diff --git a/.copilot-schema-version b/.copilot-schema-version
index 56d0dad..a700f32 100644
--- a/.copilot-schema-version
+++ b/.copilot-schema-version
@@ -1 +1 @@
-1.0.48
+1.0.49-1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0918531..6dc0ff7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,12 +4,65 @@ All notable changes to this project will be documented in this file. This change
 ## [Unreleased]
 
 ### Added (post-v1.0.0-beta.4 sync)
+- **`:session-id` on hook input maps** — `:on-hook-invoke` handlers now receive
+  a `:session-id` key on the input map. When the upstream wire payload includes
+  a `sessionId` (sub-agent hooks), the wire-provided value is preserved;
+  otherwise the SDK fills in the parent session id as a convenience.
+  (upstream PR #1290)
+- **`:cloud` session config option (create only)** — `create-session` accepts
+  an optional `:cloud` map for creating a remote cloud session. Shape:
+  `{:repository {:owner "octocat" :name "hello-world" :branch "main"}}` — `:owner`
+  and `:name` are required non-blank strings; `:branch` is optional. Forwarded on
+  the wire as `cloud.repository.*`. Matches upstream's `CloudSessionOptions` /
+  `CloudSessionRepository`. Not accepted on `resume-session` / `join-session`,
+  matching upstream `ResumeSessionConfig` (Pick excludes `cloud`).
+  (upstream PR #1306)
+- **Optional permission and tool callbacks (manual pending RPCs)** — Following
+  upstream PR #1308, `:on-permission-request` is now **optional** on
+  `create-session` and `resume-session`, and `:handler` is optional on tools
+  built via `tools/define-tool`. When omitted, the runtime no longer
+  auto-responds to permission requests or tool calls. Applications can resolve
+  these requests asynchronously via the new public functions:
+  - `sdk/handle-pending-tool-call!` / `sdk/<handle-pending-tool-call!`
+  - `sdk/handle-pending-permission-request!` / `sdk/<handle-pending-permission-request!`
+
+  Useful for human-in-the-loop UIs that surface pending tool/permission
+  requests through `sdk/get-messages` and resolve them later.
+  **Note:** This is a behavioural change — previously the SDK threw if
+  `:on-permission-request` was missing; now it's accepted and the request is
+  treated as pending until the application resolves it. (upstream PR #1308)
 - **`:agent-model` on custom-agent configs** — Custom agent maps in
   `:custom-agents` now accept an optional `:agent-model` string (e.g.
   `"claude-haiku-4.5"`). When set, the runtime attempts to use that model
   for the agent, falling back to the parent session model if unavailable.
   Forwarded on the wire as `agentModel` on each entry in `customAgents`
   for both `session.create` and `session.resume`. (upstream PR #1309)
+- **Schema bump** — `.copilot-schema-version` advanced from `1.0.48` to
+  `1.0.49-1`. Generated wire specs and coercions regenerated; new pass-through
+  event fields include `:display-prompt`, `:reasoning-summary`,
+  `:previous-reasoning-summary`. (upstream PRs #1305, #1307)
+
+### Fixed (post-v1.0.0-beta.4 sync, review iteration)
+- `::cloud-repository` spec now enforces non-blank `:name` (was just `string?`
+  via the shared `::name` spec, allowing blanks despite docs).
+- `handle-pending-tool-call!` and `<handle-pending-tool-call!` now throw when
+  neither `:result` nor `:error` is supplied (previously fell through to a
+  default "tool returned no result" payload).
+- `handle-pending-tool-call!` / `<handle-pending-tool-call!` validate that
+  `:error`, when supplied, is a string.
+- All four pending-RPC resolvers (`handle-pending-tool-call!`,
+  `<handle-pending-tool-call!`, `handle-pending-permission-request!`,
+  `<handle-pending-permission-request!`) now require `:request-id` to be a
+  non-blank string.
+- `handle-pending-permission-request!` and async variant validate that
+  `:result :kind` is a keyword in the documented decision set — matches
+  the upstream `PermissionDecision` schema:
+  `:approve-once`, `:approve-for-session`, `:approve-for-location`,
+  `:approve-permanently`, `:reject`, `:user-not-available`. Previously
+  unsupported values (e.g. `{:kind 42}`) would be sent on the wire and
+  surface as opaque server-side errors.
+- `tools/define-tool-from-spec` mirrors `tools/define-tool`: when `:handler`
+  is omitted, no `:tool-handler` wrapper is installed (declaration-only tool).
 
 ### Notes (v1.0.0-beta.4 sync)
 Upstream `v1.0.0-beta.4` shipped no new Node.js SDK API surface relative to
diff --git a/doc/reference/API.md b/doc/reference/API.md
index 73df036..2fda24c 100644
--- a/doc/reference/API.md
+++ b/doc/reference/API.md
@@ -245,7 +245,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `:commands` | vector | Command definitions (slash commands). See [Commands](#commands) |
 | `:custom-agents` | vector | Custom agent configs. Each agent map: `:agent-name` (required), `:agent-prompt` (required), `:agent-display-name`, `:agent-description`, `:agent-tools`, `:agent-infer?`, `:agent-skills` (vector of strings), `:agent-model` (string, e.g. `"claude-haiku-4.5"`; when set the runtime tries this model for the agent, falling back to the parent session model — upstream PR #1309), `:mcp-servers` |
 | `:default-agent` | map | Built-in/default agent config. Use `{:excluded-tools [...]}` to hide tools from the default agent while leaving them available to custom agents |
-| `:on-permission-request` | fn | **Required.** Permission handler function. Use `copilot/approve-all` to approve everything. |
+| `:on-permission-request` | fn | Permission handler function. **Optional** (upstream PR #1308). When omitted, permission requests are not auto-resolved; resolve them manually via `handle-pending-permission-request!`. Use `copilot/approve-all` to approve everything. |
 | `:streaming?` | boolean | Enable streaming deltas |
 | `:config-dir` | string | Override config directory for CLI |
 | `:skill-directories` | vector | Additional skill directories to load |
@@ -266,6 +266,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `:model-capabilities` | map | Model capabilities override. DeepPartial of model capabilities, e.g. `{:model-supports {:supports-vision true}}`. (upstream PR #1029) |
 | `:include-sub-agent-streaming-events?` | boolean | Forward streaming events from sub-agents to the parent session's event stream. Defaults to `true` on the wire. (upstream PR #1108) |
 | `:remote-session` | keyword | Per-session Mission Control mode: `:off`, `:export`, or `:on`. When omitted, the CLI applies its default. `:off` disables remote, `:export` exports session events to Mission Control without enabling remote steering, `:on` enables both. Forwarded as `remoteSession`. (upstream PR #1295, CLI 1.0.48) |
+| `:cloud` | map | (create-session only) Creates a remote cloud session. Shape: `{:repository {:owner "octocat" :name "hello-world" :branch "main"}}` — `:owner` and `:name` are required non-blank strings; `:branch` is optional. Forwarded as `cloud.repository.*` on `session.create`. Not accepted on `resume-session` (matches upstream `ResumeSessionConfig`). (upstream PR #1306) |
 
 #### `resume-session`
 
@@ -853,6 +854,35 @@ Abort the currently processing message.
 
 Get all events/messages from this session.
 
+#### `handle-pending-tool-call!` / `<handle-pending-tool-call!`
+
+```clojure
+(copilot/handle-pending-tool-call! session
+                                   {:request-id "tool-req-7"
+                                    :result "STATUS_OK"})
+;; or async:
+(copilot/<handle-pending-tool-call! session {:request-id "tool-req-7"
+                                             :error "lookup failed"})
+```
+
+Resolve a tool call that was not auto-handled (because `:handler` was omitted
+from `define-tool`). The args map accepts `:request-id` plus either `:result`
+(string or full result map) or `:error` (string). Sent on the wire as
+`session.tools.handlePendingToolCall`. (upstream PR #1308)
+
+#### `handle-pending-permission-request!` / `<handle-pending-permission-request!`
+
+```clojure
+(copilot/handle-pending-permission-request! session
+                                            {:request-id "perm-req-3"
+                                             :result {:kind :approve-once}})
+```
+
+Resolve a permission request that was not auto-handled (because
+`:on-permission-request` was omitted from the session config). The result map
+must contain a `:kind` other than `:no-result`. Sent on the wire as
+`session.permissions.handlePendingPermissionRequest`. (upstream PR #1308)
+
 #### `get-current-model`
 
 ```clojure
@@ -1520,6 +1550,23 @@ Let the CLI call back into your process when the model needs capabilities you pr
 
 When Copilot invokes `lookup_issue`, the SDK automatically runs your handler and responds to the CLI.
 
+**Declaration-only tools (manual resolution):**
+
+The `:handler` key is **optional** (upstream PR #1308). When omitted, the SDK does not auto-respond to tool calls — the call surfaces as a `:copilot/external_tool.requested` event with a pending request id, and the application resolves it later via `handle-pending-tool-call!`. Useful for human-in-the-loop UIs or out-of-process tool execution.
+
+```clojure
+(def manual-tool
+  (copilot/define-tool "manual_lookup"
+    {:description "Look up status manually"
+     :parameters {:type "object"
+                  :properties {:id {:type "string"}}
+                  :required ["id"]}}))
+;; …later, after a human reviews the request:
+(copilot/handle-pending-tool-call! session
+                                   {:request-id "tool-req-7"
+                                    :result "STATUS_OK"})
+```
+
 **Overriding built-in tools:**
 
 Set `:overrides-built-in-tool true` to override a built-in tool (e.g., `grep`, `edit_file`). Without this flag, defining a tool whose name clashes with a built-in tool causes an error.
@@ -1857,9 +1904,12 @@ Sessions emit `:session.compaction_start` and `:session.compaction_complete` eve
 
 The SDK uses a **deny-by-default** permission model. All permission requests
 (file writes, shell commands, URL fetches, custom tool execution, etc.) are denied unless your
-session config provides an `:on-permission-request` handler (required for
-`create-session` and `resume-session`; optional for `join-session` which
-defaults to `{:kind :no-result}`).
+session config provides an `:on-permission-request` handler. The handler is
+optional on `create-session`, `resume-session`, and `join-session` (upstream
+PR #1308): when omitted, permission requests are not auto-resolved and
+applications must resolve them via `handle-pending-permission-request!`.
+`join-session` historically defaulted to `{:kind :no-result}` and continues to
+behave that way.
 
 Use `approve-all` to opt into approving everything:
 
diff --git a/schemas/README.md b/schemas/README.md
index b239b19..49b68f1 100644
--- a/schemas/README.md
+++ b/schemas/README.md
@@ -4,4 +4,4 @@ These files are fetched verbatim from the `@github/copilot` npm package at the v
 
 **Do not edit by hand.** To update, run `bb schemas:fetch` after bumping `.copilot-schema-version`.
 
-Currently pinned version: `1.0.48`
+Currently pinned version: `1.0.49-1`
diff --git a/schemas/api.schema.json b/schemas/api.schema.json
index 30250b9..7e23234 100644
--- a/schemas/api.schema.json
+++ b/schemas/api.schema.json
@@ -5,53 +5,68 @@
   "server": {
     "ping": {
       "rpcMethod": "ping",
+      "description": "Checks server responsiveness and returns protocol information.",
       "params": {
-        "$ref": "#/definitions/PingRequest"
+        "$ref": "#/definitions/PingRequest",
+        "description": "Optional message to echo back to the caller."
       },
       "result": {
-        "$ref": "#/definitions/PingResult"
+        "$ref": "#/definitions/PingResult",
+        "description": "Server liveness response, including the echoed message, current timestamp, and protocol version."
       }
     },
     "connect": {
       "rpcMethod": "connect",
+      "description": "Performs the SDK server connection handshake and validates the optional connection token.",
       "params": {
-        "$ref": "#/definitions/ConnectRequest"
+        "$ref": "#/definitions/ConnectRequest",
+        "description": "Optional connection token presented by the SDK client during the handshake."
       },
       "result": {
-        "$ref": "#/definitions/ConnectResult"
+        "$ref": "#/definitions/ConnectResult",
+        "description": "Handshake result reporting the server's protocol version and package version on success."
       },
       "visibility": "internal"
     },
     "models": {
       "list": {
         "rpcMethod": "models.list",
+        "description": "Lists Copilot models available to the authenticated user.",
         "params": {
-          "$ref": "#/definitions/ModelsListRequest"
+          "$ref": "#/definitions/ModelsListRequest",
+          "description": "Optional GitHub token used to list models for a specific user instead of the global auth context."
         },
         "result": {
-          "$ref": "#/definitions/ModelList"
+          "$ref": "#/definitions/ModelList",
+          "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata."
         }
       }
     },
     "tools": {
       "list": {
         "rpcMethod": "tools.list",
+        "description": "Lists built-in tools available for a model.",
         "params": {
-          "$ref": "#/definitions/ToolsListRequest"
+          "$ref": "#/definitions/ToolsListRequest",
+          "description": "Optional model identifier whose tool overrides should be applied to the listing."
         },
         "result": {
-          "$ref": "#/definitions/ToolList"
+          "$ref": "#/definitions/ToolList",
+          "description": "Built-in tools available for the requested model, with their parameters and instructions."
         }
       }
     },
     "account": {
       "getQuota": {
         "rpcMethod": "account.getQuota",
+        "description": "Gets Copilot quota usage for the authenticated user or supplied GitHub token.",
         "params": {
-          "$ref": "#/definitions/AccountGetQuotaRequest"
+          "$ref": "#/definitions/AccountGetQuotaRequest",
+          "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context."
         },
         "result": {
-          "$ref": "#/definitions/AccountGetQuotaResult"
+          "$ref": "#/definitions/AccountGetQuotaResult",
+          "description": "Quota usage snapshots for the resolved user, keyed by quota type."
         }
       }
     },
@@ -59,69 +74,79 @@
       "config": {
         "list": {
           "rpcMethod": "mcp.config.list",
+          "description": "Lists MCP servers from user configuration.",
           "params": null,
           "result": {
-            "$ref": "#/definitions/McpConfigList"
+            "$ref": "#/definitions/McpConfigList",
+            "description": "User-configured MCP servers, keyed by server name."
           }
         },
         "add": {
           "rpcMethod": "mcp.config.add",
+          "description": "Adds an MCP server to user configuration.",
           "params": {
-            "$ref": "#/definitions/McpConfigAddRequest"
+            "$ref": "#/definitions/McpConfigAddRequest",
+            "description": "MCP server name and configuration to add to user configuration."
           },
           "result": {
-            "type": "null",
-            "title": "McpConfigAddResult"
+            "type": "null"
           }
         },
         "update": {
           "rpcMethod": "mcp.config.update",
+          "description": "Updates an MCP server in user configuration.",
           "params": {
-            "$ref": "#/definitions/McpConfigUpdateRequest"
+            "$ref": "#/definitions/McpConfigUpdateRequest",
+            "description": "MCP server name and replacement configuration to write to user configuration."
           },
           "result": {
-            "type": "null",
-            "title": "McpConfigUpdateResult"
+            "type": "null"
           }
         },
         "remove": {
           "rpcMethod": "mcp.config.remove",
+          "description": "Removes an MCP server from user configuration.",
           "params": {
-            "$ref": "#/definitions/McpConfigRemoveRequest"
+            "$ref": "#/definitions/McpConfigRemoveRequest",
+            "description": "MCP server name to remove from user configuration."
           },
           "result": {
-            "type": "null",
-            "title": "McpConfigRemoveResult"
+            "type": "null"
           }
         },
         "enable": {
           "rpcMethod": "mcp.config.enable",
+          "description": "Enables MCP servers in user configuration for new sessions.",
           "params": {
-            "$ref": "#/definitions/McpConfigEnableRequest"
+            "$ref": "#/definitions/McpConfigEnableRequest",
+            "description": "MCP server names to enable for new sessions."
           },
           "result": {
-            "type": "null",
-            "title": "McpConfigEnableResult"
+            "type": "null"
           }
         },
         "disable": {
           "rpcMethod": "mcp.config.disable",
+          "description": "Disables MCP servers in user configuration for new sessions.",
           "params": {
-            "$ref": "#/definitions/McpConfigDisableRequest"
+            "$ref": "#/definitions/McpConfigDisableRequest",
+            "description": "MCP server names to disable for new sessions."
           },
           "result": {
-            "type": "null",
-            "title": "McpConfigDisableResult"
+            "type": "null"
           }
         }
       },
       "discover": {
         "rpcMethod": "mcp.discover",
+        "description": "Discovers MCP servers from user, workspace, plugin, and builtin sources.",
         "params": {
-          "$ref": "#/definitions/McpDiscoverRequest"
+          "$ref": "#/definitions/McpDiscoverRequest",
+          "description": "Optional working directory used as context for MCP server discovery."
         },
         "result": {
-          "$ref": "#/definitions/McpDiscoverResult"
+          "$ref": "#/definitions/McpDiscoverResult",
+          "description": "MCP servers discovered from user, workspace, plugin, and built-in sources."
         }
       }
     },
@@ -129,44 +154,67 @@
       "config": {
         "setDisabledSkills": {
           "rpcMethod": "skills.config.setDisabledSkills",
+          "description": "Replaces the global list of disabled skills.",
           "params": {
-            "$ref": "#/definitions/SkillsConfigSetDisabledSkillsRequest"
+            "$ref": "#/definitions/SkillsConfigSetDisabledSkillsRequest",
+            "description": "Skill names to mark as disabled in global configuration, replacing any previous list."
           },
           "result": {
-            "type": "null",
-            "title": "SkillsConfigSetDisabledSkillsResult"
+            "type": "null"
           }
         }
       },
       "discover": {
         "rpcMethod": "skills.discover",
+        "description": "Discovers skills across global and project sources.",
         "params": {
-          "$ref": "#/definitions/SkillsDiscoverRequest"
+          "$ref": "#/definitions/SkillsDiscoverRequest",
+          "description": "Optional project paths and additional skill directories to include in discovery."
         },
         "result": {
-          "$ref": "#/definitions/ServerSkillList"
+          "$ref": "#/definitions/ServerSkillList",
+          "description": "Skills discovered across global and project sources."
         }
       }
     },
     "sessionFs": {
       "setProvider": {
         "rpcMethod": "sessionFs.setProvider",
+        "description": "Registers an SDK client as the session filesystem provider.",
         "params": {
-          "$ref": "#/definitions/SessionFsSetProviderRequest"
+          "$ref": "#/definitions/SessionFsSetProviderRequest",
+          "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider."
         },
         "result": {
-          "$ref": "#/definitions/SessionFsSetProviderResult"
+          "$ref": "#/definitions/SessionFsSetProviderResult",
+          "description": "Indicates whether the calling client was registered as the session filesystem provider."
         }
       }
     },
     "sessions": {
       "fork": {
         "rpcMethod": "sessions.fork",
+        "description": "Creates a new session by forking persisted history from an existing session.",
         "params": {
-          "$ref": "#/definitions/SessionsForkRequest"
+          "$ref": "#/definitions/SessionsForkRequest",
+          "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session."
         },
         "result": {
-          "$ref": "#/definitions/SessionsForkResult"
+          "$ref": "#/definitions/SessionsForkResult",
+          "description": "Identifier and optional friendly name assigned to the newly forked session."
+        },
+        "stability": "experimental"
+      },
+      "connect": {
+        "rpcMethod": "sessions.connect",
+        "description": "Connects to an existing remote session and exposes it as an SDK session.",
+        "params": {
+          "$ref": "#/definitions/ConnectRemoteSessionParams",
+          "description": "Remote session connection parameters."
+        },
+        "result": {
+          "$ref": "#/definitions/RemoteSessionConnectionResult",
+          "description": "Remote session connection result."
         },
         "stability": "experimental"
       }
@@ -175,8 +223,10 @@
   "session": {
     "suspend": {
       "rpcMethod": "session.suspend",
+      "description": "Suspends the session while preserving persisted state for later resume.",
       "params": {
         "type": "object",
+        "description": "Identifies the target session.",
         "properties": {
           "sessionId": {
             "type": "string",
@@ -189,15 +239,16 @@
         "additionalProperties": false
       },
       "result": {
-        "type": "null",
-        "title": "SuspendResult"
+        "type": "null"
       }
     },
     "auth": {
       "getStatus": {
         "rpcMethod": "session.auth.getStatus",
+        "description": "Gets authentication status and account metadata for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -210,15 +261,18 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/SessionAuthStatus"
+          "$ref": "#/definitions/SessionAuthStatus",
+          "description": "Authentication status and account metadata for the session."
         }
       }
     },
     "model": {
       "getCurrent": {
         "rpcMethod": "session.model.getCurrent",
+        "description": "Gets the currently selected model for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -231,11 +285,13 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/CurrentModel"
+          "$ref": "#/definitions/CurrentModel",
+          "description": "The currently selected model for the session."
         }
       },
       "switchTo": {
         "rpcMethod": "session.model.switchTo",
+        "description": "Switches the session to a model and optional reasoning configuration.",
         "params": {
           "type": "object",
           "properties": {
@@ -249,7 +305,11 @@
             },
             "reasoningEffort": {
               "type": "string",
-              "description": "Reasoning effort level to use for the model"
+              "description": "Reasoning effort level to use for the model. \"none\" disables reasoning."
+            },
+            "reasoningSummary": {
+              "$ref": "#/definitions/ReasoningSummary",
+              "description": "Reasoning summary mode to request for supported model clients"
             },
             "modelCapabilities": {
               "$ref": "#/definitions/ModelCapabilitiesOverride",
@@ -261,18 +321,22 @@
             "modelId"
           ],
           "additionalProperties": false,
+          "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.",
           "title": "ModelSwitchToRequest"
         },
         "result": {
-          "$ref": "#/definitions/ModelSwitchToResult"
+          "$ref": "#/definitions/ModelSwitchToResult",
+          "description": "The model identifier active on the session after the switch."
         }
       }
     },
     "mode": {
       "get": {
         "rpcMethod": "session.mode.get",
+        "description": "Gets the current agent interaction mode.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -291,6 +355,7 @@
       },
       "set": {
         "rpcMethod": "session.mode.set",
+        "description": "Sets the current agent interaction mode.",
         "params": {
           "type": "object",
           "properties": {
@@ -308,19 +373,21 @@
             "mode"
           ],
           "additionalProperties": false,
+          "description": "Agent interaction mode to apply to the session.",
           "title": "ModeSetRequest"
         },
         "result": {
-          "type": "null",
-          "title": "ModeSetResult"
+          "type": "null"
         }
       }
     },
     "name": {
       "get": {
         "rpcMethod": "session.name.get",
+        "description": "Gets the session's friendly name.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -333,11 +400,13 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/NameGetResult"
+          "$ref": "#/definitions/NameGetResult",
+          "description": "The session's friendly name, or null when not yet set."
         }
       },
       "set": {
         "rpcMethod": "session.name.set",
+        "description": "Sets the session's friendly name.",
         "params": {
           "type": "object",
           "properties": {
@@ -357,19 +426,21 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "New friendly name to apply to the session.",
           "title": "NameSetRequest"
         },
         "result": {
-          "type": "null",
-          "title": "NameSetResult"
+          "type": "null"
         }
       }
     },
     "plan": {
       "read": {
         "rpcMethod": "session.plan.read",
+        "description": "Reads the session plan file from the workspace.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -382,11 +453,13 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/PlanReadResult"
+          "$ref": "#/definitions/PlanReadResult",
+          "description": "Existence, contents, and resolved path of the session plan file."
         }
       },
       "update": {
         "rpcMethod": "session.plan.update",
+        "description": "Writes new content to the session plan file.",
         "params": {
           "type": "object",
           "properties": {
@@ -404,17 +477,19 @@
             "content"
           ],
           "additionalProperties": false,
+          "description": "Replacement contents to write to the session plan file.",
           "title": "PlanUpdateRequest"
         },
         "result": {
-          "type": "null",
-          "title": "PlanUpdateResult"
+          "type": "null"
         }
       },
       "delete": {
         "rpcMethod": "session.plan.delete",
+        "description": "Deletes the session plan file from the workspace.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -427,16 +502,17 @@
           "additionalProperties": false
         },
         "result": {
-          "type": "null",
-          "title": "PlanDeleteResult"
+          "type": "null"
         }
       }
     },
     "workspaces": {
       "getWorkspace": {
         "rpcMethod": "session.workspaces.getWorkspace",
+        "description": "Gets current workspace metadata for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -449,13 +525,16 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/WorkspacesGetWorkspaceResult"
+          "$ref": "#/definitions/WorkspacesGetWorkspaceResult",
+          "description": "Current workspace metadata for the session, or null when not available."
         }
       },
       "listFiles": {
         "rpcMethod": "session.workspaces.listFiles",
+        "description": "Lists files stored in the session workspace files directory.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -468,11 +547,13 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/WorkspacesListFilesResult"
+          "$ref": "#/definitions/WorkspacesListFilesResult",
+          "description": "Relative paths of files stored in the session workspace files directory."
         }
       },
       "readFile": {
         "rpcMethod": "session.workspaces.readFile",
+        "description": "Reads a file from the session workspace files directory.",
         "params": {
           "type": "object",
           "properties": {
@@ -490,14 +571,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Relative path of the workspace file to read.",
           "title": "WorkspacesReadFileRequest"
         },
         "result": {
-          "$ref": "#/definitions/WorkspacesReadFileResult"
+          "$ref": "#/definitions/WorkspacesReadFileResult",
+          "description": "Contents of the requested workspace file as a UTF-8 string."
         }
       },
       "createFile": {
         "rpcMethod": "session.workspaces.createFile",
+        "description": "Creates or overwrites a file in the session workspace files directory.",
         "params": {
           "type": "object",
           "properties": {
@@ -520,19 +604,21 @@
             "content"
           ],
           "additionalProperties": false,
+          "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.",
           "title": "WorkspacesCreateFileRequest"
         },
         "result": {
-          "type": "null",
-          "title": "WorkspacesCreateFileResult"
+          "type": "null"
         }
       }
     },
     "instructions": {
       "getSources": {
         "rpcMethod": "session.instructions.getSources",
+        "description": "Gets instruction sources loaded for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -545,13 +631,15 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/InstructionsGetSourcesResult"
+          "$ref": "#/definitions/InstructionsGetSourcesResult",
+          "description": "Instruction sources loaded for the session, in merge order."
         }
       }
     },
     "fleet": {
       "start": {
         "rpcMethod": "session.fleet.start",
+        "description": "Starts fleet mode by submitting the fleet orchestration prompt to the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -565,13 +653,15 @@
             }
           },
           "additionalProperties": false,
+          "description": "Optional user prompt to combine with the fleet orchestration instructions.",
           "title": "FleetStartRequest",
           "required": [
             "sessionId"
           ]
         },
         "result": {
-          "$ref": "#/definitions/FleetStartResult"
+          "$ref": "#/definitions/FleetStartResult",
+          "description": "Indicates whether fleet mode was successfully activated."
         },
         "stability": "experimental"
       }
@@ -579,8 +669,10 @@
     "agent": {
       "list": {
         "rpcMethod": "session.agent.list",
+        "description": "Lists custom agents available to the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -593,14 +685,17 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/AgentList"
+          "$ref": "#/definitions/AgentList",
+          "description": "Custom agents available to the session."
         },
         "stability": "experimental"
       },
       "getCurrent": {
         "rpcMethod": "session.agent.getCurrent",
+        "description": "Gets the currently selected custom agent for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -613,12 +708,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/AgentGetCurrentResult"
+          "$ref": "#/definitions/AgentGetCurrentResult",
+          "description": "The currently selected custom agent, or null when using the default agent."
         },
         "stability": "experimental"
       },
       "select": {
         "rpcMethod": "session.agent.select",
+        "description": "Selects a custom agent for subsequent turns in the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -636,17 +733,21 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "Name of the custom agent to select for subsequent turns.",
           "title": "AgentSelectRequest"
         },
         "result": {
-          "$ref": "#/definitions/AgentSelectResult"
+          "$ref": "#/definitions/AgentSelectResult",
+          "description": "The newly selected custom agent."
         },
         "stability": "experimental"
       },
       "deselect": {
         "rpcMethod": "session.agent.deselect",
+        "description": "Clears the selected custom agent and returns the session to the default agent.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -659,15 +760,16 @@
           "additionalProperties": false
         },
         "result": {
-          "type": "null",
-          "title": "AgentDeselectResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "reload": {
         "rpcMethod": "session.agent.reload",
+        "description": "Reloads custom agent definitions and returns the refreshed list.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -680,7 +782,8 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/AgentReloadResult"
+          "$ref": "#/definitions/AgentReloadResult",
+          "description": "Custom agents available to the session after reloading definitions from disk."
         },
         "stability": "experimental"
       }
@@ -688,6 +791,7 @@
     "tasks": {
       "startAgent": {
         "rpcMethod": "session.tasks.startAgent",
+        "description": "Starts a background agent task in the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -723,17 +827,21 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "Agent type, prompt, name, and optional description and model override for the new task.",
           "title": "TasksStartAgentRequest"
         },
         "result": {
-          "$ref": "#/definitions/TasksStartAgentResult"
+          "$ref": "#/definitions/TasksStartAgentResult",
+          "description": "Identifier assigned to the newly started background agent task."
         },
         "stability": "experimental"
       },
       "list": {
         "rpcMethod": "session.tasks.list",
+        "description": "Lists background tasks tracked by the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -746,12 +854,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/TaskList"
+          "$ref": "#/definitions/TaskList",
+          "description": "Background tasks currently tracked by the session."
         },
         "stability": "experimental"
       },
       "promoteToBackground": {
         "rpcMethod": "session.tasks.promoteToBackground",
+        "description": "Promotes an eligible synchronously-waited task so it continues running in the background.",
         "params": {
           "type": "object",
           "properties": {
@@ -769,15 +879,18 @@
             "id"
           ],
           "additionalProperties": false,
+          "description": "Identifier of the task to promote to background mode.",
           "title": "TasksPromoteToBackgroundRequest"
         },
         "result": {
-          "$ref": "#/definitions/TasksPromoteToBackgroundResult"
+          "$ref": "#/definitions/TasksPromoteToBackgroundResult",
+          "description": "Indicates whether the task was successfully promoted to background mode."
         },
         "stability": "experimental"
       },
       "cancel": {
         "rpcMethod": "session.tasks.cancel",
+        "description": "Cancels a background task.",
         "params": {
           "type": "object",
           "properties": {
@@ -795,15 +908,18 @@
             "id"
           ],
           "additionalProperties": false,
+          "description": "Identifier of the background task to cancel.",
           "title": "TasksCancelRequest"
         },
         "result": {
-          "$ref": "#/definitions/TasksCancelResult"
+          "$ref": "#/definitions/TasksCancelResult",
+          "description": "Indicates whether the background task was successfully cancelled."
         },
         "stability": "experimental"
       },
       "remove": {
         "rpcMethod": "session.tasks.remove",
+        "description": "Removes a completed or cancelled background task from tracking.",
         "params": {
           "type": "object",
           "properties": {
@@ -821,15 +937,18 @@
             "id"
           ],
           "additionalProperties": false,
+          "description": "Identifier of the completed or cancelled task to remove from tracking.",
           "title": "TasksRemoveRequest"
         },
         "result": {
-          "$ref": "#/definitions/TasksRemoveResult"
+          "$ref": "#/definitions/TasksRemoveResult",
+          "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle."
         },
         "stability": "experimental"
       },
       "sendMessage": {
         "rpcMethod": "session.tasks.sendMessage",
+        "description": "Sends a message to a background agent task.",
         "params": {
           "type": "object",
           "properties": {
@@ -856,10 +975,12 @@
             "message"
           ],
           "additionalProperties": false,
+          "description": "Identifier of the target agent task, message content, and optional sender agent ID.",
           "title": "TasksSendMessageRequest"
         },
         "result": {
-          "$ref": "#/definitions/TasksSendMessageResult"
+          "$ref": "#/definitions/TasksSendMessageResult",
+          "description": "Indicates whether the message was delivered, with an error message when delivery failed."
         },
         "stability": "experimental"
       }
@@ -867,8 +988,10 @@
     "skills": {
       "list": {
         "rpcMethod": "session.skills.list",
+        "description": "Lists skills available to the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -881,12 +1004,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/SkillList"
+          "$ref": "#/definitions/SkillList",
+          "description": "Skills available to the session, with their enabled state."
         },
         "stability": "experimental"
       },
       "enable": {
         "rpcMethod": "session.skills.enable",
+        "description": "Enables a skill for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -904,16 +1029,17 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "Name of the skill to enable for the session.",
           "title": "SkillsEnableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "SkillsEnableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "disable": {
         "rpcMethod": "session.skills.disable",
+        "description": "Disables a skill for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -931,18 +1057,20 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "Name of the skill to disable for the session.",
           "title": "SkillsDisableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "SkillsDisableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "reload": {
         "rpcMethod": "session.skills.reload",
+        "description": "Reloads skill definitions for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -955,7 +1083,8 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/SkillsLoadDiagnostics"
+          "$ref": "#/definitions/SkillsLoadDiagnostics",
+          "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists."
         },
         "stability": "experimental"
       }
@@ -963,8 +1092,10 @@
     "mcp": {
       "list": {
         "rpcMethod": "session.mcp.list",
+        "description": "Lists MCP servers configured for the session and their connection status.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -977,12 +1108,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/McpServerList"
+          "$ref": "#/definitions/McpServerList",
+          "description": "MCP servers configured for the session, with their connection status."
         },
         "stability": "experimental"
       },
       "enable": {
         "rpcMethod": "session.mcp.enable",
+        "description": "Enables an MCP server for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1002,16 +1135,17 @@
             "serverName"
           ],
           "additionalProperties": false,
+          "description": "Name of the MCP server to enable for the session.",
           "title": "McpEnableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "McpEnableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "disable": {
         "rpcMethod": "session.mcp.disable",
+        "description": "Disables an MCP server for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1031,18 +1165,20 @@
             "serverName"
           ],
           "additionalProperties": false,
+          "description": "Name of the MCP server to disable for the session.",
           "title": "McpDisableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "McpDisableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "reload": {
         "rpcMethod": "session.mcp.reload",
+        "description": "Reloads MCP server connections for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1055,14 +1191,14 @@
           "additionalProperties": false
         },
         "result": {
-          "type": "null",
-          "title": "McpReloadResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "oauth": {
         "login": {
           "rpcMethod": "session.mcp.oauth.login",
+          "description": "Starts OAuth authentication for a remote MCP server.",
           "params": {
             "type": "object",
             "properties": {
@@ -1094,10 +1230,12 @@
               "serverName"
             ],
             "additionalProperties": false,
+            "description": "Remote MCP server name and optional overrides controlling reauthentication, OAuth client display name, and the callback success-page copy.",
             "title": "McpOauthLoginRequest"
           },
           "result": {
-            "$ref": "#/definitions/McpOauthLoginResult"
+            "$ref": "#/definitions/McpOauthLoginResult",
+            "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server."
           },
           "stability": "experimental"
         }
@@ -1106,8 +1244,10 @@
     "plugins": {
       "list": {
         "rpcMethod": "session.plugins.list",
+        "description": "Lists plugins installed for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1120,7 +1260,8 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/PluginList"
+          "$ref": "#/definitions/PluginList",
+          "description": "Plugins installed for the session, with their enabled state and version metadata."
         },
         "stability": "experimental"
       }
@@ -1128,8 +1269,10 @@
     "extensions": {
       "list": {
         "rpcMethod": "session.extensions.list",
+        "description": "Lists extensions discovered for the session and their current status.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1142,12 +1285,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/ExtensionList"
+          "$ref": "#/definitions/ExtensionList",
+          "description": "Extensions discovered for the session, with their current status."
         },
         "stability": "experimental"
       },
       "enable": {
         "rpcMethod": "session.extensions.enable",
+        "description": "Enables an extension for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1165,16 +1310,17 @@
             "id"
           ],
           "additionalProperties": false,
+          "description": "Source-qualified extension identifier to enable for the session.",
           "title": "ExtensionsEnableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "ExtensionsEnableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "disable": {
         "rpcMethod": "session.extensions.disable",
+        "description": "Disables an extension for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1192,18 +1338,20 @@
             "id"
           ],
           "additionalProperties": false,
+          "description": "Source-qualified extension identifier to disable for the session.",
           "title": "ExtensionsDisableRequest"
         },
         "result": {
-          "type": "null",
-          "title": "ExtensionsDisableResult"
+          "type": "null"
         },
         "stability": "experimental"
       },
       "reload": {
         "rpcMethod": "session.extensions.reload",
+        "description": "Reloads extension definitions and processes for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1216,8 +1364,7 @@
           "additionalProperties": false
         },
         "result": {
-          "type": "null",
-          "title": "ExtensionsReloadResult"
+          "type": "null"
         },
         "stability": "experimental"
       }
@@ -1225,6 +1372,7 @@
     "tools": {
       "handlePendingToolCall": {
         "rpcMethod": "session.tools.handlePendingToolCall",
+        "description": "Provides the result for a pending external tool call.",
         "params": {
           "type": "object",
           "properties": {
@@ -1250,16 +1398,19 @@
             "requestId"
           ],
           "additionalProperties": false,
+          "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.",
           "title": "HandlePendingToolCallRequest"
         },
         "result": {
-          "$ref": "#/definitions/HandlePendingToolCallResult"
+          "$ref": "#/definitions/HandlePendingToolCallResult",
+          "description": "Indicates whether the external tool call result was handled successfully."
         }
       }
     },
     "commands": {
       "list": {
         "rpcMethod": "session.commands.list",
+        "description": "Lists slash commands available in the session.",
         "params": {
           "anyOf": [
             {
@@ -1284,6 +1435,7 @@
               "additionalProperties": false
             }
           ],
+          "description": "Optional filters controlling which command sources to include in the listing.",
           "title": "CommandsListRequest",
           "properties": {
             "sessionId": {
@@ -1296,11 +1448,13 @@
           ]
         },
         "result": {
-          "$ref": "#/definitions/CommandList"
+          "$ref": "#/definitions/CommandList",
+          "description": "Slash commands available in the session, after applying any include/exclude filters."
         }
       },
       "invoke": {
         "rpcMethod": "session.commands.invoke",
+        "description": "Invokes a slash command in the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1322,14 +1476,17 @@
             "name"
           ],
           "additionalProperties": false,
+          "description": "Slash command name and optional raw input string to invoke.",
           "title": "CommandsInvokeRequest"
         },
         "result": {
-          "$ref": "#/definitions/SlashCommandInvocationResult"
+          "$ref": "#/definitions/SlashCommandInvocationResult",
+          "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion)."
         }
       },
       "handlePendingCommand": {
         "rpcMethod": "session.commands.handlePendingCommand",
+        "description": "Reports completion of a pending client-handled slash command.",
         "params": {
           "type": "object",
           "properties": {
@@ -1351,14 +1508,17 @@
             "requestId"
           ],
           "additionalProperties": false,
+          "description": "Pending command request ID and an optional error if the client handler failed.",
           "title": "CommandsHandlePendingCommandRequest"
         },
         "result": {
-          "$ref": "#/definitions/CommandsHandlePendingCommandResult"
+          "$ref": "#/definitions/CommandsHandlePendingCommandResult",
+          "description": "Indicates whether the pending client-handled command was completed successfully."
         }
       },
       "respondToQueuedCommand": {
         "rpcMethod": "session.commands.respondToQueuedCommand",
+        "description": "Responds to a queued command request from the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1381,16 +1541,19 @@
             "result"
           ],
           "additionalProperties": false,
+          "description": "Queued command request ID and the result indicating whether the client handled it.",
           "title": "CommandsRespondToQueuedCommandRequest"
         },
         "result": {
-          "$ref": "#/definitions/CommandsRespondToQueuedCommandResult"
+          "$ref": "#/definitions/CommandsRespondToQueuedCommandResult",
+          "description": "Indicates whether the queued-command response was accepted by the session."
         }
       }
     },
     "ui": {
       "elicitation": {
         "rpcMethod": "session.ui.elicitation",
+        "description": "Requests structured input from a UI-capable client.",
         "params": {
           "type": "object",
           "properties": {
@@ -1413,6 +1576,7 @@
             "requestedSchema"
           ],
           "additionalProperties": false,
+          "description": "Prompt message and JSON schema describing the form fields to elicit from the user.",
           "title": "UIElicitationRequest"
         },
         "result": {
@@ -1422,6 +1586,7 @@
       },
       "handlePendingElicitation": {
         "rpcMethod": "session.ui.handlePendingElicitation",
+        "description": "Provides the user response for a pending elicitation request.",
         "params": {
           "type": "object",
           "properties": {
@@ -1444,16 +1609,19 @@
             "result"
           ],
           "additionalProperties": false,
+          "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).",
           "title": "UIHandlePendingElicitationRequest"
         },
         "result": {
-          "$ref": "#/definitions/UIElicitationResult"
+          "$ref": "#/definitions/UIElicitationResult",
+          "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client."
         }
       }
     },
     "permissions": {
       "handlePendingPermissionRequest": {
         "rpcMethod": "session.permissions.handlePendingPermissionRequest",
+        "description": "Provides a decision for a pending tool permission request.",
         "params": {
           "type": "object",
           "properties": {
@@ -1466,7 +1634,8 @@
               "description": "Request ID of the pending permission request"
             },
             "result": {
-              "$ref": "#/definitions/PermissionDecision"
+              "$ref": "#/definitions/PermissionDecision",
+              "description": "Decision to apply to a pending permission request."
             }
           },
           "required": [
@@ -1475,14 +1644,17 @@
             "result"
           ],
           "additionalProperties": false,
+          "description": "Pending permission request ID and the decision to apply (approve/reject and scope).",
           "title": "PermissionDecisionRequest"
         },
         "result": {
-          "$ref": "#/definitions/PermissionRequestResult"
+          "$ref": "#/definitions/PermissionRequestResult",
+          "description": "Indicates whether the permission decision was applied; false when the request was already resolved."
         }
       },
       "setApproveAll": {
         "rpcMethod": "session.permissions.setApproveAll",
+        "description": "Enables or disables automatic approval of tool permission requests for the session.",
         "params": {
           "type": "object",
           "properties": {
@@ -1500,14 +1672,17 @@
             "enabled"
           ],
           "additionalProperties": false,
+          "description": "Whether to auto-approve all tool permission requests for the rest of the session.",
           "title": "PermissionsSetApproveAllRequest"
         },
         "result": {
-          "$ref": "#/definitions/PermissionsSetApproveAllResult"
+          "$ref": "#/definitions/PermissionsSetApproveAllResult",
+          "description": "Indicates whether the operation succeeded."
         }
       },
       "resetSessionApprovals": {
         "rpcMethod": "session.permissions.resetSessionApprovals",
+        "description": "Clears session-scoped tool permission approvals.",
         "params": {
           "type": "object",
           "properties": {
@@ -1517,18 +1692,21 @@
             }
           },
           "additionalProperties": false,
+          "description": "No parameters; clears all session-scoped tool permission approvals.",
           "title": "PermissionsResetSessionApprovalsRequest",
           "required": [
             "sessionId"
           ]
         },
         "result": {
-          "$ref": "#/definitions/PermissionsResetSessionApprovalsResult"
+          "$ref": "#/definitions/PermissionsResetSessionApprovalsResult",
+          "description": "Indicates whether the operation succeeded."
         }
       }
     },
     "log": {
       "rpcMethod": "session.log",
+      "description": "Emits a user-visible session log event.",
       "params": {
         "type": "object",
         "properties": {
@@ -1559,15 +1737,18 @@
           "message"
         ],
         "additionalProperties": false,
+        "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.",
         "title": "LogRequest"
       },
       "result": {
-        "$ref": "#/definitions/LogResult"
+        "$ref": "#/definitions/LogResult",
+        "description": "Identifier of the session event that was emitted for the log message."
       }
     },
     "shell": {
       "exec": {
         "rpcMethod": "session.shell.exec",
+        "description": "Starts a shell command and streams output through session notifications.",
         "params": {
           "type": "object",
           "properties": {
@@ -1595,14 +1776,17 @@
             "command"
           ],
           "additionalProperties": false,
+          "description": "Shell command to run, with optional working directory and timeout in milliseconds.",
           "title": "ShellExecRequest"
         },
         "result": {
-          "$ref": "#/definitions/ShellExecResult"
+          "$ref": "#/definitions/ShellExecResult",
+          "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications."
         }
       },
       "kill": {
         "rpcMethod": "session.shell.kill",
+        "description": "Sends a signal to a shell process previously started via \"shell.exec\".",
         "params": {
           "type": "object",
           "properties": {
@@ -1624,18 +1808,22 @@
             "processId"
           ],
           "additionalProperties": false,
+          "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.",
           "title": "ShellKillRequest"
         },
         "result": {
-          "$ref": "#/definitions/ShellKillResult"
+          "$ref": "#/definitions/ShellKillResult",
+          "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited."
         }
       }
     },
     "history": {
       "compact": {
         "rpcMethod": "session.history.compact",
+        "description": "Compacts the session history to reduce context usage.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1648,12 +1836,14 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/HistoryCompactResult"
+          "$ref": "#/definitions/HistoryCompactResult",
+          "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown."
         },
         "stability": "experimental"
       },
       "truncate": {
         "rpcMethod": "session.history.truncate",
+        "description": "Truncates persisted session history to a specific event.",
         "params": {
           "type": "object",
           "properties": {
@@ -1671,10 +1861,12 @@
             "eventId"
           ],
           "additionalProperties": false,
+          "description": "Identifier of the event to truncate to; this event and all later events are removed.",
           "title": "HistoryTruncateRequest"
         },
         "result": {
-          "$ref": "#/definitions/HistoryTruncateResult"
+          "$ref": "#/definitions/HistoryTruncateResult",
+          "description": "Number of events that were removed by the truncation."
         },
         "stability": "experimental"
       }
@@ -1682,8 +1874,10 @@
     "usage": {
       "getMetrics": {
         "rpcMethod": "session.usage.getMetrics",
+        "description": "Gets accumulated usage metrics for the session.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1696,7 +1890,8 @@
           "additionalProperties": false
         },
         "result": {
-          "$ref": "#/definitions/UsageGetMetricsResult"
+          "$ref": "#/definitions/UsageGetMetricsResult",
+          "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals."
         },
         "stability": "experimental"
       }
@@ -1704,6 +1899,7 @@
     "remote": {
       "enable": {
         "rpcMethod": "session.remote.enable",
+        "description": "Enables remote session export or steering.",
         "params": {
           "type": "object",
           "properties": {
@@ -1713,24 +1909,28 @@
             },
             "mode": {
               "$ref": "#/definitions/RemoteSessionMode",
-              "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering."
+              "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering."
             }
           },
           "additionalProperties": false,
+          "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.",
           "title": "RemoteEnableRequest",
           "required": [
             "sessionId"
           ]
         },
         "result": {
-          "$ref": "#/definitions/RemoteEnableResult"
+          "$ref": "#/definitions/RemoteEnableResult",
+          "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled."
         },
         "stability": "experimental"
       },
       "disable": {
         "rpcMethod": "session.remote.disable",
+        "description": "Disables remote session export and steering.",
         "params": {
           "type": "object",
+          "description": "Identifies the target session.",
           "properties": {
             "sessionId": {
               "type": "string",
@@ -1743,8 +1943,7 @@
           "additionalProperties": false
         },
         "result": {
-          "type": "null",
-          "title": "RemoteDisableResult"
+          "type": "null"
         },
         "stability": "experimental"
       }
@@ -1754,6 +1953,7 @@
     "sessionFs": {
       "readFile": {
         "rpcMethod": "sessionFs.readFile",
+        "description": "Reads a file from the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1771,14 +1971,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Path of the file to read from the client-provided session filesystem.",
           "title": "SessionFsReadFileRequest"
         },
         "result": {
-          "$ref": "#/definitions/SessionFsReadFileResult"
+          "$ref": "#/definitions/SessionFsReadFileResult",
+          "description": "File content as a UTF-8 string, or a filesystem error if the read failed."
         }
       },
       "writeFile": {
         "rpcMethod": "sessionFs.writeFile",
+        "description": "Writes a file in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1806,6 +2009,7 @@
             "content"
           ],
           "additionalProperties": false,
+          "description": "File path, content to write, and optional mode for the client-provided session filesystem.",
           "title": "SessionFsWriteFileRequest"
         },
         "result": {
@@ -1823,6 +2027,7 @@
       },
       "appendFile": {
         "rpcMethod": "sessionFs.appendFile",
+        "description": "Appends content to a file in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1850,6 +2055,7 @@
             "content"
           ],
           "additionalProperties": false,
+          "description": "File path, content to append, and optional mode for the client-provided session filesystem.",
           "title": "SessionFsAppendFileRequest"
         },
         "result": {
@@ -1867,6 +2073,7 @@
       },
       "exists": {
         "rpcMethod": "sessionFs.exists",
+        "description": "Checks whether a path exists in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1884,14 +2091,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Path to test for existence in the client-provided session filesystem.",
           "title": "SessionFsExistsRequest"
         },
         "result": {
-          "$ref": "#/definitions/SessionFsExistsResult"
+          "$ref": "#/definitions/SessionFsExistsResult",
+          "description": "Indicates whether the requested path exists in the client-provided session filesystem."
         }
       },
       "stat": {
         "rpcMethod": "sessionFs.stat",
+        "description": "Gets metadata for a path in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1909,14 +2119,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Path whose metadata should be returned from the client-provided session filesystem.",
           "title": "SessionFsStatRequest"
         },
         "result": {
-          "$ref": "#/definitions/SessionFsStatResult"
+          "$ref": "#/definitions/SessionFsStatResult",
+          "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed."
         }
       },
       "mkdir": {
         "rpcMethod": "sessionFs.mkdir",
+        "description": "Creates a directory in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1943,6 +2156,7 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.",
           "title": "SessionFsMkdirRequest"
         },
         "result": {
@@ -1960,6 +2174,7 @@
       },
       "readdir": {
         "rpcMethod": "sessionFs.readdir",
+        "description": "Lists entry names in a directory from the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -1977,14 +2192,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Directory path whose entries should be listed from the client-provided session filesystem.",
           "title": "SessionFsReaddirRequest"
         },
         "result": {
-          "$ref": "#/definitions/SessionFsReaddirResult"
+          "$ref": "#/definitions/SessionFsReaddirResult",
+          "description": "Names of entries in the requested directory, or a filesystem error if the read failed."
         }
       },
       "readdirWithTypes": {
         "rpcMethod": "sessionFs.readdirWithTypes",
+        "description": "Lists directory entries with type information from the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -2002,14 +2220,17 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.",
           "title": "SessionFsReaddirWithTypesRequest"
         },
         "result": {
-          "$ref": "#/definitions/SessionFsReaddirWithTypesResult"
+          "$ref": "#/definitions/SessionFsReaddirWithTypesResult",
+          "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed."
         }
       },
       "rm": {
         "rpcMethod": "sessionFs.rm",
+        "description": "Removes a file or directory from the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -2035,6 +2256,7 @@
             "path"
           ],
           "additionalProperties": false,
+          "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.",
           "title": "SessionFsRmRequest"
         },
         "result": {
@@ -2052,6 +2274,7 @@
       },
       "rename": {
         "rpcMethod": "sessionFs.rename",
+        "description": "Renames or moves a path in the client-provided session filesystem.",
         "params": {
           "type": "object",
           "properties": {
@@ -2074,6 +2297,7 @@
             "dest"
           ],
           "additionalProperties": false,
+          "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.",
           "title": "SessionFsRenameRequest"
         },
         "result": {
@@ -2108,6 +2332,7 @@
           "additionalProperties": false
         }
       ],
+      "description": "Optional GitHub token used to look up quota for a specific user instead of the global auth context.",
       "title": "AccountGetQuotaRequest"
     },
     "AccountGetQuotaResult": {
@@ -2125,6 +2350,7 @@
         "quotaSnapshots"
       ],
       "additionalProperties": false,
+      "description": "Quota usage snapshots for the resolved user, keyed by quota type.",
       "title": "AccountGetQuotaResult"
     },
     "AccountQuotaSnapshot": {
@@ -2175,7 +2401,8 @@
         "overageAllowedWithExhaustedQuota"
       ],
       "additionalProperties": false,
-      "title": "AccountQuotaSnapshot"
+      "title": "AccountQuotaSnapshot",
+      "description": "Schema for the `AccountQuotaSnapshot` type."
     },
     "AgentGetCurrentResult": {
       "type": "object",
@@ -2189,6 +2416,7 @@
         "agent"
       ],
       "additionalProperties": false,
+      "description": "The currently selected custom agent, or null when using the default agent.",
       "title": "AgentGetCurrentResult"
     },
     "AgentInfo": {
@@ -2217,7 +2445,8 @@
         "description"
       ],
       "additionalProperties": false,
-      "title": "AgentInfo"
+      "title": "AgentInfo",
+      "description": "Schema for the `AgentInfo` type."
     },
     "AgentList": {
       "type": "object",
@@ -2234,6 +2463,7 @@
         "agents"
       ],
       "additionalProperties": false,
+      "description": "Custom agents available to the session.",
       "title": "AgentList"
     },
     "AgentReloadResult": {
@@ -2251,6 +2481,7 @@
         "agents"
       ],
       "additionalProperties": false,
+      "description": "Custom agents available to the session after reloading definitions from disk.",
       "title": "AgentReloadResult"
     },
     "AgentSelectRequest": {
@@ -2265,6 +2496,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "Name of the custom agent to select for subsequent turns.",
       "title": "AgentSelectRequest"
     },
     "AgentSelectResult": {
@@ -2279,6 +2511,7 @@
         "agent"
       ],
       "additionalProperties": false,
+      "description": "The newly selected custom agent.",
       "title": "AgentSelectResult"
     },
     "AuthInfoType": {
@@ -2310,6 +2543,7 @@
         "commands"
       ],
       "additionalProperties": false,
+      "description": "Slash commands available in the session, after applying any include/exclude filters.",
       "title": "CommandList"
     },
     "CommandsHandlePendingCommandRequest": {
@@ -2328,6 +2562,7 @@
         "requestId"
       ],
       "additionalProperties": false,
+      "description": "Pending command request ID and an optional error if the client handler failed.",
       "title": "CommandsHandlePendingCommandRequest"
     },
     "CommandsHandlePendingCommandResult": {
@@ -2342,6 +2577,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the pending client-handled command was completed successfully.",
       "title": "CommandsHandlePendingCommandResult"
     },
     "CommandsInvokeRequest": {
@@ -2360,6 +2596,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "Slash command name and optional raw input string to invoke.",
       "title": "CommandsInvokeRequest"
     },
     "CommandsListRequest": {
@@ -2386,6 +2623,7 @@
           "additionalProperties": false
         }
       ],
+      "description": "Optional filters controlling which command sources to include in the listing.",
       "title": "CommandsListRequest"
     },
     "CommandsRespondToQueuedCommandRequest": {
@@ -2405,6 +2643,7 @@
         "result"
       ],
       "additionalProperties": false,
+      "description": "Queued command request ID and the result indicating whether the client handled it.",
       "title": "CommandsRespondToQueuedCommandRequest"
     },
     "CommandsRespondToQueuedCommandResult": {
@@ -2419,8 +2658,117 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the queued-command response was accepted by the session.",
       "title": "CommandsRespondToQueuedCommandResult"
     },
+    "ConnectedRemoteSessionMetadata": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "SDK session ID for the connected remote session."
+        },
+        "name": {
+          "type": "string",
+          "description": "Optional friendly session name."
+        },
+        "summary": {
+          "type": "string",
+          "description": "Optional session summary."
+        },
+        "startTime": {
+          "type": "string",
+          "description": "Session start time as an ISO 8601 string."
+        },
+        "modifiedTime": {
+          "type": "string",
+          "description": "Last session update time as an ISO 8601 string."
+        },
+        "repository": {
+          "$ref": "#/definitions/ConnectedRemoteSessionMetadataRepository",
+          "description": "Repository associated with the connected remote session."
+        },
+        "pullRequestNumber": {
+          "type": "integer",
+          "description": "Pull request number associated with the session."
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Original remote resource identifier."
+        },
+        "kind": {
+          "$ref": "#/definitions/ConnectedRemoteSessionMetadataKind",
+          "description": "Neutral SDK discriminator for the connected remote session kind."
+        },
+        "staleAt": {
+          "type": "string",
+          "description": "Remote session staleness deadline as an ISO 8601 string."
+        },
+        "state": {
+          "type": "string",
+          "description": "Remote session state returned by the backing service."
+        }
+      },
+      "required": [
+        "sessionId",
+        "startTime",
+        "modifiedTime",
+        "repository",
+        "kind"
+      ],
+      "additionalProperties": false,
+      "description": "Metadata for a connected remote session.",
+      "title": "ConnectedRemoteSessionMetadata"
+    },
+    "ConnectedRemoteSessionMetadataKind": {
+      "type": "string",
+      "enum": [
+        "remote-session",
+        "coding-agent"
+      ],
+      "description": "Neutral SDK discriminator for the connected remote session kind.",
+      "title": "ConnectedRemoteSessionMetadataKind"
+    },
+    "ConnectedRemoteSessionMetadataRepository": {
+      "type": "object",
+      "properties": {
+        "owner": {
+          "type": "string",
+          "description": "Repository owner or organization login."
+        },
+        "name": {
+          "type": "string",
+          "description": "Repository name."
+        },
+        "branch": {
+          "type": "string",
+          "description": "Branch associated with the remote session."
+        }
+      },
+      "required": [
+        "owner",
+        "name",
+        "branch"
+      ],
+      "additionalProperties": false,
+      "description": "Repository associated with the connected remote session.",
+      "title": "ConnectedRemoteSessionMetadataRepository"
+    },
+    "ConnectRemoteSessionParams": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "Session ID to connect to."
+        }
+      },
+      "required": [
+        "sessionId"
+      ],
+      "additionalProperties": false,
+      "description": "Remote session connection parameters.",
+      "title": "ConnectRemoteSessionParams"
+    },
     "ConnectRequest": {
       "type": "object",
       "properties": {
@@ -2430,6 +2778,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional connection token presented by the SDK client during the handshake.",
       "title": "ConnectRequest",
       "visibility": "internal"
     },
@@ -2456,6 +2805,7 @@
         "version"
       ],
       "additionalProperties": false,
+      "description": "Handshake result reporting the server's protocol version and package version on success.",
       "title": "ConnectResult",
       "visibility": "internal"
     },
@@ -2468,6 +2818,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "The currently selected model for the session.",
       "title": "CurrentModel"
     },
     "DiscoveredMcpServer": {
@@ -2498,7 +2849,8 @@
         "enabled"
       ],
       "additionalProperties": false,
-      "title": "DiscoveredMcpServer"
+      "title": "DiscoveredMcpServer",
+      "description": "Schema for the `DiscoveredMcpServer` type."
     },
     "DiscoveredMcpServerSource": {
       "type": "string",
@@ -2544,7 +2896,8 @@
         "blob"
       ],
       "additionalProperties": false,
-      "title": "EmbeddedBlobResourceContents"
+      "title": "EmbeddedBlobResourceContents",
+      "description": "Schema for the `EmbeddedBlobResourceContents` type."
     },
     "EmbeddedTextResourceContents": {
       "type": "object",
@@ -2567,7 +2920,8 @@
         "text"
       ],
       "additionalProperties": false,
-      "title": "EmbeddedTextResourceContents"
+      "title": "EmbeddedTextResourceContents",
+      "description": "Schema for the `EmbeddedTextResourceContents` type."
     },
     "Extension": {
       "type": "object",
@@ -2600,7 +2954,8 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "Extension"
+      "title": "Extension",
+      "description": "Schema for the `Extension` type."
     },
     "ExtensionList": {
       "type": "object",
@@ -2617,6 +2972,7 @@
         "extensions"
       ],
       "additionalProperties": false,
+      "description": "Extensions discovered for the session, with their current status.",
       "title": "ExtensionList"
     },
     "ExtensionsDisableRequest": {
@@ -2631,6 +2987,7 @@
         "id"
       ],
       "additionalProperties": false,
+      "description": "Source-qualified extension identifier to disable for the session.",
       "title": "ExtensionsDisableRequest"
     },
     "ExtensionsEnableRequest": {
@@ -2645,6 +3002,7 @@
         "id"
       ],
       "additionalProperties": false,
+      "description": "Source-qualified extension identifier to enable for the session.",
       "title": "ExtensionsEnableRequest"
     },
     "ExtensionSource": {
@@ -2989,6 +3347,7 @@
           "$ref": "#/definitions/FilterMappingString"
         }
       ],
+      "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode.",
       "title": "FilterMapping"
     },
     "FilterMappingString": {
@@ -2998,7 +3357,8 @@
         "markdown",
         "hidden_characters"
       ],
-      "title": "FilterMappingString"
+      "title": "FilterMappingString",
+      "description": "Allowed values for the `FilterMappingString` enumeration."
     },
     "FilterMappingValue": {
       "type": "string",
@@ -3007,7 +3367,8 @@
         "markdown",
         "hidden_characters"
       ],
-      "title": "FilterMappingValue"
+      "title": "FilterMappingValue",
+      "description": "Allowed values for the `FilterMappingValue` enumeration."
     },
     "FleetStartRequest": {
       "type": "object",
@@ -3018,6 +3379,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional user prompt to combine with the fleet orchestration instructions.",
       "title": "FleetStartRequest"
     },
     "FleetStartResult": {
@@ -3032,6 +3394,7 @@
         "started"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether fleet mode was successfully activated.",
       "title": "FleetStartResult"
     },
     "HandlePendingToolCallRequest": {
@@ -3054,6 +3417,7 @@
         "requestId"
       ],
       "additionalProperties": false,
+      "description": "Pending external tool call request ID, with the tool result or an error describing why it failed.",
       "title": "HandlePendingToolCallRequest"
     },
     "HandlePendingToolCallResult": {
@@ -3068,6 +3432,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the external tool call result was handled successfully.",
       "title": "HandlePendingToolCallResult"
     },
     "HistoryCompactContextWindow": {
@@ -3141,6 +3506,7 @@
         "messagesRemoved"
       ],
       "additionalProperties": false,
+      "description": "Compaction outcome with the number of tokens and messages removed and the resulting context window breakdown.",
       "title": "HistoryCompactResult"
     },
     "HistoryTruncateRequest": {
@@ -3155,6 +3521,7 @@
         "eventId"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the event to truncate to; this event and all later events are removed.",
       "title": "HistoryTruncateRequest"
     },
     "HistoryTruncateResult": {
@@ -3170,6 +3537,7 @@
         "eventsRemoved"
       ],
       "additionalProperties": false,
+      "description": "Number of events that were removed by the truncation.",
       "title": "HistoryTruncateResult"
     },
     "InstructionsGetSourcesResult": {
@@ -3187,6 +3555,7 @@
         "sources"
       ],
       "additionalProperties": false,
+      "description": "Instruction sources loaded for the session, in merge order.",
       "title": "InstructionsGetSourcesResult"
     },
     "InstructionsSources": {
@@ -3234,7 +3603,8 @@
         "location"
       ],
       "additionalProperties": false,
-      "title": "InstructionsSources"
+      "title": "InstructionsSources",
+      "description": "Schema for the `InstructionsSources` type."
     },
     "InstructionsSourcesLocation": {
       "type": "string",
@@ -3284,6 +3654,7 @@
         "message"
       ],
       "additionalProperties": false,
+      "description": "Message text, optional severity level, persistence flag, and optional follow-up URL.",
       "title": "LogRequest"
     },
     "LogResult": {
@@ -3299,6 +3670,7 @@
         "eventId"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the session event that was emitted for the log message.",
       "title": "LogResult"
     },
     "McpConfigAddRequest": {
@@ -3320,6 +3692,7 @@
         "config"
       ],
       "additionalProperties": false,
+      "description": "MCP server name and configuration to add to user configuration.",
       "title": "McpConfigAddRequest"
     },
     "McpConfigDisableRequest": {
@@ -3330,7 +3703,8 @@
           "items": {
             "type": "string",
             "minLength": 1,
-            "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$"
+            "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$",
+            "description": "MCP server name used as a configuration key."
           },
           "description": "Names of MCP servers to disable. Each server is added to the persisted disabled list so new sessions skip it. Already-disabled names are ignored. Active sessions keep their current connections until they end."
         }
@@ -3339,6 +3713,7 @@
         "names"
       ],
       "additionalProperties": false,
+      "description": "MCP server names to disable for new sessions.",
       "title": "McpConfigDisableRequest"
     },
     "McpConfigEnableRequest": {
@@ -3349,7 +3724,8 @@
           "items": {
             "type": "string",
             "minLength": 1,
-            "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$"
+            "pattern": "^[^\\x00-\\x1f/\\x7f-\\x9f}]+(?:\\/[^\\x00-\\x1f/\\x7f-\\x9f}]+)*$",
+            "description": "MCP server name used as a configuration key."
           },
           "description": "Names of MCP servers to enable. Each server is removed from the persisted disabled list so new sessions spawn it. Unknown or already-enabled names are ignored."
         }
@@ -3358,6 +3734,7 @@
         "names"
       ],
       "additionalProperties": false,
+      "description": "MCP server names to enable for new sessions.",
       "title": "McpConfigEnableRequest"
     },
     "McpConfigList": {
@@ -3380,6 +3757,7 @@
         "servers"
       ],
       "additionalProperties": false,
+      "description": "User-configured MCP servers, keyed by server name.",
       "title": "McpConfigList"
     },
     "McpConfigRemoveRequest": {
@@ -3396,6 +3774,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "MCP server name to remove from user configuration.",
       "title": "McpConfigRemoveRequest"
     },
     "McpConfigUpdateRequest": {
@@ -3417,6 +3796,7 @@
         "config"
       ],
       "additionalProperties": false,
+      "description": "MCP server name and replacement configuration to write to user configuration.",
       "title": "McpConfigUpdateRequest"
     },
     "McpDisableRequest": {
@@ -3433,6 +3813,7 @@
         "serverName"
       ],
       "additionalProperties": false,
+      "description": "Name of the MCP server to disable for the session.",
       "title": "McpDisableRequest"
     },
     "McpDiscoverRequest": {
@@ -3444,6 +3825,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional working directory used as context for MCP server discovery.",
       "title": "McpDiscoverRequest"
     },
     "McpDiscoverResult": {
@@ -3461,6 +3843,7 @@
         "servers"
       ],
       "additionalProperties": false,
+      "description": "MCP servers discovered from user, workspace, plugin, and built-in sources.",
       "title": "McpDiscoverResult"
     },
     "McpEnableRequest": {
@@ -3477,6 +3860,7 @@
         "serverName"
       ],
       "additionalProperties": false,
+      "description": "Name of the MCP server to enable for the session.",
       "title": "McpEnableRequest"
     },
     "McpOauthLoginRequest": {
@@ -3505,6 +3889,7 @@
         "serverName"
       ],
       "additionalProperties": false,
+      "description": "Remote MCP server name and optional overrides controlling reauthentication, OAuth client display name, and the callback success-page copy.",
       "title": "McpOauthLoginRequest"
     },
     "McpOauthLoginResult": {
@@ -3516,6 +3901,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.",
       "title": "McpOauthLoginResult"
     },
     "McpServer": {
@@ -3545,15 +3931,18 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "McpServer"
+      "title": "McpServer",
+      "description": "Schema for the `McpServer` type."
     },
     "McpServerConfig": {
       "anyOf": [
         {
-          "$ref": "#/definitions/McpServerConfigLocal"
+          "$ref": "#/definitions/McpServerConfigLocal",
+          "description": "Local MCP server configuration launched as a child process."
         },
         {
-          "$ref": "#/definitions/McpServerConfigHttp"
+          "$ref": "#/definitions/McpServerConfigHttp",
+          "description": "Remote MCP server configuration accessed over HTTP or SSE."
         }
       ],
       "description": "MCP server configuration (local/stdio or remote/http)",
@@ -3574,10 +3963,12 @@
           "description": "Remote transport type. Defaults to \"http\" when omitted."
         },
         "isDefaultServer": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this server is a built-in fallback used when the user has not configured their own server."
         },
         "filterMapping": {
-          "$ref": "#/definitions/FilterMapping"
+          "$ref": "#/definitions/FilterMapping",
+          "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode."
         },
         "timeout": {
           "type": "integer",
@@ -3588,28 +3979,34 @@
         },
         "url": {
           "type": "string",
-          "format": "uri"
+          "format": "uri",
+          "description": "URL of the remote MCP server endpoint."
         },
         "headers": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
-          }
+          },
+          "description": "HTTP headers to include in requests to the remote MCP server."
         },
         "oauthClientId": {
-          "type": "string"
+          "type": "string",
+          "description": "OAuth client ID for a pre-registered remote MCP OAuth client."
         },
         "oauthPublicClient": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether the configured OAuth client is public and does not require a client secret."
         },
         "oauthGrantType": {
-          "$ref": "#/definitions/McpServerConfigHttpOauthGrantType"
+          "$ref": "#/definitions/McpServerConfigHttpOauthGrantType",
+          "description": "OAuth grant type to use when authenticating to the remote MCP server."
         }
       },
       "required": [
         "url"
       ],
       "additionalProperties": false,
+      "description": "Remote MCP server configuration accessed over HTTP or SSE.",
       "title": "McpServerConfigHttp"
     },
     "McpServerConfigHttpOauthGrantType": {
@@ -3618,6 +4015,7 @@
         "authorization_code",
         "client_credentials"
       ],
+      "description": "OAuth grant type to use when authenticating to the remote MCP server.",
       "title": "McpServerConfigHttpOauthGrantType"
     },
     "McpServerConfigHttpType": {
@@ -3641,13 +4039,16 @@
           "description": "Tools to include. Defaults to all tools if not specified."
         },
         "type": {
-          "$ref": "#/definitions/McpServerConfigLocalType"
+          "$ref": "#/definitions/McpServerConfigLocalType",
+          "description": "Local transport type. Defaults to \"local\"."
         },
         "isDefaultServer": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this server is a built-in fallback used when the user has not configured their own server."
         },
         "filterMapping": {
-          "$ref": "#/definitions/FilterMapping"
+          "$ref": "#/definitions/FilterMapping",
+          "description": "Content filtering mode to apply to all tools, or a map of tool name to content filtering mode."
         },
         "timeout": {
           "type": "integer",
@@ -3657,22 +4058,26 @@
           "format": "duration"
         },
         "command": {
-          "type": "string"
+          "type": "string",
+          "description": "Executable command used to start the local MCP server process."
         },
         "args": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Command-line arguments passed to the local MCP server process."
         },
         "cwd": {
-          "type": "string"
+          "type": "string",
+          "description": "Working directory for the local MCP server process."
         },
         "env": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
-          }
+          },
+          "description": "Environment variables to pass to the local MCP server process."
         }
       },
       "required": [
@@ -3680,6 +4085,7 @@
         "args"
       ],
       "additionalProperties": false,
+      "description": "Local MCP server configuration launched as a child process.",
       "title": "McpServerConfigLocal"
     },
     "McpServerConfigLocalType": {
@@ -3688,6 +4094,7 @@
         "local",
         "stdio"
       ],
+      "description": "Local transport type. Defaults to \"local\".",
       "title": "McpServerConfigLocalType"
     },
     "McpServerList": {
@@ -3705,6 +4112,7 @@
         "servers"
       ],
       "additionalProperties": false,
+      "description": "MCP servers configured for the session, with their connection status.",
       "title": "McpServerList"
     },
     "McpServerSource": {
@@ -3780,7 +4188,8 @@
         "capabilities"
       ],
       "additionalProperties": false,
-      "title": "Model"
+      "title": "Model",
+      "description": "Schema for the `Model` type."
     },
     "ModelBilling": {
       "type": "object",
@@ -3916,11 +4325,13 @@
       "properties": {
         "max_prompt_tokens": {
           "type": "integer",
-          "minimum": 0
+          "minimum": 0,
+          "description": "Maximum number of prompt/input tokens"
         },
         "max_output_tokens": {
           "type": "integer",
-          "minimum": 0
+          "minimum": 0,
+          "description": "Maximum number of output/completion tokens"
         },
         "max_context_window_tokens": {
           "type": "integer",
@@ -3928,7 +4339,8 @@
           "description": "Maximum total context window size in tokens"
         },
         "vision": {
-          "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision"
+          "$ref": "#/definitions/ModelCapabilitiesOverrideLimitsVision",
+          "description": "Vision-specific limits"
         }
       },
       "additionalProperties": false,
@@ -3957,16 +4369,19 @@
         }
       },
       "additionalProperties": false,
+      "description": "Vision-specific limits",
       "title": "ModelCapabilitiesOverrideLimitsVision"
     },
     "ModelCapabilitiesOverrideSupports": {
       "type": "object",
       "properties": {
         "vision": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this model supports vision/image input"
         },
         "reasoningEffort": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this model supports reasoning effort configuration"
         }
       },
       "additionalProperties": false,
@@ -4004,6 +4419,7 @@
         "models"
       ],
       "additionalProperties": false,
+      "description": "List of Copilot models available to the resolved user, including capabilities and billing metadata.",
       "title": "ModelList"
     },
     "ModelPickerCategory": {
@@ -4062,6 +4478,7 @@
           "additionalProperties": false
         }
       ],
+      "description": "Optional GitHub token used to list models for a specific user instead of the global auth context.",
       "title": "ModelsListRequest"
     },
     "ModelSwitchToRequest": {
@@ -4073,7 +4490,11 @@
         },
         "reasoningEffort": {
           "type": "string",
-          "description": "Reasoning effort level to use for the model"
+          "description": "Reasoning effort level to use for the model. \"none\" disables reasoning."
+        },
+        "reasoningSummary": {
+          "$ref": "#/definitions/ReasoningSummary",
+          "description": "Reasoning summary mode to request for supported model clients"
         },
         "modelCapabilities": {
           "$ref": "#/definitions/ModelCapabilitiesOverride",
@@ -4084,6 +4505,7 @@
         "modelId"
       ],
       "additionalProperties": false,
+      "description": "Target model identifier and optional reasoning effort, summary, and capability overrides.",
       "title": "ModelSwitchToRequest"
     },
     "ModelSwitchToResult": {
@@ -4095,6 +4517,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "The model identifier active on the session after the switch.",
       "title": "ModelSwitchToResult"
     },
     "ModeSetRequest": {
@@ -4109,6 +4532,7 @@
         "mode"
       ],
       "additionalProperties": false,
+      "description": "Agent interaction mode to apply to the session.",
       "title": "ModeSetRequest"
     },
     "NameGetResult": {
@@ -4126,6 +4550,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "The session's friendly name, or null when not yet set.",
       "title": "NameGetResult"
     },
     "NameSetRequest": {
@@ -4142,6 +4567,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "New friendly name to apply to the session.",
       "title": "NameSetRequest"
     },
     "PermissionDecision": {
@@ -4165,6 +4591,7 @@
           "$ref": "#/definitions/PermissionDecisionUserNotAvailable"
         }
       ],
+      "description": "Decision to apply to a pending permission request.",
       "title": "PermissionDecision"
     },
     "PermissionDecisionApproveForLocation": {
@@ -4190,7 +4617,8 @@
         "locationKey"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocation"
+      "title": "PermissionDecisionApproveForLocation",
+      "description": "Schema for the `PermissionDecisionApproveForLocation` type."
     },
     "PermissionDecisionApproveForLocationApproval": {
       "anyOf": [
@@ -4230,13 +4658,15 @@
       "properties": {
         "kind": {
           "type": "string",
-          "const": "commands"
+          "const": "commands",
+          "description": "Approval scoped to specific command identifiers."
         },
         "commandIdentifiers": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Command identifiers covered by this approval."
         }
       },
       "required": [
@@ -4244,17 +4674,20 @@
         "commandIdentifiers"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalCommands"
+      "title": "PermissionDecisionApproveForLocationApprovalCommands",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCommands` type."
     },
     "PermissionDecisionApproveForLocationApprovalCustomTool": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "custom-tool"
+          "const": "custom-tool",
+          "description": "Approval covering a custom tool."
         },
         "toolName": {
-          "type": "string"
+          "type": "string",
+          "description": "Custom tool name."
         }
       },
       "required": [
@@ -4262,34 +4695,40 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalCustomTool"
+      "title": "PermissionDecisionApproveForLocationApprovalCustomTool",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalCustomTool` type."
     },
     "PermissionDecisionApproveForLocationApprovalExtensionManagement": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "extension-management"
+          "const": "extension-management",
+          "description": "Approval covering extension lifecycle operations such as enable, disable, or reload."
         },
         "operation": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional operation identifier; when omitted, the approval covers all extension management operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement"
+      "title": "PermissionDecisionApproveForLocationApprovalExtensionManagement",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionManagement` type."
     },
     "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "extension-permission-access"
+          "const": "extension-permission-access",
+          "description": "Approval covering an extension's request to access a permission-gated capability."
         },
         "extensionName": {
-          "type": "string"
+          "type": "string",
+          "description": "Extension name."
         }
       },
       "required": [
@@ -4297,23 +4736,27 @@
         "extensionName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess"
+      "title": "PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalExtensionPermissionAccess` type."
     },
     "PermissionDecisionApproveForLocationApprovalMcp": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "mcp"
+          "const": "mcp",
+          "description": "Approval covering an MCP tool."
         },
         "serverName": {
-          "type": "string"
+          "type": "string",
+          "description": "MCP server name."
         },
         "toolName": {
           "type": [
             "string",
             "null"
-          ]
+          ],
+          "description": "MCP tool name, or null to cover every tool on the server."
         }
       },
       "required": [
@@ -4322,17 +4765,20 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalMcp"
+      "title": "PermissionDecisionApproveForLocationApprovalMcp",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcp` type."
     },
     "PermissionDecisionApproveForLocationApprovalMcpSampling": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "mcp-sampling"
+          "const": "mcp-sampling",
+          "description": "Approval covering MCP sampling requests for a server."
         },
         "serverName": {
-          "type": "string"
+          "type": "string",
+          "description": "MCP server name."
         }
       },
       "required": [
@@ -4340,49 +4786,56 @@
         "serverName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalMcpSampling"
+      "title": "PermissionDecisionApproveForLocationApprovalMcpSampling",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMcpSampling` type."
     },
     "PermissionDecisionApproveForLocationApprovalMemory": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "memory"
+          "const": "memory",
+          "description": "Approval covering writes to long-term memory."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalMemory"
+      "title": "PermissionDecisionApproveForLocationApprovalMemory",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalMemory` type."
     },
     "PermissionDecisionApproveForLocationApprovalRead": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "read"
+          "const": "read",
+          "description": "Approval covering read-only filesystem operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalRead"
+      "title": "PermissionDecisionApproveForLocationApprovalRead",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalRead` type."
     },
     "PermissionDecisionApproveForLocationApprovalWrite": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "write"
+          "const": "write",
+          "description": "Approval covering filesystem write operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForLocationApprovalWrite"
+      "title": "PermissionDecisionApproveForLocationApprovalWrite",
+      "description": "Schema for the `PermissionDecisionApproveForLocationApprovalWrite` type."
     },
     "PermissionDecisionApproveForSession": {
       "type": "object",
@@ -4405,7 +4858,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSession"
+      "title": "PermissionDecisionApproveForSession",
+      "description": "Schema for the `PermissionDecisionApproveForSession` type."
     },
     "PermissionDecisionApproveForSessionApproval": {
       "anyOf": [
@@ -4445,13 +4899,15 @@
       "properties": {
         "kind": {
           "type": "string",
-          "const": "commands"
+          "const": "commands",
+          "description": "Approval scoped to specific command identifiers."
         },
         "commandIdentifiers": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Command identifiers covered by this approval."
         }
       },
       "required": [
@@ -4459,17 +4915,20 @@
         "commandIdentifiers"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalCommands"
+      "title": "PermissionDecisionApproveForSessionApprovalCommands",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCommands` type."
     },
     "PermissionDecisionApproveForSessionApprovalCustomTool": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "custom-tool"
+          "const": "custom-tool",
+          "description": "Approval covering a custom tool."
         },
         "toolName": {
-          "type": "string"
+          "type": "string",
+          "description": "Custom tool name."
         }
       },
       "required": [
@@ -4477,34 +4936,40 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalCustomTool"
+      "title": "PermissionDecisionApproveForSessionApprovalCustomTool",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalCustomTool` type."
     },
     "PermissionDecisionApproveForSessionApprovalExtensionManagement": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "extension-management"
+          "const": "extension-management",
+          "description": "Approval covering extension lifecycle operations such as enable, disable, or reload."
         },
         "operation": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional operation identifier; when omitted, the approval covers all extension management operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement"
+      "title": "PermissionDecisionApproveForSessionApprovalExtensionManagement",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionManagement` type."
     },
     "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "extension-permission-access"
+          "const": "extension-permission-access",
+          "description": "Approval covering an extension's request to access a permission-gated capability."
         },
         "extensionName": {
-          "type": "string"
+          "type": "string",
+          "description": "Extension name."
         }
       },
       "required": [
@@ -4512,23 +4977,27 @@
         "extensionName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess"
+      "title": "PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalExtensionPermissionAccess` type."
     },
     "PermissionDecisionApproveForSessionApprovalMcp": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "mcp"
+          "const": "mcp",
+          "description": "Approval covering an MCP tool."
         },
         "serverName": {
-          "type": "string"
+          "type": "string",
+          "description": "MCP server name."
         },
         "toolName": {
           "type": [
             "string",
             "null"
-          ]
+          ],
+          "description": "MCP tool name, or null to cover every tool on the server."
         }
       },
       "required": [
@@ -4537,17 +5006,20 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalMcp"
+      "title": "PermissionDecisionApproveForSessionApprovalMcp",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcp` type."
     },
     "PermissionDecisionApproveForSessionApprovalMcpSampling": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "mcp-sampling"
+          "const": "mcp-sampling",
+          "description": "Approval covering MCP sampling requests for a server."
         },
         "serverName": {
-          "type": "string"
+          "type": "string",
+          "description": "MCP server name."
         }
       },
       "required": [
@@ -4555,49 +5027,56 @@
         "serverName"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalMcpSampling"
+      "title": "PermissionDecisionApproveForSessionApprovalMcpSampling",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMcpSampling` type."
     },
     "PermissionDecisionApproveForSessionApprovalMemory": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "memory"
+          "const": "memory",
+          "description": "Approval covering writes to long-term memory."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalMemory"
+      "title": "PermissionDecisionApproveForSessionApprovalMemory",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalMemory` type."
     },
     "PermissionDecisionApproveForSessionApprovalRead": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "read"
+          "const": "read",
+          "description": "Approval covering read-only filesystem operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalRead"
+      "title": "PermissionDecisionApproveForSessionApprovalRead",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalRead` type."
     },
     "PermissionDecisionApproveForSessionApprovalWrite": {
       "type": "object",
       "properties": {
         "kind": {
           "type": "string",
-          "const": "write"
+          "const": "write",
+          "description": "Approval covering filesystem write operations."
         }
       },
       "required": [
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveForSessionApprovalWrite"
+      "title": "PermissionDecisionApproveForSessionApprovalWrite",
+      "description": "Schema for the `PermissionDecisionApproveForSessionApprovalWrite` type."
     },
     "PermissionDecisionApproveOnce": {
       "type": "object",
@@ -4612,7 +5091,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApproveOnce"
+      "title": "PermissionDecisionApproveOnce",
+      "description": "Schema for the `PermissionDecisionApproveOnce` type."
     },
     "PermissionDecisionApprovePermanently": {
       "type": "object",
@@ -4632,7 +5112,8 @@
         "domain"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionApprovePermanently"
+      "title": "PermissionDecisionApprovePermanently",
+      "description": "Schema for the `PermissionDecisionApprovePermanently` type."
     },
     "PermissionDecisionReject": {
       "type": "object",
@@ -4651,7 +5132,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionReject"
+      "title": "PermissionDecisionReject",
+      "description": "Schema for the `PermissionDecisionReject` type."
     },
     "PermissionDecisionRequest": {
       "type": "object",
@@ -4661,7 +5143,8 @@
           "description": "Request ID of the pending permission request"
         },
         "result": {
-          "$ref": "#/definitions/PermissionDecision"
+          "$ref": "#/definitions/PermissionDecision",
+          "description": "Decision to apply to a pending permission request."
         }
       },
       "required": [
@@ -4669,6 +5152,7 @@
         "result"
       ],
       "additionalProperties": false,
+      "description": "Pending permission request ID and the decision to apply (approve/reject and scope).",
       "title": "PermissionDecisionRequest"
     },
     "PermissionDecisionUserNotAvailable": {
@@ -4684,7 +5168,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDecisionUserNotAvailable"
+      "title": "PermissionDecisionUserNotAvailable",
+      "description": "Schema for the `PermissionDecisionUserNotAvailable` type."
     },
     "PermissionRequestResult": {
       "type": "object",
@@ -4698,12 +5183,14 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the permission decision was applied; false when the request was already resolved.",
       "title": "PermissionRequestResult"
     },
     "PermissionsResetSessionApprovalsRequest": {
       "type": "object",
       "properties": {},
       "additionalProperties": false,
+      "description": "No parameters; clears all session-scoped tool permission approvals.",
       "title": "PermissionsResetSessionApprovalsRequest"
     },
     "PermissionsResetSessionApprovalsResult": {
@@ -4718,6 +5205,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the operation succeeded.",
       "title": "PermissionsResetSessionApprovalsResult"
     },
     "PermissionsSetApproveAllRequest": {
@@ -4732,6 +5220,7 @@
         "enabled"
       ],
       "additionalProperties": false,
+      "description": "Whether to auto-approve all tool permission requests for the rest of the session.",
       "title": "PermissionsSetApproveAllRequest"
     },
     "PermissionsSetApproveAllResult": {
@@ -4746,6 +5235,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the operation succeeded.",
       "title": "PermissionsSetApproveAllResult"
     },
     "PingRequest": {
@@ -4757,6 +5247,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional message to echo back to the caller.",
       "title": "PingRequest"
     },
     "PingResult": {
@@ -4781,6 +5272,7 @@
         "protocolVersion"
       ],
       "additionalProperties": false,
+      "description": "Server liveness response, including the echoed message, current timestamp, and protocol version.",
       "title": "PingResult"
     },
     "PlanReadResult": {
@@ -4811,6 +5303,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Existence, contents, and resolved path of the session plan file.",
       "title": "PlanReadResult"
     },
     "PlanUpdateRequest": {
@@ -4825,6 +5318,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "Replacement contents to write to the session plan file.",
       "title": "PlanUpdateRequest"
     },
     "Plugin": {
@@ -4853,7 +5347,8 @@
         "enabled"
       ],
       "additionalProperties": false,
-      "title": "Plugin"
+      "title": "Plugin",
+      "description": "Schema for the `Plugin` type."
     },
     "PluginList": {
       "type": "object",
@@ -4870,6 +5365,7 @@
         "plugins"
       ],
       "additionalProperties": false,
+      "description": "Plugins installed for the session, with their enabled state and version metadata.",
       "title": "PluginList"
     },
     "QueuedCommandHandled": {
@@ -4889,7 +5385,8 @@
         "handled"
       ],
       "additionalProperties": false,
-      "title": "QueuedCommandHandled"
+      "title": "QueuedCommandHandled",
+      "description": "Schema for the `QueuedCommandHandled` type."
     },
     "QueuedCommandNotHandled": {
       "type": "object",
@@ -4904,7 +5401,8 @@
         "handled"
       ],
       "additionalProperties": false,
-      "title": "QueuedCommandNotHandled"
+      "title": "QueuedCommandNotHandled",
+      "description": "Schema for the `QueuedCommandNotHandled` type."
     },
     "QueuedCommandResult": {
       "anyOf": [
@@ -4918,15 +5416,26 @@
       "description": "Result of the queued command execution",
       "title": "QueuedCommandResult"
     },
+    "ReasoningSummary": {
+      "type": "string",
+      "enum": [
+        "none",
+        "concise",
+        "detailed"
+      ],
+      "description": "Reasoning summary mode to request for supported model clients",
+      "title": "ReasoningSummary"
+    },
     "RemoteEnableRequest": {
       "type": "object",
       "properties": {
         "mode": {
           "$ref": "#/definitions/RemoteSessionMode",
-          "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering."
+          "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering."
         }
       },
       "additionalProperties": false,
+      "description": "Optional remote session mode (\"off\", \"export\", or \"on\"); defaults to enabling both export and remote steering.",
       "title": "RemoteEnableRequest"
     },
     "RemoteEnableResult": {
@@ -4934,7 +5443,7 @@
       "properties": {
         "url": {
           "type": "string",
-          "description": "Mission Control frontend URL for this session"
+          "description": "GitHub frontend URL for this session"
         },
         "remoteSteerable": {
           "type": "boolean",
@@ -4945,8 +5454,29 @@
         "remoteSteerable"
       ],
       "additionalProperties": false,
+      "description": "GitHub URL for the session and a flag indicating whether remote steering is enabled.",
       "title": "RemoteEnableResult"
     },
+    "RemoteSessionConnectionResult": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "SDK session ID for the connected remote session."
+        },
+        "metadata": {
+          "$ref": "#/definitions/ConnectedRemoteSessionMetadata",
+          "description": "Metadata for a connected remote session."
+        }
+      },
+      "required": [
+        "sessionId",
+        "metadata"
+      ],
+      "additionalProperties": false,
+      "description": "Remote session connection result.",
+      "title": "RemoteSessionConnectionResult"
+    },
     "RemoteSessionMode": {
       "type": "string",
       "enum": [
@@ -4954,7 +5484,7 @@
         "export",
         "on"
       ],
-      "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to Mission Control without enabling remote steering, \"on\" enables both export and remote steering.",
+      "description": "Per-session remote mode. \"off\" disables remote, \"export\" exports session events to GitHub without enabling remote steering, \"on\" enables both export and remote steering.",
       "title": "RemoteSessionMode"
     },
     "ServerSkill": {
@@ -4997,7 +5527,8 @@
         "enabled"
       ],
       "additionalProperties": false,
-      "title": "ServerSkill"
+      "title": "ServerSkill",
+      "description": "Schema for the `ServerSkill` type."
     },
     "ServerSkillList": {
       "type": "object",
@@ -5014,6 +5545,7 @@
         "skills"
       ],
       "additionalProperties": false,
+      "description": "Skills discovered across global and project sources.",
       "title": "ServerSkillList"
     },
     "SessionAuthStatus": {
@@ -5048,6 +5580,7 @@
         "isAuthenticated"
       ],
       "additionalProperties": false,
+      "description": "Authentication status and account metadata for the session.",
       "title": "SessionAuthStatus"
     },
     "SessionFsAppendFileRequest": {
@@ -5072,6 +5605,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "File path, content to append, and optional mode for the client-provided session filesystem.",
       "title": "SessionFsAppendFileRequest"
     },
     "SessionFsError": {
@@ -5114,6 +5648,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Path to test for existence in the client-provided session filesystem.",
       "title": "SessionFsExistsRequest"
     },
     "SessionFsExistsResult": {
@@ -5128,6 +5663,7 @@
         "exists"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the requested path exists in the client-provided session filesystem.",
       "title": "SessionFsExistsResult"
     },
     "SessionFsMkdirRequest": {
@@ -5151,6 +5687,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Directory path to create in the client-provided session filesystem, with options for recursive creation and POSIX mode.",
       "title": "SessionFsMkdirRequest"
     },
     "SessionFsReaddirRequest": {
@@ -5165,6 +5702,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Directory path whose entries should be listed from the client-provided session filesystem.",
       "title": "SessionFsReaddirRequest"
     },
     "SessionFsReaddirResult": {
@@ -5186,6 +5724,7 @@
         "entries"
       ],
       "additionalProperties": false,
+      "description": "Names of entries in the requested directory, or a filesystem error if the read failed.",
       "title": "SessionFsReaddirResult"
     },
     "SessionFsReaddirWithTypesEntry": {
@@ -5205,7 +5744,8 @@
         "type"
       ],
       "additionalProperties": false,
-      "title": "SessionFsReaddirWithTypesEntry"
+      "title": "SessionFsReaddirWithTypesEntry",
+      "description": "Schema for the `SessionFsReaddirWithTypesEntry` type."
     },
     "SessionFsReaddirWithTypesEntryType": {
       "type": "string",
@@ -5228,6 +5768,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Directory path whose entries (with type information) should be listed from the client-provided session filesystem.",
       "title": "SessionFsReaddirWithTypesRequest"
     },
     "SessionFsReaddirWithTypesResult": {
@@ -5249,6 +5790,7 @@
         "entries"
       ],
       "additionalProperties": false,
+      "description": "Entries in the requested directory paired with file/directory type information, or a filesystem error if the read failed.",
       "title": "SessionFsReaddirWithTypesResult"
     },
     "SessionFsReadFileRequest": {
@@ -5263,6 +5805,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Path of the file to read from the client-provided session filesystem.",
       "title": "SessionFsReadFileRequest"
     },
     "SessionFsReadFileResult": {
@@ -5281,6 +5824,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "File content as a UTF-8 string, or a filesystem error if the read failed.",
       "title": "SessionFsReadFileResult"
     },
     "SessionFsRenameRequest": {
@@ -5300,6 +5844,7 @@
         "dest"
       ],
       "additionalProperties": false,
+      "description": "Source and destination paths for renaming or moving an entry in the client-provided session filesystem.",
       "title": "SessionFsRenameRequest"
     },
     "SessionFsRmRequest": {
@@ -5322,6 +5867,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Path to remove from the client-provided session filesystem, with options for recursive removal and force.",
       "title": "SessionFsRmRequest"
     },
     "SessionFsSetProviderConventions": {
@@ -5355,6 +5901,7 @@
         "conventions"
       ],
       "additionalProperties": false,
+      "description": "Initial working directory, session-state path layout, and path conventions used to register the calling SDK client as the session filesystem provider.",
       "title": "SessionFsSetProviderRequest"
     },
     "SessionFsSetProviderResult": {
@@ -5369,6 +5916,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the calling client was registered as the session filesystem provider.",
       "title": "SessionFsSetProviderResult"
     },
     "SessionFsStatRequest": {
@@ -5383,6 +5931,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Path whose metadata should be returned from the client-provided session filesystem.",
       "title": "SessionFsStatRequest"
     },
     "SessionFsStatResult": {
@@ -5424,6 +5973,7 @@
         "birthtime"
       ],
       "additionalProperties": false,
+      "description": "Filesystem metadata for the requested path, or a filesystem error if the stat failed.",
       "title": "SessionFsStatResult"
     },
     "SessionFsWriteFileRequest": {
@@ -5448,6 +5998,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "File path, content to write, and optional mode for the client-provided session filesystem.",
       "title": "SessionFsWriteFileRequest"
     },
     "SessionLogLevel": {
@@ -5490,6 +6041,7 @@
         "sessionId"
       ],
       "additionalProperties": false,
+      "description": "Source session identifier to fork from, optional event-ID boundary, and optional friendly name for the new session.",
       "title": "SessionsForkRequest"
     },
     "SessionsForkResult": {
@@ -5508,6 +6060,7 @@
         "sessionId"
       ],
       "additionalProperties": false,
+      "description": "Identifier and optional friendly name assigned to the newly forked session.",
       "title": "SessionsForkResult"
     },
     "ShellExecRequest": {
@@ -5532,6 +6085,7 @@
         "command"
       ],
       "additionalProperties": false,
+      "description": "Shell command to run, with optional working directory and timeout in milliseconds.",
       "title": "ShellExecRequest"
     },
     "ShellExecResult": {
@@ -5546,6 +6100,7 @@
         "processId"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the spawned process, used to correlate streamed output and exit notifications.",
       "title": "ShellExecResult"
     },
     "ShellKillRequest": {
@@ -5564,6 +6119,7 @@
         "processId"
       ],
       "additionalProperties": false,
+      "description": "Identifier of a process previously returned by \"shell.exec\" and the signal to send.",
       "title": "ShellKillRequest"
     },
     "ShellKillResult": {
@@ -5578,6 +6134,7 @@
         "killed"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the signal was delivered; false if the process was unknown or already exited.",
       "title": "ShellKillResult"
     },
     "ShellKillSignal": {
@@ -5626,7 +6183,8 @@
         "enabled"
       ],
       "additionalProperties": false,
-      "title": "Skill"
+      "title": "Skill",
+      "description": "Schema for the `Skill` type."
     },
     "SkillList": {
       "type": "object",
@@ -5643,6 +6201,7 @@
         "skills"
       ],
       "additionalProperties": false,
+      "description": "Skills available to the session, with their enabled state.",
       "title": "SkillList"
     },
     "SkillsConfigSetDisabledSkillsRequest": {
@@ -5660,6 +6219,7 @@
         "disabledSkills"
       ],
       "additionalProperties": false,
+      "description": "Skill names to mark as disabled in global configuration, replacing any previous list.",
       "title": "SkillsConfigSetDisabledSkillsRequest"
     },
     "SkillsDisableRequest": {
@@ -5674,6 +6234,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "Name of the skill to disable for the session.",
       "title": "SkillsDisableRequest"
     },
     "SkillsDiscoverRequest": {
@@ -5695,6 +6256,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional project paths and additional skill directories to include in discovery.",
       "title": "SkillsDiscoverRequest"
     },
     "SkillsEnableRequest": {
@@ -5709,6 +6271,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "Name of the skill to enable for the session.",
       "title": "SkillsEnableRequest"
     },
     "SkillsLoadDiagnostics": {
@@ -5734,6 +6297,7 @@
         "errors"
       ],
       "additionalProperties": false,
+      "description": "Diagnostics from reloading skill definitions, with warnings and errors as separate lists.",
       "title": "SkillsLoadDiagnostics"
     },
     "SlashCommandAgentPromptMode": {
@@ -5777,7 +6341,8 @@
         "displayPrompt"
       ],
       "additionalProperties": false,
-      "title": "SlashCommandAgentPromptResult"
+      "title": "SlashCommandAgentPromptResult",
+      "description": "Schema for the `SlashCommandAgentPromptResult` type."
     },
     "SlashCommandCompletedResult": {
       "type": "object",
@@ -5800,7 +6365,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "SlashCommandCompletedResult"
+      "title": "SlashCommandCompletedResult",
+      "description": "Schema for the `SlashCommandCompletedResult` type."
     },
     "SlashCommandInfo": {
       "type": "object",
@@ -5844,7 +6410,8 @@
         "allowDuringAgentExecution"
       ],
       "additionalProperties": false,
-      "title": "SlashCommandInfo"
+      "title": "SlashCommandInfo",
+      "description": "Schema for the `SlashCommandInfo` type."
     },
     "SlashCommandInput": {
       "type": "object",
@@ -5893,6 +6460,7 @@
           "$ref": "#/definitions/SlashCommandCompletedResult"
         }
       ],
+      "description": "Result of invoking the slash command (text output, prompt to send to the agent, or completion).",
       "title": "SlashCommandInvocationResult"
     },
     "SlashCommandKind": {
@@ -5935,7 +6503,8 @@
         "text"
       ],
       "additionalProperties": false,
-      "title": "SlashCommandTextResult"
+      "title": "SlashCommandTextResult",
+      "description": "Schema for the `SlashCommandTextResult` type."
     },
     "TaskAgentInfo": {
       "type": "object",
@@ -6030,7 +6599,8 @@
         "prompt"
       ],
       "additionalProperties": false,
-      "title": "TaskAgentInfo"
+      "title": "TaskAgentInfo",
+      "description": "Schema for the `TaskAgentInfo` type."
     },
     "TaskAgentInfoExecutionMode": {
       "type": "string",
@@ -6062,7 +6632,8 @@
           "$ref": "#/definitions/TaskShellInfo"
         }
       ],
-      "title": "TaskInfo"
+      "title": "TaskInfo",
+      "description": "Schema for the `TaskInfo` type."
     },
     "TaskList": {
       "type": "object",
@@ -6079,6 +6650,7 @@
         "tasks"
       ],
       "additionalProperties": false,
+      "description": "Background tasks currently tracked by the session.",
       "title": "TaskList"
     },
     "TasksCancelRequest": {
@@ -6093,6 +6665,7 @@
         "id"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the background task to cancel.",
       "title": "TasksCancelRequest"
     },
     "TasksCancelResult": {
@@ -6107,6 +6680,7 @@
         "cancelled"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the background task was successfully cancelled.",
       "title": "TasksCancelResult"
     },
     "TaskShellInfo": {
@@ -6174,7 +6748,8 @@
         "attachmentMode"
       ],
       "additionalProperties": false,
-      "title": "TaskShellInfo"
+      "title": "TaskShellInfo",
+      "description": "Schema for the `TaskShellInfo` type."
     },
     "TaskShellInfoAttachmentMode": {
       "type": "string",
@@ -6218,6 +6793,7 @@
         "id"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the task to promote to background mode.",
       "title": "TasksPromoteToBackgroundRequest"
     },
     "TasksPromoteToBackgroundResult": {
@@ -6232,6 +6808,7 @@
         "promoted"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the task was successfully promoted to background mode.",
       "title": "TasksPromoteToBackgroundResult"
     },
     "TasksRemoveRequest": {
@@ -6246,6 +6823,7 @@
         "id"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the completed or cancelled task to remove from tracking.",
       "title": "TasksRemoveRequest"
     },
     "TasksRemoveResult": {
@@ -6260,6 +6838,7 @@
         "removed"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the task was removed. False when the task does not exist or is still running/idle.",
       "title": "TasksRemoveResult"
     },
     "TasksSendMessageRequest": {
@@ -6283,6 +6862,7 @@
         "message"
       ],
       "additionalProperties": false,
+      "description": "Identifier of the target agent task, message content, and optional sender agent ID.",
       "title": "TasksSendMessageRequest"
     },
     "TasksSendMessageResult": {
@@ -6301,6 +6881,7 @@
         "sent"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the message was delivered, with an error message when delivery failed.",
       "title": "TasksSendMessageResult"
     },
     "TasksStartAgentRequest": {
@@ -6333,6 +6914,7 @@
         "name"
       ],
       "additionalProperties": false,
+      "description": "Agent type, prompt, name, and optional description and model override for the new task.",
       "title": "TasksStartAgentRequest"
     },
     "TasksStartAgentResult": {
@@ -6347,6 +6929,7 @@
         "agentId"
       ],
       "additionalProperties": false,
+      "description": "Identifier assigned to the newly started background agent task.",
       "title": "TasksStartAgentResult"
     },
     "Tool": {
@@ -6379,7 +6962,8 @@
         "description"
       ],
       "additionalProperties": false,
-      "title": "Tool"
+      "title": "Tool",
+      "description": "Schema for the `Tool` type."
     },
     "ToolList": {
       "type": "object",
@@ -6396,6 +6980,7 @@
         "tools"
       ],
       "additionalProperties": false,
+      "description": "Built-in tools available for the requested model, with their parameters and instructions.",
       "title": "ToolList"
     },
     "ToolsListRequest": {
@@ -6407,6 +6992,7 @@
         }
       },
       "additionalProperties": false,
+      "description": "Optional model identifier whose tool overrides should be applied to the listing.",
       "title": "ToolsListRequest"
     },
     "UIElicitationArrayAnyOfField": {
@@ -6414,28 +7000,35 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "array"
+          "const": "array",
+          "description": "Type discriminator. Always \"array\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "minItems": {
-          "type": "number"
+          "type": "number",
+          "description": "Minimum number of items the user must select."
         },
         "maxItems": {
-          "type": "number"
+          "type": "number",
+          "description": "Maximum number of items the user may select."
         },
         "items": {
-          "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItems"
+          "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItems",
+          "description": "Schema applied to each item in the array."
         },
         "default": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Default values selected when the form is first shown."
         }
       },
       "required": [
@@ -6443,6 +7036,7 @@
         "items"
       ],
       "additionalProperties": false,
+      "description": "Multi-select string field where each option pairs a value with a display label.",
       "title": "UIElicitationArrayAnyOfField"
     },
     "UIElicitationArrayAnyOfFieldItems": {
@@ -6452,23 +7046,27 @@
           "type": "array",
           "items": {
             "$ref": "#/definitions/UIElicitationArrayAnyOfFieldItemsAnyOf"
-          }
+          },
+          "description": "Selectable options, each with a value and a display label."
         }
       },
       "required": [
         "anyOf"
       ],
       "additionalProperties": false,
+      "description": "Schema applied to each item in the array.",
       "title": "UIElicitationArrayAnyOfFieldItems"
     },
     "UIElicitationArrayAnyOfFieldItemsAnyOf": {
       "type": "object",
       "properties": {
         "const": {
-          "type": "string"
+          "type": "string",
+          "description": "Value submitted when this option is selected."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Display label for this option."
         }
       },
       "required": [
@@ -6476,35 +7074,43 @@
         "title"
       ],
       "additionalProperties": false,
-      "title": "UIElicitationArrayAnyOfFieldItemsAnyOf"
+      "title": "UIElicitationArrayAnyOfFieldItemsAnyOf",
+      "description": "Schema for the `UIElicitationArrayAnyOfFieldItemsAnyOf` type."
     },
     "UIElicitationArrayEnumField": {
       "type": "object",
       "properties": {
         "type": {
           "type": "string",
-          "const": "array"
+          "const": "array",
+          "description": "Type discriminator. Always \"array\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "minItems": {
-          "type": "number"
+          "type": "number",
+          "description": "Minimum number of items the user must select."
         },
         "maxItems": {
-          "type": "number"
+          "type": "number",
+          "description": "Maximum number of items the user may select."
         },
         "items": {
-          "$ref": "#/definitions/UIElicitationArrayEnumFieldItems"
+          "$ref": "#/definitions/UIElicitationArrayEnumFieldItems",
+          "description": "Schema applied to each item in the array."
         },
         "default": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Default values selected when the form is first shown."
         }
       },
       "required": [
@@ -6512,6 +7118,7 @@
         "items"
       ],
       "additionalProperties": false,
+      "description": "Multi-select string field whose allowed values are defined inline.",
       "title": "UIElicitationArrayEnumField"
     },
     "UIElicitationArrayEnumFieldItems": {
@@ -6519,13 +7126,15 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "string"
+          "const": "string",
+          "description": "Type discriminator. Always \"string\"."
         },
         "enum": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Allowed string values for each selected item."
         }
       },
       "required": [
@@ -6533,6 +7142,7 @@
         "enum"
       ],
       "additionalProperties": false,
+      "description": "Schema applied to each item in the array.",
       "title": "UIElicitationArrayEnumFieldItems"
     },
     "UIElicitationFieldValue": {
@@ -6553,7 +7163,8 @@
           }
         }
       ],
-      "title": "UIElicitationFieldValue"
+      "title": "UIElicitationFieldValue",
+      "description": "Schema for the `UIElicitationFieldValue` type."
     },
     "UIElicitationRequest": {
       "type": "object",
@@ -6572,6 +7183,7 @@
         "requestedSchema"
       ],
       "additionalProperties": false,
+      "description": "Prompt message and JSON schema describing the form fields to elicit from the user.",
       "title": "UIElicitationRequest"
     },
     "UIElicitationResponse": {
@@ -6623,6 +7235,7 @@
         "success"
       ],
       "additionalProperties": false,
+      "description": "Indicates whether the elicitation response was accepted; false if it was already resolved by another client.",
       "title": "UIElicitationResult"
     },
     "UIElicitationSchema": {
@@ -6636,7 +7249,8 @@
         "properties": {
           "type": "object",
           "additionalProperties": {
-            "$ref": "#/definitions/UIElicitationSchemaProperty"
+            "$ref": "#/definitions/UIElicitationSchemaProperty",
+            "description": "Definition for a single elicitation form field."
           },
           "description": "Form field definitions, keyed by field name"
         },
@@ -6659,27 +7273,35 @@
     "UIElicitationSchemaProperty": {
       "anyOf": [
         {
-          "$ref": "#/definitions/UIElicitationStringEnumField"
+          "$ref": "#/definitions/UIElicitationStringEnumField",
+          "description": "Single-select string field whose allowed values are defined inline."
         },
         {
-          "$ref": "#/definitions/UIElicitationStringOneOfField"
+          "$ref": "#/definitions/UIElicitationStringOneOfField",
+          "description": "Single-select string field where each option pairs a value with a display label."
         },
         {
-          "$ref": "#/definitions/UIElicitationArrayEnumField"
+          "$ref": "#/definitions/UIElicitationArrayEnumField",
+          "description": "Multi-select string field whose allowed values are defined inline."
         },
         {
-          "$ref": "#/definitions/UIElicitationArrayAnyOfField"
+          "$ref": "#/definitions/UIElicitationArrayAnyOfField",
+          "description": "Multi-select string field where each option pairs a value with a display label."
         },
         {
-          "$ref": "#/definitions/UIElicitationSchemaPropertyBoolean"
+          "$ref": "#/definitions/UIElicitationSchemaPropertyBoolean",
+          "description": "Boolean field rendered as a yes/no toggle."
         },
         {
-          "$ref": "#/definitions/UIElicitationSchemaPropertyString"
+          "$ref": "#/definitions/UIElicitationSchemaPropertyString",
+          "description": "Free-text string field with optional length and format constraints."
         },
         {
-          "$ref": "#/definitions/UIElicitationSchemaPropertyNumber"
+          "$ref": "#/definitions/UIElicitationSchemaPropertyNumber",
+          "description": "Numeric field accepting either a number or an integer."
         }
       ],
+      "description": "Definition for a single elicitation form field.",
       "title": "UIElicitationSchemaProperty"
     },
     "UIElicitationSchemaPropertyBoolean": {
@@ -6687,50 +7309,62 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "boolean"
+          "const": "boolean",
+          "description": "Type discriminator. Always \"boolean\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "default": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Default value selected when the form is first shown."
         }
       },
       "required": [
         "type"
       ],
       "additionalProperties": false,
+      "description": "Boolean field rendered as a yes/no toggle.",
       "title": "UIElicitationSchemaPropertyBoolean"
     },
     "UIElicitationSchemaPropertyNumber": {
       "type": "object",
       "properties": {
         "type": {
-          "$ref": "#/definitions/UIElicitationSchemaPropertyNumberType"
+          "$ref": "#/definitions/UIElicitationSchemaPropertyNumberType",
+          "description": "Numeric type accepted by the field."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "minimum": {
-          "type": "number"
+          "type": "number",
+          "description": "Minimum allowed value (inclusive)."
         },
         "maximum": {
-          "type": "number"
+          "type": "number",
+          "description": "Maximum allowed value (inclusive)."
         },
         "default": {
-          "type": "number"
+          "type": "number",
+          "description": "Default value populated in the input when the form is first shown."
         }
       },
       "required": [
         "type"
       ],
       "additionalProperties": false,
+      "description": "Numeric field accepting either a number or an integer.",
       "title": "UIElicitationSchemaPropertyNumber"
     },
     "UIElicitationSchemaPropertyNumberType": {
@@ -6739,6 +7373,7 @@
         "number",
         "integer"
       ],
+      "description": "Numeric type accepted by the field.",
       "title": "UIElicitationSchemaPropertyNumberType"
     },
     "UIElicitationSchemaPropertyString": {
@@ -6746,31 +7381,39 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "string"
+          "const": "string",
+          "description": "Type discriminator. Always \"string\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "minLength": {
-          "type": "number"
+          "type": "number",
+          "description": "Minimum number of characters required."
         },
         "maxLength": {
-          "type": "number"
+          "type": "number",
+          "description": "Maximum number of characters allowed."
         },
         "format": {
-          "$ref": "#/definitions/UIElicitationSchemaPropertyStringFormat"
+          "$ref": "#/definitions/UIElicitationSchemaPropertyStringFormat",
+          "description": "Optional format hint that constrains the accepted input."
         },
         "default": {
-          "type": "string"
+          "type": "string",
+          "description": "Default value populated in the input when the form is first shown."
         }
       },
       "required": [
         "type"
       ],
       "additionalProperties": false,
+      "description": "Free-text string field with optional length and format constraints.",
       "title": "UIElicitationSchemaPropertyString"
     },
     "UIElicitationSchemaPropertyStringFormat": {
@@ -6781,6 +7424,7 @@
         "date",
         "date-time"
       ],
+      "description": "Optional format hint that constrains the accepted input.",
       "title": "UIElicitationSchemaPropertyStringFormat"
     },
     "UIElicitationStringEnumField": {
@@ -6788,28 +7432,34 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "string"
+          "const": "string",
+          "description": "Type discriminator. Always \"string\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "enum": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Allowed string values."
         },
         "enumNames": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Optional display labels for each enum value, in the same order as `enum`."
         },
         "default": {
-          "type": "string"
+          "type": "string",
+          "description": "Default value selected when the form is first shown."
         }
       },
       "required": [
@@ -6817,6 +7467,7 @@
         "enum"
       ],
       "additionalProperties": false,
+      "description": "Single-select string field whose allowed values are defined inline.",
       "title": "UIElicitationStringEnumField"
     },
     "UIElicitationStringOneOfField": {
@@ -6824,22 +7475,27 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "string"
+          "const": "string",
+          "description": "Type discriminator. Always \"string\"."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Human-readable label for the field."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Help text describing the field."
         },
         "oneOf": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/UIElicitationStringOneOfFieldOneOf"
-          }
+          },
+          "description": "Selectable options, each with a value and a display label."
         },
         "default": {
-          "type": "string"
+          "type": "string",
+          "description": "Default value selected when the form is first shown."
         }
       },
       "required": [
@@ -6847,16 +7503,19 @@
         "oneOf"
       ],
       "additionalProperties": false,
+      "description": "Single-select string field where each option pairs a value with a display label.",
       "title": "UIElicitationStringOneOfField"
     },
     "UIElicitationStringOneOfFieldOneOf": {
       "type": "object",
       "properties": {
         "const": {
-          "type": "string"
+          "type": "string",
+          "description": "Value submitted when this option is selected."
         },
         "title": {
-          "type": "string"
+          "type": "string",
+          "description": "Display label for this option."
         }
       },
       "required": [
@@ -6864,7 +7523,8 @@
         "title"
       ],
       "additionalProperties": false,
-      "title": "UIElicitationStringOneOfFieldOneOf"
+      "title": "UIElicitationStringOneOfFieldOneOf",
+      "description": "Schema for the `UIElicitationStringOneOfFieldOneOf` type."
     },
     "UIHandlePendingElicitationRequest": {
       "type": "object",
@@ -6883,6 +7543,7 @@
         "result"
       ],
       "additionalProperties": false,
+      "description": "Pending elicitation request ID and the user's response (accept/decline/cancel + form values).",
       "title": "UIHandlePendingElicitationRequest"
     },
     "UsageGetMetricsResult": {
@@ -6956,6 +7617,7 @@
         "lastCallOutputTokens"
       ],
       "additionalProperties": false,
+      "description": "Accumulated session usage metrics, including premium request cost, token counts, model breakdown, and code-change totals.",
       "title": "UsageGetMetricsResult"
     },
     "UsageMetricsCodeChanges": {
@@ -7012,7 +7674,8 @@
         "usage"
       ],
       "additionalProperties": false,
-      "title": "UsageMetricsModelMetric"
+      "title": "UsageMetricsModelMetric",
+      "description": "Schema for the `UsageMetricsModelMetric` type."
     },
     "UsageMetricsModelMetricRequests": {
       "type": "object",
@@ -7047,7 +7710,8 @@
         "tokenCount"
       ],
       "additionalProperties": false,
-      "title": "UsageMetricsModelMetricTokenDetail"
+      "title": "UsageMetricsModelMetricTokenDetail",
+      "description": "Schema for the `UsageMetricsModelMetricTokenDetail` type."
     },
     "UsageMetricsModelMetricUsage": {
       "type": "object",
@@ -7101,7 +7765,8 @@
         "tokenCount"
       ],
       "additionalProperties": false,
-      "title": "UsageMetricsTokenDetail"
+      "title": "UsageMetricsTokenDetail",
+      "description": "Schema for the `UsageMetricsTokenDetail` type."
     },
     "WorkspacesCreateFileRequest": {
       "type": "object",
@@ -7120,6 +7785,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "Relative path and UTF-8 content for the workspace file to create or overwrite.",
       "title": "WorkspacesCreateFileRequest"
     },
     "WorkspacesGetWorkspaceResult": {
@@ -7204,6 +7870,7 @@
         "workspace"
       ],
       "additionalProperties": false,
+      "description": "Current workspace metadata for the session, or null when not available.",
       "title": "WorkspacesGetWorkspaceResult"
     },
     "WorkspacesListFilesResult": {
@@ -7221,6 +7888,7 @@
         "files"
       ],
       "additionalProperties": false,
+      "description": "Relative paths of files stored in the session workspace files directory.",
       "title": "WorkspacesListFilesResult"
     },
     "WorkspacesReadFileRequest": {
@@ -7235,6 +7903,7 @@
         "path"
       ],
       "additionalProperties": false,
+      "description": "Relative path of the workspace file to read.",
       "title": "WorkspacesReadFileRequest"
     },
     "WorkspacesReadFileResult": {
@@ -7249,6 +7918,7 @@
         "content"
       ],
       "additionalProperties": false,
+      "description": "Contents of the requested workspace file as a UTF-8 string.",
       "title": "WorkspacesReadFileResult"
     }
   }
diff --git a/schemas/session-events.schema.json b/schemas/session-events.schema.json
index ce89f29..37ff396 100644
--- a/schemas/session-events.schema.json
+++ b/schemas/session-events.schema.json
@@ -51,7 +51,8 @@
         },
         "type": {
           "type": "string",
-          "const": "abort"
+          "const": "abort",
+          "description": "Type discriminator. Always \"abort\"."
         },
         "data": {
           "$ref": "#/definitions/AbortData",
@@ -66,6 +67,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"abort\". Turn abort information including the reason for termination",
       "title": "AbortEvent"
     },
     "AbortReason": {
@@ -120,7 +122,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -128,7 +131,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.intent"
+          "const": "assistant.intent",
+          "description": "Type discriminator. Always \"assistant.intent\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantIntentData",
@@ -144,6 +148,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan",
       "title": "AssistantIntentEvent"
     },
     "AssistantMessageData": {
@@ -276,7 +281,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -284,7 +290,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.message_delta"
+          "const": "assistant.message_delta",
+          "description": "Type discriminator. Always \"assistant.message_delta\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantMessageDeltaData",
@@ -300,6 +307,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates",
       "title": "AssistantMessageDeltaEvent"
     },
     "AssistantMessageEvent": {
@@ -337,7 +345,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.message"
+          "const": "assistant.message",
+          "description": "Type discriminator. Always \"assistant.message\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantMessageData",
@@ -352,6 +361,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata",
       "title": "AssistantMessageEvent"
     },
     "AssistantMessageStartData": {
@@ -400,7 +410,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -408,7 +419,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.message_start"
+          "const": "assistant.message_start",
+          "description": "Type discriminator. Always \"assistant.message_start\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantMessageStartData",
@@ -424,6 +436,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata",
       "title": "AssistantMessageStartEvent"
     },
     "AssistantMessageToolRequest": {
@@ -548,7 +561,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -556,7 +570,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.reasoning_delta"
+          "const": "assistant.reasoning_delta",
+          "description": "Type discriminator. Always \"assistant.reasoning_delta\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantReasoningDeltaData",
@@ -572,6 +587,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates",
       "title": "AssistantReasoningDeltaEvent"
     },
     "AssistantReasoningEvent": {
@@ -609,7 +625,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.reasoning"
+          "const": "assistant.reasoning",
+          "description": "Type discriminator. Always \"assistant.reasoning\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantReasoningData",
@@ -624,6 +641,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text",
       "title": "AssistantReasoningEvent"
     },
     "AssistantStreamingDeltaData": {
@@ -668,7 +686,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -676,7 +695,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.streaming_delta"
+          "const": "assistant.streaming_delta",
+          "description": "Type discriminator. Always \"assistant.streaming_delta\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantStreamingDeltaData",
@@ -692,6 +712,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count",
       "title": "AssistantStreamingDeltaEvent"
     },
     "AssistantTurnEndData": {
@@ -744,7 +765,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.turn_end"
+          "const": "assistant.turn_end",
+          "description": "Type discriminator. Always \"assistant.turn_end\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantTurnEndData",
@@ -759,6 +781,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier",
       "title": "AssistantTurnEndEvent"
     },
     "AssistantTurnStartData": {
@@ -815,7 +838,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.turn_start"
+          "const": "assistant.turn_start",
+          "description": "Type discriminator. Always \"assistant.turn_start\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantTurnStartData",
@@ -830,6 +854,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking",
       "title": "AssistantTurnStartEvent"
     },
     "AssistantUsageApiEndpoint": {
@@ -974,7 +999,7 @@
         },
         "reasoningEffort": {
           "type": "string",
-          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")"
+          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")"
         }
       },
       "required": [
@@ -1011,7 +1036,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1019,7 +1045,8 @@
         },
         "type": {
           "type": "string",
-          "const": "assistant.usage"
+          "const": "assistant.usage",
+          "description": "Type discriminator. Always \"assistant.usage\"."
         },
         "data": {
           "$ref": "#/definitions/AssistantUsageData",
@@ -1035,6 +1062,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information",
       "title": "AssistantUsageEvent"
     },
     "AssistantUsageQuotaSnapshot": {
@@ -1084,7 +1112,8 @@
         "remainingPercentage"
       ],
       "additionalProperties": false,
-      "title": "AssistantUsageQuotaSnapshot"
+      "title": "AssistantUsageQuotaSnapshot",
+      "description": "Schema for the `AssistantUsageQuotaSnapshot` type."
     },
     "AutoModeSwitchCompletedData": {
       "type": "object",
@@ -1133,7 +1162,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1141,7 +1171,8 @@
         },
         "type": {
           "type": "string",
-          "const": "auto_mode_switch.completed"
+          "const": "auto_mode_switch.completed",
+          "description": "Type discriminator. Always \"auto_mode_switch.completed\"."
         },
         "data": {
           "$ref": "#/definitions/AutoModeSwitchCompletedData",
@@ -1157,6 +1188,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification",
       "title": "AutoModeSwitchCompletedEvent"
     },
     "AutoModeSwitchRequestedData": {
@@ -1209,7 +1241,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1217,7 +1250,8 @@
         },
         "type": {
           "type": "string",
-          "const": "auto_mode_switch.requested"
+          "const": "auto_mode_switch.requested",
+          "description": "Type discriminator. Always \"auto_mode_switch.requested\"."
         },
         "data": {
           "$ref": "#/definitions/AutoModeSwitchRequestedData",
@@ -1233,13 +1267,15 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval",
       "title": "AutoModeSwitchRequestedEvent"
     },
     "BackgroundTasksChangedData": {
       "type": "object",
       "properties": {},
       "additionalProperties": false,
-      "title": "BackgroundTasksChangedData"
+      "title": "BackgroundTasksChangedData",
+      "description": "Schema for the `BackgroundTasksChangedData` type."
     },
     "BackgroundTasksChangedEvent": {
       "type": "object",
@@ -1268,7 +1304,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1276,10 +1313,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.background_tasks_changed"
+          "const": "session.background_tasks_changed",
+          "description": "Type discriminator. Always \"session.background_tasks_changed\"."
         },
         "data": {
-          "$ref": "#/definitions/BackgroundTasksChangedData"
+          "$ref": "#/definitions/BackgroundTasksChangedData",
+          "description": "Schema for the `BackgroundTasksChangedData` type."
         }
       },
       "required": [
@@ -1291,6 +1330,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.background_tasks_changed\".",
       "title": "BackgroundTasksChangedEvent"
     },
     "CapabilitiesChangedData": {
@@ -1332,7 +1372,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1340,7 +1381,8 @@
         },
         "type": {
           "type": "string",
-          "const": "capabilities.changed"
+          "const": "capabilities.changed",
+          "description": "Type discriminator. Always \"capabilities.changed\"."
         },
         "data": {
           "$ref": "#/definitions/CapabilitiesChangedData",
@@ -1356,6 +1398,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"capabilities.changed\". Session capability change notification",
       "title": "CapabilitiesChangedEvent"
     },
     "CapabilitiesChangedUI": {
@@ -1412,7 +1455,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1420,7 +1464,8 @@
         },
         "type": {
           "type": "string",
-          "const": "command.completed"
+          "const": "command.completed",
+          "description": "Type discriminator. Always \"command.completed\"."
         },
         "data": {
           "$ref": "#/definitions/CommandCompletedData",
@@ -1436,6 +1481,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal",
       "title": "CommandCompletedEvent"
     },
     "CommandExecuteData": {
@@ -1495,7 +1541,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1503,7 +1550,8 @@
         },
         "type": {
           "type": "string",
-          "const": "command.execute"
+          "const": "command.execute",
+          "description": "Type discriminator. Always \"command.execute\"."
         },
         "data": {
           "$ref": "#/definitions/CommandExecuteData",
@@ -1519,6 +1567,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client",
       "title": "CommandExecuteEvent"
     },
     "CommandQueuedData": {
@@ -1568,7 +1617,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1576,7 +1626,8 @@
         },
         "type": {
           "type": "string",
-          "const": "command.queued"
+          "const": "command.queued",
+          "description": "Type discriminator. Always \"command.queued\"."
         },
         "data": {
           "$ref": "#/definitions/CommandQueuedData",
@@ -1592,23 +1643,27 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution",
       "title": "CommandQueuedEvent"
     },
     "CommandsChangedCommand": {
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "Slash command name without the leading slash."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional human-readable command description."
         }
       },
       "required": [
         "name"
       ],
       "additionalProperties": false,
-      "title": "CommandsChangedCommand"
+      "title": "CommandsChangedCommand",
+      "description": "Schema for the `CommandsChangedCommand` type."
     },
     "CommandsChangedData": {
       "type": "object",
@@ -1655,7 +1710,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -1663,7 +1719,8 @@
         },
         "type": {
           "type": "string",
-          "const": "commands.changed"
+          "const": "commands.changed",
+          "description": "Type discriminator. Always \"commands.changed\"."
         },
         "data": {
           "$ref": "#/definitions/CommandsChangedData",
@@ -1679,6 +1736,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"commands.changed\". SDK command registration change notification",
       "title": "CommandsChangedEvent"
     },
     "CompactionCompleteCompactionTokensUsed": {
@@ -1877,7 +1935,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.compaction_complete"
+          "const": "session.compaction_complete",
+          "description": "Type discriminator. Always \"session.compaction_complete\"."
         },
         "data": {
           "$ref": "#/definitions/CompactionCompleteData",
@@ -1892,6 +1951,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details",
       "title": "CompactionCompleteEvent"
     },
     "CompactionStartData": {
@@ -1949,7 +2009,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.compaction_start"
+          "const": "session.compaction_start",
+          "description": "Type discriminator. Always \"session.compaction_start\"."
         },
         "data": {
           "$ref": "#/definitions/CompactionStartData",
@@ -1964,6 +2025,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction",
       "title": "CompactionStartEvent"
     },
     "ContextChangedEvent": {
@@ -2001,7 +2063,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.context_changed"
+          "const": "session.context_changed",
+          "description": "Type discriminator. Always \"session.context_changed\"."
         },
         "data": {
           "$ref": "#/definitions/WorkingDirectoryContext",
@@ -2016,6 +2079,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.context_changed\". Updated working directory and git context after the change",
       "title": "ContextChangedEvent"
     },
     "CustomAgentsUpdatedAgent": {
@@ -2074,7 +2138,8 @@
         "userInvocable"
       ],
       "additionalProperties": false,
-      "title": "CustomAgentsUpdatedAgent"
+      "title": "CustomAgentsUpdatedAgent",
+      "description": "Schema for the `CustomAgentsUpdatedAgent` type."
     },
     "CustomAgentsUpdatedData": {
       "type": "object",
@@ -2107,7 +2172,8 @@
         "errors"
       ],
       "additionalProperties": false,
-      "title": "CustomAgentsUpdatedData"
+      "title": "CustomAgentsUpdatedData",
+      "description": "Schema for the `CustomAgentsUpdatedData` type."
     },
     "CustomAgentsUpdatedEvent": {
       "type": "object",
@@ -2136,7 +2202,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2144,10 +2211,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.custom_agents_updated"
+          "const": "session.custom_agents_updated",
+          "description": "Type discriminator. Always \"session.custom_agents_updated\"."
         },
         "data": {
-          "$ref": "#/definitions/CustomAgentsUpdatedData"
+          "$ref": "#/definitions/CustomAgentsUpdatedData",
+          "description": "Schema for the `CustomAgentsUpdatedData` type."
         }
       },
       "required": [
@@ -2159,6 +2228,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.custom_agents_updated\".",
       "title": "CustomAgentsUpdatedEvent"
     },
     "CustomNotificationData": {
@@ -2224,7 +2294,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2232,7 +2303,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.custom_notification"
+          "const": "session.custom_notification",
+          "description": "Type discriminator. Always \"session.custom_notification\"."
         },
         "data": {
           "$ref": "#/definitions/CustomNotificationData",
@@ -2248,6 +2320,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.",
       "title": "CustomNotificationEvent"
     },
     "CustomNotificationPayload": {
@@ -2312,7 +2385,8 @@
           }
         }
       ],
-      "title": "ElicitationCompletedContent"
+      "title": "ElicitationCompletedContent",
+      "description": "Schema for the `ElicitationCompletedContent` type."
     },
     "ElicitationCompletedData": {
       "type": "object",
@@ -2367,7 +2441,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2375,7 +2450,8 @@
         },
         "type": {
           "type": "string",
-          "const": "elicitation.completed"
+          "const": "elicitation.completed",
+          "description": "Type discriminator. Always \"elicitation.completed\"."
         },
         "data": {
           "$ref": "#/definitions/ElicitationCompletedData",
@@ -2391,6 +2467,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response",
       "title": "ElicitationCompletedEvent"
     },
     "ElicitationRequestedData": {
@@ -2460,7 +2537,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2468,7 +2546,8 @@
         },
         "type": {
           "type": "string",
-          "const": "elicitation.requested"
+          "const": "elicitation.requested",
+          "description": "Type discriminator. Always \"elicitation.requested\"."
         },
         "data": {
           "$ref": "#/definitions/ElicitationRequestedData",
@@ -2484,6 +2563,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)",
       "title": "ElicitationRequestedEvent"
     },
     "ElicitationRequestedMode": {
@@ -2546,7 +2626,8 @@
         "blob"
       ],
       "additionalProperties": false,
-      "title": "EmbeddedBlobResourceContents"
+      "title": "EmbeddedBlobResourceContents",
+      "description": "Schema for the `EmbeddedBlobResourceContents` type."
     },
     "EmbeddedTextResourceContents": {
       "type": "object",
@@ -2569,7 +2650,8 @@
         "text"
       ],
       "additionalProperties": false,
-      "title": "EmbeddedTextResourceContents"
+      "title": "EmbeddedTextResourceContents",
+      "description": "Schema for the `EmbeddedTextResourceContents` type."
     },
     "ErrorData": {
       "type": "object",
@@ -2651,7 +2733,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.error"
+          "const": "session.error",
+          "description": "Type discriminator. Always \"session.error\"."
         },
         "data": {
           "$ref": "#/definitions/ErrorData",
@@ -2666,6 +2749,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information",
       "title": "ErrorEvent"
     },
     "ExitPlanModeCompletedData": {
@@ -2726,7 +2810,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2734,7 +2819,8 @@
         },
         "type": {
           "type": "string",
-          "const": "exit_plan_mode.completed"
+          "const": "exit_plan_mode.completed",
+          "description": "Type discriminator. Always \"exit_plan_mode.completed\"."
         },
         "data": {
           "$ref": "#/definitions/ExitPlanModeCompletedData",
@@ -2750,6 +2836,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback",
       "title": "ExitPlanModeCompletedEvent"
     },
     "ExitPlanModeRequestedData": {
@@ -2817,7 +2904,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2825,7 +2913,8 @@
         },
         "type": {
           "type": "string",
-          "const": "exit_plan_mode.requested"
+          "const": "exit_plan_mode.requested",
+          "description": "Type discriminator. Always \"exit_plan_mode.requested\"."
         },
         "data": {
           "$ref": "#/definitions/ExitPlanModeRequestedData",
@@ -2841,6 +2930,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions",
       "title": "ExitPlanModeRequestedEvent"
     },
     "ExtensionsLoadedData": {
@@ -2858,7 +2948,8 @@
         "extensions"
       ],
       "additionalProperties": false,
-      "title": "ExtensionsLoadedData"
+      "title": "ExtensionsLoadedData",
+      "description": "Schema for the `ExtensionsLoadedData` type."
     },
     "ExtensionsLoadedEvent": {
       "type": "object",
@@ -2887,7 +2978,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -2895,10 +2987,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.extensions_loaded"
+          "const": "session.extensions_loaded",
+          "description": "Type discriminator. Always \"session.extensions_loaded\"."
         },
         "data": {
-          "$ref": "#/definitions/ExtensionsLoadedData"
+          "$ref": "#/definitions/ExtensionsLoadedData",
+          "description": "Schema for the `ExtensionsLoadedData` type."
         }
       },
       "required": [
@@ -2910,6 +3004,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.extensions_loaded\".",
       "title": "ExtensionsLoadedEvent"
     },
     "ExtensionsLoadedExtension": {
@@ -2939,7 +3034,8 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "ExtensionsLoadedExtension"
+      "title": "ExtensionsLoadedExtension",
+      "description": "Schema for the `ExtensionsLoadedExtension` type."
     },
     "ExtensionsLoadedExtensionSource": {
       "type": "string",
@@ -3003,7 +3099,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3011,7 +3108,8 @@
         },
         "type": {
           "type": "string",
-          "const": "external_tool.completed"
+          "const": "external_tool.completed",
+          "description": "Type discriminator. Always \"external_tool.completed\"."
         },
         "data": {
           "$ref": "#/definitions/ExternalToolCompletedData",
@@ -3026,6 +3124,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal",
       "title": "ExternalToolCompletedEvent"
     },
     "ExternalToolRequestedData": {
@@ -3104,7 +3203,8 @@
         },
         "type": {
           "type": "string",
-          "const": "external_tool.requested"
+          "const": "external_tool.requested",
+          "description": "Type discriminator. Always \"external_tool.requested\"."
         },
         "data": {
           "$ref": "#/definitions/ExternalToolRequestedData",
@@ -3119,6 +3219,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution",
       "title": "ExternalToolRequestedEvent"
     },
     "HandoffData": {
@@ -3197,7 +3298,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.handoff"
+          "const": "session.handoff",
+          "description": "Type discriminator. Always \"session.handoff\"."
         },
         "data": {
           "$ref": "#/definitions/HandoffData",
@@ -3212,6 +3314,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information",
       "title": "HandoffEvent"
     },
     "HandoffRepository": {
@@ -3333,7 +3436,8 @@
         },
         "type": {
           "type": "string",
-          "const": "hook.end"
+          "const": "hook.end",
+          "description": "Type discriminator. Always \"hook.end\"."
         },
         "data": {
           "$ref": "#/definitions/HookEndData",
@@ -3348,6 +3452,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information",
       "title": "HookEndEvent"
     },
     "HookStartData": {
@@ -3408,7 +3513,8 @@
         },
         "type": {
           "type": "string",
-          "const": "hook.start"
+          "const": "hook.start",
+          "description": "Type discriminator. Always \"hook.start\"."
         },
         "data": {
           "$ref": "#/definitions/HookStartData",
@@ -3423,6 +3529,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"hook.start\". Hook invocation start details including type and input data",
       "title": "HookStartEvent"
     },
     "IdleData": {
@@ -3464,7 +3571,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3472,7 +3580,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.idle"
+          "const": "session.idle",
+          "description": "Type discriminator. Always \"session.idle\"."
         },
         "data": {
           "$ref": "#/definitions/IdleData",
@@ -3488,6 +3597,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents in flight",
       "title": "IdleEvent"
     },
     "InfoData": {
@@ -3554,7 +3664,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.info"
+          "const": "session.info",
+          "description": "Type discriminator. Always \"session.info\"."
         },
         "data": {
           "$ref": "#/definitions/InfoData",
@@ -3569,6 +3680,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.info\". Informational message for timeline display with categorization",
       "title": "InfoEvent"
     },
     "McpOauthCompletedData": {
@@ -3613,7 +3725,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3621,7 +3734,8 @@
         },
         "type": {
           "type": "string",
-          "const": "mcp.oauth_completed"
+          "const": "mcp.oauth_completed",
+          "description": "Type discriminator. Always \"mcp.oauth_completed\"."
         },
         "data": {
           "$ref": "#/definitions/McpOauthCompletedData",
@@ -3637,6 +3751,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification",
       "title": "McpOauthCompletedEvent"
     },
     "McpOauthRequiredData": {
@@ -3695,7 +3810,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3703,7 +3819,8 @@
         },
         "type": {
           "type": "string",
-          "const": "mcp.oauth_required"
+          "const": "mcp.oauth_required",
+          "description": "Type discriminator. Always \"mcp.oauth_required\"."
         },
         "data": {
           "$ref": "#/definitions/McpOauthRequiredData",
@@ -3719,6 +3836,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server",
       "title": "McpOauthRequiredEvent"
     },
     "McpOauthRequiredStaticClientConfig": {
@@ -3760,7 +3878,8 @@
         "servers"
       ],
       "additionalProperties": false,
-      "title": "McpServersLoadedData"
+      "title": "McpServersLoadedData",
+      "description": "Schema for the `McpServersLoadedData` type."
     },
     "McpServersLoadedEvent": {
       "type": "object",
@@ -3789,7 +3908,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3797,10 +3917,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.mcp_servers_loaded"
+          "const": "session.mcp_servers_loaded",
+          "description": "Type discriminator. Always \"session.mcp_servers_loaded\"."
         },
         "data": {
-          "$ref": "#/definitions/McpServersLoadedData"
+          "$ref": "#/definitions/McpServersLoadedData",
+          "description": "Schema for the `McpServersLoadedData` type."
         }
       },
       "required": [
@@ -3812,6 +3934,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.mcp_servers_loaded\".",
       "title": "McpServersLoadedEvent"
     },
     "McpServersLoadedServer": {
@@ -3839,7 +3962,8 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "McpServersLoadedServer"
+      "title": "McpServersLoadedServer",
+      "description": "Schema for the `McpServersLoadedServer` type."
     },
     "McpServersLoadedServerStatus": {
       "type": "string",
@@ -3871,7 +3995,8 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "McpServerStatusChangedData"
+      "title": "McpServerStatusChangedData",
+      "description": "Schema for the `McpServerStatusChangedData` type."
     },
     "McpServerStatusChangedEvent": {
       "type": "object",
@@ -3900,7 +4025,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -3908,10 +4034,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.mcp_server_status_changed"
+          "const": "session.mcp_server_status_changed",
+          "description": "Type discriminator. Always \"session.mcp_server_status_changed\"."
         },
         "data": {
-          "$ref": "#/definitions/McpServerStatusChangedData"
+          "$ref": "#/definitions/McpServerStatusChangedData",
+          "description": "Schema for the `McpServerStatusChangedData` type."
         }
       },
       "required": [
@@ -3923,6 +4051,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.mcp_server_status_changed\".",
       "title": "McpServerStatusChangedEvent"
     },
     "McpServerStatusChangedStatus": {
@@ -3993,7 +4122,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.mode_changed"
+          "const": "session.mode_changed",
+          "description": "Type discriminator. Always \"session.mode_changed\"."
         },
         "data": {
           "$ref": "#/definitions/ModeChangedData",
@@ -4008,6 +4138,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes",
       "title": "ModeChangedEvent"
     },
     "ModelCallFailureData": {
@@ -4080,7 +4211,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -4088,7 +4220,8 @@
         },
         "type": {
           "type": "string",
-          "const": "model.call_failure"
+          "const": "model.call_failure",
+          "description": "Type discriminator. Always \"model.call_failure\"."
         },
         "data": {
           "$ref": "#/definitions/ModelCallFailureData",
@@ -4104,6 +4237,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry",
       "title": "ModelCallFailureEvent"
     },
     "ModelCallFailureSource": {
@@ -4132,9 +4266,20 @@
           "description": "Reasoning effort level before the model change, if applicable"
         },
         "reasoningEffort": {
-          "type": "string",
+          "type": [
+            "string",
+            "null"
+          ],
           "description": "Reasoning effort level after the model change, if applicable"
         },
+        "previousReasoningSummary": {
+          "$ref": "#/definitions/ReasoningSummary",
+          "description": "Reasoning summary mode before the model change, if applicable"
+        },
+        "reasoningSummary": {
+          "$ref": "#/definitions/ReasoningSummary",
+          "description": "Reasoning summary mode after the model change, if applicable"
+        },
         "cause": {
           "type": "string",
           "description": "Reason the change happened, when not user-initiated. Currently `\"rate_limit_auto_switch\"` for changes triggered by the auto-mode-switch rate-limit recovery path. UI clients can use this to render contextual copy."
@@ -4182,7 +4327,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.model_change"
+          "const": "session.model_change",
+          "description": "Type discriminator. Always \"session.model_change\"."
         },
         "data": {
           "$ref": "#/definitions/ModelChangeData",
@@ -4197,6 +4343,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers",
       "title": "ModelChangeEvent"
     },
     "PendingMessagesModifiedData": {
@@ -4233,7 +4380,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -4241,7 +4389,8 @@
         },
         "type": {
           "type": "string",
-          "const": "pending_messages.modified"
+          "const": "pending_messages.modified",
+          "description": "Type discriminator. Always \"pending_messages.modified\"."
         },
         "data": {
           "$ref": "#/definitions/PendingMessagesModifiedData",
@@ -4257,6 +4406,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed",
       "title": "PendingMessagesModifiedEvent"
     },
     "PermissionApproved": {
@@ -4272,7 +4422,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionApproved"
+      "title": "PermissionApproved",
+      "description": "Schema for the `PermissionApproved` type."
     },
     "PermissionApprovedForLocation": {
       "type": "object",
@@ -4297,7 +4448,8 @@
         "locationKey"
       ],
       "additionalProperties": false,
-      "title": "PermissionApprovedForLocation"
+      "title": "PermissionApprovedForLocation",
+      "description": "Schema for the `PermissionApprovedForLocation` type."
     },
     "PermissionApprovedForSession": {
       "type": "object",
@@ -4317,7 +4469,8 @@
         "approval"
       ],
       "additionalProperties": false,
-      "title": "PermissionApprovedForSession"
+      "title": "PermissionApprovedForSession",
+      "description": "Schema for the `PermissionApprovedForSession` type."
     },
     "PermissionCancelled": {
       "type": "object",
@@ -4336,7 +4489,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionCancelled"
+      "title": "PermissionCancelled",
+      "description": "Schema for the `PermissionCancelled` type."
     },
     "PermissionCompletedData": {
       "type": "object",
@@ -4397,7 +4551,8 @@
         },
         "type": {
           "type": "string",
-          "const": "permission.completed"
+          "const": "permission.completed",
+          "description": "Type discriminator. Always \"permission.completed\"."
         },
         "data": {
           "$ref": "#/definitions/PermissionCompletedData",
@@ -4412,6 +4567,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal",
       "title": "PermissionCompletedEvent"
     },
     "PermissionDeniedByContentExclusionPolicy": {
@@ -4437,7 +4593,8 @@
         "message"
       ],
       "additionalProperties": false,
-      "title": "PermissionDeniedByContentExclusionPolicy"
+      "title": "PermissionDeniedByContentExclusionPolicy",
+      "description": "Schema for the `PermissionDeniedByContentExclusionPolicy` type."
     },
     "PermissionDeniedByPermissionRequestHook": {
       "type": "object",
@@ -4460,7 +4617,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDeniedByPermissionRequestHook"
+      "title": "PermissionDeniedByPermissionRequestHook",
+      "description": "Schema for the `PermissionDeniedByPermissionRequestHook` type."
     },
     "PermissionDeniedByRules": {
       "type": "object",
@@ -4483,7 +4641,8 @@
         "rules"
       ],
       "additionalProperties": false,
-      "title": "PermissionDeniedByRules"
+      "title": "PermissionDeniedByRules",
+      "description": "Schema for the `PermissionDeniedByRules` type."
     },
     "PermissionDeniedInteractivelyByUser": {
       "type": "object",
@@ -4506,7 +4665,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDeniedInteractivelyByUser"
+      "title": "PermissionDeniedInteractivelyByUser",
+      "description": "Schema for the `PermissionDeniedInteractivelyByUser` type."
     },
     "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser": {
       "type": "object",
@@ -4521,7 +4681,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser"
+      "title": "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser",
+      "description": "Schema for the `PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type."
     },
     "PermissionPromptRequest": {
       "anyOf": [
@@ -5144,7 +5305,8 @@
         },
         "type": {
           "type": "string",
-          "const": "permission.requested"
+          "const": "permission.requested",
+          "description": "Type discriminator. Always \"permission.requested\"."
         },
         "data": {
           "$ref": "#/definitions/PermissionRequestedData",
@@ -5159,6 +5321,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details",
       "title": "PermissionRequestedEvent"
     },
     "PermissionRequestExtensionManagement": {
@@ -5477,7 +5640,8 @@
         "readOnly"
       ],
       "additionalProperties": false,
-      "title": "PermissionRequestShellCommand"
+      "title": "PermissionRequestShellCommand",
+      "description": "Schema for the `PermissionRequestShellCommand` type."
     },
     "PermissionRequestShellPossibleUrl": {
       "type": "object",
@@ -5491,7 +5655,8 @@
         "url"
       ],
       "additionalProperties": false,
-      "title": "PermissionRequestShellPossibleUrl"
+      "title": "PermissionRequestShellPossibleUrl",
+      "description": "Schema for the `PermissionRequestShellPossibleUrl` type."
     },
     "PermissionRequestUrl": {
       "type": "object",
@@ -5620,7 +5785,8 @@
         "argument"
       ],
       "additionalProperties": false,
-      "title": "PermissionRule"
+      "title": "PermissionRule",
+      "description": "Schema for the `PermissionRule` type."
     },
     "PlanChangedData": {
       "type": "object",
@@ -5672,7 +5838,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.plan_changed"
+          "const": "session.plan_changed",
+          "description": "Type discriminator. Always \"session.plan_changed\"."
         },
         "data": {
           "$ref": "#/definitions/PlanChangedData",
@@ -5687,6 +5854,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed",
       "title": "PlanChangedEvent"
     },
     "PlanChangedOperation": {
@@ -5699,19 +5867,29 @@
       "description": "The type of operation performed on the plan file",
       "title": "PlanChangedOperation"
     },
+    "ReasoningSummary": {
+      "type": "string",
+      "enum": [
+        "none",
+        "concise",
+        "detailed"
+      ],
+      "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")",
+      "title": "ReasoningSummary"
+    },
     "RemoteSteerableChangedData": {
       "type": "object",
       "properties": {
         "remoteSteerable": {
           "type": "boolean",
-          "description": "Whether this session now supports remote steering via Mission Control"
+          "description": "Whether this session now supports remote steering via GitHub"
         }
       },
       "required": [
         "remoteSteerable"
       ],
       "additionalProperties": false,
-      "description": "Notifies Mission Control that the session's remote steering capability has changed",
+      "description": "Notifies that the session's remote steering capability has changed",
       "title": "RemoteSteerableChangedData"
     },
     "RemoteSteerableChangedEvent": {
@@ -5749,11 +5927,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.remote_steerable_changed"
+          "const": "session.remote_steerable_changed",
+          "description": "Type discriminator. Always \"session.remote_steerable_changed\"."
         },
         "data": {
           "$ref": "#/definitions/RemoteSteerableChangedData",
-          "description": "Notifies Mission Control that the session's remote steering capability has changed"
+          "description": "Notifies that the session's remote steering capability has changed"
         }
       },
       "required": [
@@ -5764,6 +5943,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed",
       "title": "RemoteSteerableChangedEvent"
     },
     "ResumeData": {
@@ -5784,7 +5964,11 @@
         },
         "reasoningEffort": {
           "type": "string",
-          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")"
+          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")"
+        },
+        "reasoningSummary": {
+          "$ref": "#/definitions/ReasoningSummary",
+          "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")"
         },
         "context": {
           "$ref": "#/definitions/WorkingDirectoryContext",
@@ -5800,7 +5984,7 @@
         },
         "remoteSteerable": {
           "type": "boolean",
-          "description": "Whether this session supports remote steering via Mission Control"
+          "description": "Whether this session supports remote steering via GitHub"
         },
         "continuePendingWork": {
           "type": "boolean",
@@ -5850,7 +6034,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.resume"
+          "const": "session.resume",
+          "description": "Type discriminator. Always \"session.resume\"."
         },
         "data": {
           "$ref": "#/definitions/ResumeData",
@@ -5865,6 +6050,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.resume\". Session resume metadata including current context and event count",
       "title": "ResumeEvent"
     },
     "SamplingCompletedData": {
@@ -5909,7 +6095,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -5917,7 +6104,8 @@
         },
         "type": {
           "type": "string",
-          "const": "sampling.completed"
+          "const": "sampling.completed",
+          "description": "Type discriminator. Always \"sampling.completed\"."
         },
         "data": {
           "$ref": "#/definitions/SamplingCompletedData",
@@ -5933,6 +6121,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal",
       "title": "SamplingCompletedEvent"
     },
     "SamplingRequestedData": {
@@ -5990,7 +6179,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -5998,7 +6188,8 @@
         },
         "type": {
           "type": "string",
-          "const": "sampling.requested"
+          "const": "sampling.requested",
+          "description": "Type discriminator. Always \"sampling.requested\"."
         },
         "data": {
           "$ref": "#/definitions/SamplingRequestedData",
@@ -6014,6 +6205,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation",
       "title": "SamplingRequestedEvent"
     },
     "ScheduleCancelledData": {
@@ -6067,7 +6259,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.schedule_cancelled"
+          "const": "session.schedule_cancelled",
+          "description": "Type discriminator. Always \"session.schedule_cancelled\"."
         },
         "data": {
           "$ref": "#/definitions/ScheduleCancelledData",
@@ -6082,6 +6275,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog",
       "title": "ScheduleCancelledEvent"
     },
     "ScheduleCreatedData": {
@@ -6104,6 +6298,10 @@
         "recurring": {
           "type": "boolean",
           "description": "Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)"
+        },
+        "displayPrompt": {
+          "type": "string",
+          "description": "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)"
         }
       },
       "required": [
@@ -6150,7 +6348,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.schedule_created"
+          "const": "session.schedule_created",
+          "description": "Type discriminator. Always \"session.schedule_created\"."
         },
         "data": {
           "$ref": "#/definitions/ScheduleCreatedData",
@@ -6165,254 +6364,337 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after",
       "title": "ScheduleCreatedEvent"
     },
     "SessionEvent": {
       "anyOf": [
         {
-          "$ref": "#/definitions/StartEvent"
+          "$ref": "#/definitions/StartEvent",
+          "description": "Session event \"session.start\". Session initialization metadata including context and configuration"
         },
         {
-          "$ref": "#/definitions/ResumeEvent"
+          "$ref": "#/definitions/ResumeEvent",
+          "description": "Session event \"session.resume\". Session resume metadata including current context and event count"
         },
         {
-          "$ref": "#/definitions/RemoteSteerableChangedEvent"
+          "$ref": "#/definitions/RemoteSteerableChangedEvent",
+          "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed"
         },
         {
-          "$ref": "#/definitions/ErrorEvent"
+          "$ref": "#/definitions/ErrorEvent",
+          "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information"
         },
         {
-          "$ref": "#/definitions/IdleEvent"
+          "$ref": "#/definitions/IdleEvent",
+          "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents in flight"
         },
         {
-          "$ref": "#/definitions/TitleChangedEvent"
+          "$ref": "#/definitions/TitleChangedEvent",
+          "description": "Session event \"session.title_changed\". Session title change payload containing the new display title"
         },
         {
-          "$ref": "#/definitions/ScheduleCreatedEvent"
+          "$ref": "#/definitions/ScheduleCreatedEvent",
+          "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after"
         },
         {
-          "$ref": "#/definitions/ScheduleCancelledEvent"
+          "$ref": "#/definitions/ScheduleCancelledEvent",
+          "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog"
         },
         {
-          "$ref": "#/definitions/InfoEvent"
+          "$ref": "#/definitions/InfoEvent",
+          "description": "Session event \"session.info\". Informational message for timeline display with categorization"
         },
         {
-          "$ref": "#/definitions/WarningEvent"
+          "$ref": "#/definitions/WarningEvent",
+          "description": "Session event \"session.warning\". Warning message for timeline display with categorization"
         },
         {
-          "$ref": "#/definitions/ModelChangeEvent"
+          "$ref": "#/definitions/ModelChangeEvent",
+          "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers"
         },
         {
-          "$ref": "#/definitions/ModeChangedEvent"
+          "$ref": "#/definitions/ModeChangedEvent",
+          "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes"
         },
         {
-          "$ref": "#/definitions/PlanChangedEvent"
+          "$ref": "#/definitions/PlanChangedEvent",
+          "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed"
         },
         {
-          "$ref": "#/definitions/WorkspaceFileChangedEvent"
+          "$ref": "#/definitions/WorkspaceFileChangedEvent",
+          "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type"
         },
         {
-          "$ref": "#/definitions/HandoffEvent"
+          "$ref": "#/definitions/HandoffEvent",
+          "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information"
         },
         {
-          "$ref": "#/definitions/TruncationEvent"
+          "$ref": "#/definitions/TruncationEvent",
+          "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics"
         },
         {
-          "$ref": "#/definitions/SnapshotRewindEvent"
+          "$ref": "#/definitions/SnapshotRewindEvent",
+          "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events"
         },
         {
-          "$ref": "#/definitions/ShutdownEvent"
+          "$ref": "#/definitions/ShutdownEvent",
+          "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason"
         },
         {
-          "$ref": "#/definitions/ContextChangedEvent"
+          "$ref": "#/definitions/ContextChangedEvent",
+          "description": "Session event \"session.context_changed\". Updated working directory and git context after the change"
         },
         {
-          "$ref": "#/definitions/UsageInfoEvent"
+          "$ref": "#/definitions/UsageInfoEvent",
+          "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts"
         },
         {
-          "$ref": "#/definitions/CompactionStartEvent"
+          "$ref": "#/definitions/CompactionStartEvent",
+          "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction"
         },
         {
-          "$ref": "#/definitions/CompactionCompleteEvent"
+          "$ref": "#/definitions/CompactionCompleteEvent",
+          "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details"
         },
         {
-          "$ref": "#/definitions/TaskCompleteEvent"
+          "$ref": "#/definitions/TaskCompleteEvent",
+          "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent"
         },
         {
-          "$ref": "#/definitions/UserMessageEvent"
+          "$ref": "#/definitions/UserMessageEvent",
+          "description": "Session event \"user.message\"."
         },
         {
-          "$ref": "#/definitions/PendingMessagesModifiedEvent"
+          "$ref": "#/definitions/PendingMessagesModifiedEvent",
+          "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed"
         },
         {
-          "$ref": "#/definitions/AssistantTurnStartEvent"
+          "$ref": "#/definitions/AssistantTurnStartEvent",
+          "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking"
         },
         {
-          "$ref": "#/definitions/AssistantIntentEvent"
+          "$ref": "#/definitions/AssistantIntentEvent",
+          "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan"
         },
         {
-          "$ref": "#/definitions/AssistantReasoningEvent"
+          "$ref": "#/definitions/AssistantReasoningEvent",
+          "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text"
         },
         {
-          "$ref": "#/definitions/AssistantReasoningDeltaEvent"
+          "$ref": "#/definitions/AssistantReasoningDeltaEvent",
+          "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates"
         },
         {
-          "$ref": "#/definitions/AssistantStreamingDeltaEvent"
+          "$ref": "#/definitions/AssistantStreamingDeltaEvent",
+          "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count"
         },
         {
-          "$ref": "#/definitions/AssistantMessageEvent"
+          "$ref": "#/definitions/AssistantMessageEvent",
+          "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata"
         },
         {
-          "$ref": "#/definitions/AssistantMessageStartEvent"
+          "$ref": "#/definitions/AssistantMessageStartEvent",
+          "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata"
         },
         {
-          "$ref": "#/definitions/AssistantMessageDeltaEvent"
+          "$ref": "#/definitions/AssistantMessageDeltaEvent",
+          "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates"
         },
         {
-          "$ref": "#/definitions/AssistantTurnEndEvent"
+          "$ref": "#/definitions/AssistantTurnEndEvent",
+          "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier"
         },
         {
-          "$ref": "#/definitions/AssistantUsageEvent"
+          "$ref": "#/definitions/AssistantUsageEvent",
+          "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information"
         },
         {
-          "$ref": "#/definitions/ModelCallFailureEvent"
+          "$ref": "#/definitions/ModelCallFailureEvent",
+          "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry"
         },
         {
-          "$ref": "#/definitions/AbortEvent"
+          "$ref": "#/definitions/AbortEvent",
+          "description": "Session event \"abort\". Turn abort information including the reason for termination"
         },
         {
-          "$ref": "#/definitions/ToolUserRequestedEvent"
+          "$ref": "#/definitions/ToolUserRequestedEvent",
+          "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments"
         },
         {
-          "$ref": "#/definitions/ToolExecutionStartEvent"
+          "$ref": "#/definitions/ToolExecutionStartEvent",
+          "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable"
         },
         {
-          "$ref": "#/definitions/ToolExecutionPartialResultEvent"
+          "$ref": "#/definitions/ToolExecutionPartialResultEvent",
+          "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display"
         },
         {
-          "$ref": "#/definitions/ToolExecutionProgressEvent"
+          "$ref": "#/definitions/ToolExecutionProgressEvent",
+          "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message"
         },
         {
-          "$ref": "#/definitions/ToolExecutionCompleteEvent"
+          "$ref": "#/definitions/ToolExecutionCompleteEvent",
+          "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information"
         },
         {
-          "$ref": "#/definitions/SkillInvokedEvent"
+          "$ref": "#/definitions/SkillInvokedEvent",
+          "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata"
         },
         {
-          "$ref": "#/definitions/SubagentStartedEvent"
+          "$ref": "#/definitions/SubagentStartedEvent",
+          "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information"
         },
         {
-          "$ref": "#/definitions/SubagentCompletedEvent"
+          "$ref": "#/definitions/SubagentCompletedEvent",
+          "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution"
         },
         {
-          "$ref": "#/definitions/SubagentFailedEvent"
+          "$ref": "#/definitions/SubagentFailedEvent",
+          "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information"
         },
         {
-          "$ref": "#/definitions/SubagentSelectedEvent"
+          "$ref": "#/definitions/SubagentSelectedEvent",
+          "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools"
         },
         {
-          "$ref": "#/definitions/SubagentDeselectedEvent"
+          "$ref": "#/definitions/SubagentDeselectedEvent",
+          "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent"
         },
         {
-          "$ref": "#/definitions/HookStartEvent"
+          "$ref": "#/definitions/HookStartEvent",
+          "description": "Session event \"hook.start\". Hook invocation start details including type and input data"
         },
         {
-          "$ref": "#/definitions/HookEndEvent"
+          "$ref": "#/definitions/HookEndEvent",
+          "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information"
         },
         {
-          "$ref": "#/definitions/SystemMessageEvent"
+          "$ref": "#/definitions/SystemMessageEvent",
+          "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata"
         },
         {
-          "$ref": "#/definitions/SystemNotificationEvent"
+          "$ref": "#/definitions/SystemNotificationEvent",
+          "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion"
         },
         {
-          "$ref": "#/definitions/PermissionRequestedEvent"
+          "$ref": "#/definitions/PermissionRequestedEvent",
+          "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details"
         },
         {
-          "$ref": "#/definitions/PermissionCompletedEvent"
+          "$ref": "#/definitions/PermissionCompletedEvent",
+          "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal"
         },
         {
-          "$ref": "#/definitions/UserInputRequestedEvent"
+          "$ref": "#/definitions/UserInputRequestedEvent",
+          "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices"
         },
         {
-          "$ref": "#/definitions/UserInputCompletedEvent"
+          "$ref": "#/definitions/UserInputCompletedEvent",
+          "description": "Session event \"user_input.completed\". User input request completion with the user's response"
         },
         {
-          "$ref": "#/definitions/ElicitationRequestedEvent"
+          "$ref": "#/definitions/ElicitationRequestedEvent",
+          "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)"
         },
         {
-          "$ref": "#/definitions/ElicitationCompletedEvent"
+          "$ref": "#/definitions/ElicitationCompletedEvent",
+          "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response"
         },
         {
-          "$ref": "#/definitions/SamplingRequestedEvent"
+          "$ref": "#/definitions/SamplingRequestedEvent",
+          "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation"
         },
         {
-          "$ref": "#/definitions/SamplingCompletedEvent"
+          "$ref": "#/definitions/SamplingCompletedEvent",
+          "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal"
         },
         {
-          "$ref": "#/definitions/McpOauthRequiredEvent"
+          "$ref": "#/definitions/McpOauthRequiredEvent",
+          "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server"
         },
         {
-          "$ref": "#/definitions/McpOauthCompletedEvent"
+          "$ref": "#/definitions/McpOauthCompletedEvent",
+          "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification"
         },
         {
-          "$ref": "#/definitions/CustomNotificationEvent"
+          "$ref": "#/definitions/CustomNotificationEvent",
+          "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined."
         },
         {
-          "$ref": "#/definitions/ExternalToolRequestedEvent"
+          "$ref": "#/definitions/ExternalToolRequestedEvent",
+          "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution"
         },
         {
-          "$ref": "#/definitions/ExternalToolCompletedEvent"
+          "$ref": "#/definitions/ExternalToolCompletedEvent",
+          "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal"
         },
         {
-          "$ref": "#/definitions/CommandQueuedEvent"
+          "$ref": "#/definitions/CommandQueuedEvent",
+          "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution"
         },
         {
-          "$ref": "#/definitions/CommandExecuteEvent"
+          "$ref": "#/definitions/CommandExecuteEvent",
+          "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client"
         },
         {
-          "$ref": "#/definitions/CommandCompletedEvent"
+          "$ref": "#/definitions/CommandCompletedEvent",
+          "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal"
         },
         {
-          "$ref": "#/definitions/AutoModeSwitchRequestedEvent"
+          "$ref": "#/definitions/AutoModeSwitchRequestedEvent",
+          "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval"
         },
         {
-          "$ref": "#/definitions/AutoModeSwitchCompletedEvent"
+          "$ref": "#/definitions/AutoModeSwitchCompletedEvent",
+          "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification"
         },
         {
-          "$ref": "#/definitions/CommandsChangedEvent"
+          "$ref": "#/definitions/CommandsChangedEvent",
+          "description": "Session event \"commands.changed\". SDK command registration change notification"
         },
         {
-          "$ref": "#/definitions/CapabilitiesChangedEvent"
+          "$ref": "#/definitions/CapabilitiesChangedEvent",
+          "description": "Session event \"capabilities.changed\". Session capability change notification"
         },
         {
-          "$ref": "#/definitions/ExitPlanModeRequestedEvent"
+          "$ref": "#/definitions/ExitPlanModeRequestedEvent",
+          "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions"
         },
         {
-          "$ref": "#/definitions/ExitPlanModeCompletedEvent"
+          "$ref": "#/definitions/ExitPlanModeCompletedEvent",
+          "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback"
         },
         {
-          "$ref": "#/definitions/ToolsUpdatedEvent"
+          "$ref": "#/definitions/ToolsUpdatedEvent",
+          "description": "Session event \"session.tools_updated\"."
         },
         {
-          "$ref": "#/definitions/BackgroundTasksChangedEvent"
+          "$ref": "#/definitions/BackgroundTasksChangedEvent",
+          "description": "Session event \"session.background_tasks_changed\"."
         },
         {
-          "$ref": "#/definitions/SkillsLoadedEvent"
+          "$ref": "#/definitions/SkillsLoadedEvent",
+          "description": "Session event \"session.skills_loaded\"."
         },
         {
-          "$ref": "#/definitions/CustomAgentsUpdatedEvent"
+          "$ref": "#/definitions/CustomAgentsUpdatedEvent",
+          "description": "Session event \"session.custom_agents_updated\"."
         },
         {
-          "$ref": "#/definitions/McpServersLoadedEvent"
+          "$ref": "#/definitions/McpServersLoadedEvent",
+          "description": "Session event \"session.mcp_servers_loaded\"."
         },
         {
-          "$ref": "#/definitions/McpServerStatusChangedEvent"
+          "$ref": "#/definitions/McpServerStatusChangedEvent",
+          "description": "Session event \"session.mcp_server_status_changed\"."
         },
         {
-          "$ref": "#/definitions/ExtensionsLoadedEvent"
+          "$ref": "#/definitions/ExtensionsLoadedEvent",
+          "description": "Session event \"session.extensions_loaded\"."
         }
-      ]
+      ],
+      "description": "Union of all session event variants emitted by the Copilot CLI runtime."
     },
     "ShutdownCodeChanges": {
       "type": "object",
@@ -6555,7 +6837,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.shutdown"
+          "const": "session.shutdown",
+          "description": "Type discriminator. Always \"session.shutdown\"."
         },
         "data": {
           "$ref": "#/definitions/ShutdownData",
@@ -6570,6 +6853,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason",
       "title": "ShutdownEvent"
     },
     "ShutdownModelMetric": {
@@ -6600,7 +6884,8 @@
         "usage"
       ],
       "additionalProperties": false,
-      "title": "ShutdownModelMetric"
+      "title": "ShutdownModelMetric",
+      "description": "Schema for the `ShutdownModelMetric` type."
     },
     "ShutdownModelMetricRequests": {
       "type": "object",
@@ -6634,7 +6919,8 @@
         "tokenCount"
       ],
       "additionalProperties": false,
-      "title": "ShutdownModelMetricTokenDetail"
+      "title": "ShutdownModelMetricTokenDetail",
+      "description": "Schema for the `ShutdownModelMetricTokenDetail` type."
     },
     "ShutdownModelMetricUsage": {
       "type": "object",
@@ -6682,7 +6968,8 @@
         "tokenCount"
       ],
       "additionalProperties": false,
-      "title": "ShutdownTokenDetail"
+      "title": "ShutdownTokenDetail",
+      "description": "Schema for the `ShutdownTokenDetail` type."
     },
     "ShutdownType": {
       "type": "string",
@@ -6772,7 +7059,8 @@
         },
         "type": {
           "type": "string",
-          "const": "skill.invoked"
+          "const": "skill.invoked",
+          "description": "Type discriminator. Always \"skill.invoked\"."
         },
         "data": {
           "$ref": "#/definitions/SkillInvokedData",
@@ -6787,6 +7075,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata",
       "title": "SkillInvokedEvent"
     },
     "SkillsLoadedData": {
@@ -6804,7 +7093,8 @@
         "skills"
       ],
       "additionalProperties": false,
-      "title": "SkillsLoadedData"
+      "title": "SkillsLoadedData",
+      "description": "Schema for the `SkillsLoadedData` type."
     },
     "SkillsLoadedEvent": {
       "type": "object",
@@ -6833,7 +7123,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -6841,10 +7132,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.skills_loaded"
+          "const": "session.skills_loaded",
+          "description": "Type discriminator. Always \"session.skills_loaded\"."
         },
         "data": {
-          "$ref": "#/definitions/SkillsLoadedData"
+          "$ref": "#/definitions/SkillsLoadedData",
+          "description": "Schema for the `SkillsLoadedData` type."
         }
       },
       "required": [
@@ -6856,6 +7149,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.skills_loaded\".",
       "title": "SkillsLoadedEvent"
     },
     "SkillsLoadedSkill": {
@@ -6894,7 +7188,8 @@
         "enabled"
       ],
       "additionalProperties": false,
-      "title": "SkillsLoadedSkill"
+      "title": "SkillsLoadedSkill",
+      "description": "Schema for the `SkillsLoadedSkill` type."
     },
     "SnapshotRewindData": {
       "type": "object",
@@ -6943,7 +7238,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -6951,7 +7247,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.snapshot_rewind"
+          "const": "session.snapshot_rewind",
+          "description": "Type discriminator. Always \"session.snapshot_rewind\"."
         },
         "data": {
           "$ref": "#/definitions/SnapshotRewindData",
@@ -6967,6 +7264,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events",
       "title": "SnapshotRewindEvent"
     },
     "StartData": {
@@ -6999,7 +7297,11 @@
         },
         "reasoningEffort": {
           "type": "string",
-          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\", \"xhigh\")"
+          "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\")"
+        },
+        "reasoningSummary": {
+          "$ref": "#/definitions/ReasoningSummary",
+          "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")"
         },
         "context": {
           "$ref": "#/definitions/WorkingDirectoryContext",
@@ -7011,7 +7313,7 @@
         },
         "remoteSteerable": {
           "type": "boolean",
-          "description": "Whether this session supports remote steering via Mission Control"
+          "description": "Whether this session supports remote steering via GitHub"
         },
         "detachedFromSpawningParentSessionId": {
           "type": "string",
@@ -7064,7 +7366,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.start"
+          "const": "session.start",
+          "description": "Type discriminator. Always \"session.start\"."
         },
         "data": {
           "$ref": "#/definitions/StartData",
@@ -7079,6 +7382,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.start\". Session initialization metadata including context and configuration",
       "title": "StartEvent"
     },
     "SubagentCompletedData": {
@@ -7157,7 +7461,8 @@
         },
         "type": {
           "type": "string",
-          "const": "subagent.completed"
+          "const": "subagent.completed",
+          "description": "Type discriminator. Always \"subagent.completed\"."
         },
         "data": {
           "$ref": "#/definitions/SubagentCompletedData",
@@ -7172,6 +7477,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution",
       "title": "SubagentCompletedEvent"
     },
     "SubagentDeselectedData": {
@@ -7216,7 +7522,8 @@
         },
         "type": {
           "type": "string",
-          "const": "subagent.deselected"
+          "const": "subagent.deselected",
+          "description": "Type discriminator. Always \"subagent.deselected\"."
         },
         "data": {
           "$ref": "#/definitions/SubagentDeselectedData",
@@ -7231,6 +7538,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent",
       "title": "SubagentDeselectedEvent"
     },
     "SubagentFailedData": {
@@ -7314,7 +7622,8 @@
         },
         "type": {
           "type": "string",
-          "const": "subagent.failed"
+          "const": "subagent.failed",
+          "description": "Type discriminator. Always \"subagent.failed\"."
         },
         "data": {
           "$ref": "#/definitions/SubagentFailedData",
@@ -7329,6 +7638,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information",
       "title": "SubagentFailedEvent"
     },
     "SubagentSelectedData": {
@@ -7401,7 +7711,8 @@
         },
         "type": {
           "type": "string",
-          "const": "subagent.selected"
+          "const": "subagent.selected",
+          "description": "Type discriminator. Always \"subagent.selected\"."
         },
         "data": {
           "$ref": "#/definitions/SubagentSelectedData",
@@ -7416,6 +7727,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools",
       "title": "SubagentSelectedEvent"
     },
     "SubagentStartedData": {
@@ -7487,7 +7799,8 @@
         },
         "type": {
           "type": "string",
-          "const": "subagent.started"
+          "const": "subagent.started",
+          "description": "Type discriminator. Always \"subagent.started\"."
         },
         "data": {
           "$ref": "#/definitions/SubagentStartedData",
@@ -7502,6 +7815,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information",
       "title": "SubagentStartedEvent"
     },
     "SystemMessageData": {
@@ -7567,7 +7881,8 @@
         },
         "type": {
           "type": "string",
-          "const": "system.message"
+          "const": "system.message",
+          "description": "Type discriminator. Always \"system.message\"."
         },
         "data": {
           "$ref": "#/definitions/SystemMessageData",
@@ -7582,6 +7897,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata",
       "title": "SystemMessageEvent"
     },
     "SystemMessageMetadata": {
@@ -7639,7 +7955,8 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "agent_completed"
+          "const": "agent_completed",
+          "description": "Type discriminator. Always \"agent_completed\"."
         },
         "agentId": {
           "type": "string",
@@ -7669,7 +7986,8 @@
         "status"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationAgentCompleted"
+      "title": "SystemNotificationAgentCompleted",
+      "description": "Schema for the `SystemNotificationAgentCompleted` type."
     },
     "SystemNotificationAgentCompletedStatus": {
       "type": "string",
@@ -7685,7 +8003,8 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "agent_idle"
+          "const": "agent_idle",
+          "description": "Type discriminator. Always \"agent_idle\"."
         },
         "agentId": {
           "type": "string",
@@ -7706,7 +8025,8 @@
         "agentType"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationAgentIdle"
+      "title": "SystemNotificationAgentIdle",
+      "description": "Schema for the `SystemNotificationAgentIdle` type."
     },
     "SystemNotificationData": {
       "type": "object",
@@ -7763,7 +8083,8 @@
         },
         "type": {
           "type": "string",
-          "const": "system.notification"
+          "const": "system.notification",
+          "description": "Type discriminator. Always \"system.notification\"."
         },
         "data": {
           "$ref": "#/definitions/SystemNotificationData",
@@ -7778,6 +8099,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion",
       "title": "SystemNotificationEvent"
     },
     "SystemNotificationInstructionDiscovered": {
@@ -7785,7 +8107,8 @@
       "properties": {
         "type": {
           "type": "string",
-          "const": "instruction_discovered"
+          "const": "instruction_discovered",
+          "description": "Type discriminator. Always \"instruction_discovered\"."
         },
         "sourcePath": {
           "type": "string",
@@ -7811,14 +8134,16 @@
         "triggerTool"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationInstructionDiscovered"
+      "title": "SystemNotificationInstructionDiscovered",
+      "description": "Schema for the `SystemNotificationInstructionDiscovered` type."
     },
     "SystemNotificationNewInboxMessage": {
       "type": "object",
       "properties": {
         "type": {
           "type": "string",
-          "const": "new_inbox_message"
+          "const": "new_inbox_message",
+          "description": "Type discriminator. Always \"new_inbox_message\"."
         },
         "entryId": {
           "type": "string",
@@ -7845,14 +8170,16 @@
         "summary"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationNewInboxMessage"
+      "title": "SystemNotificationNewInboxMessage",
+      "description": "Schema for the `SystemNotificationNewInboxMessage` type."
     },
     "SystemNotificationShellCompleted": {
       "type": "object",
       "properties": {
         "type": {
           "type": "string",
-          "const": "shell_completed"
+          "const": "shell_completed",
+          "description": "Type discriminator. Always \"shell_completed\"."
         },
         "shellId": {
           "type": "string",
@@ -7872,14 +8199,16 @@
         "shellId"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationShellCompleted"
+      "title": "SystemNotificationShellCompleted",
+      "description": "Schema for the `SystemNotificationShellCompleted` type."
     },
     "SystemNotificationShellDetachedCompleted": {
       "type": "object",
       "properties": {
         "type": {
           "type": "string",
-          "const": "shell_detached_completed"
+          "const": "shell_detached_completed",
+          "description": "Type discriminator. Always \"shell_detached_completed\"."
         },
         "shellId": {
           "type": "string",
@@ -7895,7 +8224,8 @@
         "shellId"
       ],
       "additionalProperties": false,
-      "title": "SystemNotificationShellDetachedCompleted"
+      "title": "SystemNotificationShellDetachedCompleted",
+      "description": "Schema for the `SystemNotificationShellDetachedCompleted` type."
     },
     "TaskCompleteData": {
       "type": "object",
@@ -7949,7 +8279,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.task_complete"
+          "const": "session.task_complete",
+          "description": "Type discriminator. Always \"session.task_complete\"."
         },
         "data": {
           "$ref": "#/definitions/TaskCompleteData",
@@ -7964,6 +8295,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent",
       "title": "TaskCompleteEvent"
     },
     "TitleChangedData": {
@@ -8008,7 +8340,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -8016,7 +8349,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.title_changed"
+          "const": "session.title_changed",
+          "description": "Type discriminator. Always \"session.title_changed\"."
         },
         "data": {
           "$ref": "#/definitions/TitleChangedData",
@@ -8032,6 +8366,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.title_changed\". Session title change payload containing the new display title",
       "title": "TitleChangedEvent"
     },
     "ToolExecutionCompleteContent": {
@@ -8398,7 +8733,8 @@
         },
         "type": {
           "type": "string",
-          "const": "tool.execution_complete"
+          "const": "tool.execution_complete",
+          "description": "Type discriminator. Always \"tool.execution_complete\"."
         },
         "data": {
           "$ref": "#/definitions/ToolExecutionCompleteData",
@@ -8413,6 +8749,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information",
       "title": "ToolExecutionCompleteEvent"
     },
     "ToolExecutionCompleteResult": {
@@ -8489,7 +8826,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -8497,7 +8835,8 @@
         },
         "type": {
           "type": "string",
-          "const": "tool.execution_partial_result"
+          "const": "tool.execution_partial_result",
+          "description": "Type discriminator. Always \"tool.execution_partial_result\"."
         },
         "data": {
           "$ref": "#/definitions/ToolExecutionPartialData",
@@ -8513,6 +8852,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display",
       "title": "ToolExecutionPartialResultEvent"
     },
     "ToolExecutionProgressData": {
@@ -8562,7 +8902,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -8570,7 +8911,8 @@
         },
         "type": {
           "type": "string",
-          "const": "tool.execution_progress"
+          "const": "tool.execution_progress",
+          "description": "Type discriminator. Always \"tool.execution_progress\"."
         },
         "data": {
           "$ref": "#/definitions/ToolExecutionProgressData",
@@ -8586,6 +8928,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message",
       "title": "ToolExecutionProgressEvent"
     },
     "ToolExecutionStartData": {
@@ -8663,7 +9006,8 @@
         },
         "type": {
           "type": "string",
-          "const": "tool.execution_start"
+          "const": "tool.execution_start",
+          "description": "Type discriminator. Always \"tool.execution_start\"."
         },
         "data": {
           "$ref": "#/definitions/ToolExecutionStartData",
@@ -8678,20 +9022,23 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable",
       "title": "ToolExecutionStartEvent"
     },
     "ToolsUpdatedData": {
       "type": "object",
       "properties": {
         "model": {
-          "type": "string"
+          "type": "string",
+          "description": "Identifier of the model the resolved tools apply to."
         }
       },
       "required": [
         "model"
       ],
       "additionalProperties": false,
-      "title": "ToolsUpdatedData"
+      "title": "ToolsUpdatedData",
+      "description": "Schema for the `ToolsUpdatedData` type."
     },
     "ToolsUpdatedEvent": {
       "type": "object",
@@ -8720,7 +9067,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -8728,10 +9076,12 @@
         },
         "type": {
           "type": "string",
-          "const": "session.tools_updated"
+          "const": "session.tools_updated",
+          "description": "Type discriminator. Always \"session.tools_updated\"."
         },
         "data": {
-          "$ref": "#/definitions/ToolsUpdatedData"
+          "$ref": "#/definitions/ToolsUpdatedData",
+          "description": "Schema for the `ToolsUpdatedData` type."
         }
       },
       "required": [
@@ -8743,6 +9093,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.tools_updated\".",
       "title": "ToolsUpdatedEvent"
     },
     "ToolUserRequestedData": {
@@ -8803,7 +9154,8 @@
         },
         "type": {
           "type": "string",
-          "const": "tool.user_requested"
+          "const": "tool.user_requested",
+          "description": "Type discriminator. Always \"tool.user_requested\"."
         },
         "data": {
           "$ref": "#/definitions/ToolUserRequestedData",
@@ -8818,6 +9170,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments",
       "title": "ToolUserRequestedEvent"
     },
     "TruncationData": {
@@ -8905,7 +9258,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.truncation"
+          "const": "session.truncation",
+          "description": "Type discriminator. Always \"session.truncation\"."
         },
         "data": {
           "$ref": "#/definitions/TruncationData",
@@ -8920,6 +9274,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics",
       "title": "TruncationEvent"
     },
     "UsageInfoData": {
@@ -8990,7 +9345,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -8998,7 +9354,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.usage_info"
+          "const": "session.usage_info",
+          "description": "Type discriminator. Always \"session.usage_info\"."
         },
         "data": {
           "$ref": "#/definitions/UsageInfoData",
@@ -9014,6 +9371,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts",
       "title": "UsageInfoEvent"
     },
     "UserInputCompletedData": {
@@ -9066,7 +9424,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -9074,7 +9433,8 @@
         },
         "type": {
           "type": "string",
-          "const": "user_input.completed"
+          "const": "user_input.completed",
+          "description": "Type discriminator. Always \"user_input.completed\"."
         },
         "data": {
           "$ref": "#/definitions/UserInputCompletedData",
@@ -9090,6 +9450,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"user_input.completed\". User input request completion with the user's response",
       "title": "UserInputCompletedEvent"
     },
     "UserInputRequestedData": {
@@ -9154,7 +9515,8 @@
         },
         "ephemeral": {
           "type": "boolean",
-          "const": true
+          "const": true,
+          "description": "Always true for events that are transient and not persisted to the session event log on disk."
         },
         "agentId": {
           "type": "string",
@@ -9162,7 +9524,8 @@
         },
         "type": {
           "type": "string",
-          "const": "user_input.requested"
+          "const": "user_input.requested",
+          "description": "Type discriminator. Always \"user_input.requested\"."
         },
         "data": {
           "$ref": "#/definitions/UserInputRequestedData",
@@ -9178,6 +9541,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices",
       "title": "UserInputRequestedEvent"
     },
     "UserMessageAgentMode": {
@@ -9529,7 +9893,8 @@
         "content"
       ],
       "additionalProperties": false,
-      "title": "UserMessageData"
+      "title": "UserMessageData",
+      "description": "Schema for the `UserMessageData` type."
     },
     "UserMessageEvent": {
       "type": "object",
@@ -9566,10 +9931,12 @@
         },
         "type": {
           "type": "string",
-          "const": "user.message"
+          "const": "user.message",
+          "description": "Type discriminator. Always \"user.message\"."
         },
         "data": {
-          "$ref": "#/definitions/UserMessageData"
+          "$ref": "#/definitions/UserMessageData",
+          "description": "Schema for the `UserMessageData` type."
         }
       },
       "required": [
@@ -9580,6 +9947,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"user.message\".",
       "title": "UserMessageEvent"
     },
     "UserToolSessionApproval": {
@@ -9633,7 +10001,8 @@
         "commandIdentifiers"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalCommands"
+      "title": "UserToolSessionApprovalCommands",
+      "description": "Schema for the `UserToolSessionApprovalCommands` type."
     },
     "UserToolSessionApprovalCustomTool": {
       "type": "object",
@@ -9653,7 +10022,8 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalCustomTool"
+      "title": "UserToolSessionApprovalCustomTool",
+      "description": "Schema for the `UserToolSessionApprovalCustomTool` type."
     },
     "UserToolSessionApprovalExtensionManagement": {
       "type": "object",
@@ -9672,7 +10042,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalExtensionManagement"
+      "title": "UserToolSessionApprovalExtensionManagement",
+      "description": "Schema for the `UserToolSessionApprovalExtensionManagement` type."
     },
     "UserToolSessionApprovalExtensionPermissionAccess": {
       "type": "object",
@@ -9692,7 +10063,8 @@
         "extensionName"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalExtensionPermissionAccess"
+      "title": "UserToolSessionApprovalExtensionPermissionAccess",
+      "description": "Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type."
     },
     "UserToolSessionApprovalMcp": {
       "type": "object",
@@ -9720,7 +10092,8 @@
         "toolName"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalMcp"
+      "title": "UserToolSessionApprovalMcp",
+      "description": "Schema for the `UserToolSessionApprovalMcp` type."
     },
     "UserToolSessionApprovalMemory": {
       "type": "object",
@@ -9735,7 +10108,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalMemory"
+      "title": "UserToolSessionApprovalMemory",
+      "description": "Schema for the `UserToolSessionApprovalMemory` type."
     },
     "UserToolSessionApprovalRead": {
       "type": "object",
@@ -9750,7 +10124,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalRead"
+      "title": "UserToolSessionApprovalRead",
+      "description": "Schema for the `UserToolSessionApprovalRead` type."
     },
     "UserToolSessionApprovalWrite": {
       "type": "object",
@@ -9765,7 +10140,8 @@
         "kind"
       ],
       "additionalProperties": false,
-      "title": "UserToolSessionApprovalWrite"
+      "title": "UserToolSessionApprovalWrite",
+      "description": "Schema for the `UserToolSessionApprovalWrite` type."
     },
     "WarningData": {
       "type": "object",
@@ -9827,7 +10203,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.warning"
+          "const": "session.warning",
+          "description": "Type discriminator. Always \"session.warning\"."
         },
         "data": {
           "$ref": "#/definitions/WarningData",
@@ -9842,6 +10219,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.warning\". Warning message for timeline display with categorization",
       "title": "WarningEvent"
     },
     "WorkingDirectoryContext": {
@@ -9951,7 +10329,8 @@
         },
         "type": {
           "type": "string",
-          "const": "session.workspace_file_changed"
+          "const": "session.workspace_file_changed",
+          "description": "Type discriminator. Always \"session.workspace_file_changed\"."
         },
         "data": {
           "$ref": "#/definitions/WorkspaceFileChangedData",
@@ -9966,6 +10345,7 @@
         "data"
       ],
       "additionalProperties": false,
+      "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type",
       "title": "WorkspaceFileChangedEvent"
     },
     "WorkspaceFileChangedOperation": {
@@ -9978,5 +10358,6 @@
       "title": "WorkspaceFileChangedOperation"
     }
   },
-  "$schema": "http://json-schema.org/draft-07/schema#"
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "JSON Schema for session events emitted by the Copilot CLI runtime."
 }
diff --git a/src/github/copilot_sdk.clj b/src/github/copilot_sdk.clj
index 283c21e..f62e193 100644
--- a/src/github/copilot_sdk.clj
+++ b/src/github/copilot_sdk.clj
@@ -783,6 +783,45 @@
   [session]
   (session/get-messages session))
 
+(defn handle-pending-tool-call!
+  "Manually resolve a pending external tool call (upstream PR #1308).
+
+   Use this when a tool was declared without a `:handler` and the runtime
+   emitted a `:copilot/external_tool.requested` event. Read the `:request-id`
+   from `(:data event)` and supply either `:result` or `:error`.
+
+   Options:
+   - :request-id - String request id from the event (required)
+   - :result     - Tool result (string, map, or other; normalized for the wire)
+   - :error      - Error message (string). Mutually exclusive with :result."
+  [session opts]
+  (session/handle-pending-tool-call! session opts))
+
+(defn <handle-pending-tool-call!
+  "core.async variant of `handle-pending-tool-call!`. Returns a channel."
+  [session opts]
+  (session/<handle-pending-tool-call! session opts))
+
+(defn handle-pending-permission-request!
+  "Manually resolve a pending permission request (upstream PR #1308).
+
+   Use this when no `:on-permission-request` handler was registered and the
+   runtime emitted a `:copilot/permission.requested` event. Read the
+   `:request-id` from `(:data event)` and supply a decision in `:result`.
+
+   Options:
+   - :request-id - String request id from the event (required)
+   - :result     - Permission decision map `{:kind k ...}`. `:no-result` is
+                   not allowed for the pending RPC — to decline answering,
+                   simply don't call this function."
+  [session opts]
+  (session/handle-pending-permission-request! session opts))
+
+(defn <handle-pending-permission-request!
+  "core.async variant of `handle-pending-permission-request!`. Returns a channel."
+  [session opts]
+  (session/<handle-pending-permission-request! session opts))
+
 (defn disconnect!
   "Disconnects the session and releases in-memory resources (event handlers,
    tool handlers, permission handler). Session data on disk is preserved for
diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj
index 7abcb35..c94d5df 100644
--- a/src/github/copilot_sdk/client.clj
+++ b/src/github/copilot_sdk/client.clj
@@ -267,8 +267,11 @@
 
 (defn- handle-v3-tool-requested!
   "Handle v3 external_tool.requested broadcast event.
-   Calls the session's tool handler and responds via the
-   session.tools.handlePendingToolCall RPC method."
+   When a tool handler is registered for `tool-name`, calls it and
+   responds via `session.tools.handlePendingToolCall`.
+   When no handler is registered (upstream PR #1308 — declaration-only tool),
+   leaves the call PENDING — the consumer is expected to resolve it via
+   `handle-pending-tool-call!`."
   [client session-id event]
   (let [data (:data event)
         request-id (:request-id data)
@@ -276,8 +279,11 @@
         tool-call-id (:tool-call-id data)
         arguments (:arguments data)
         traceparent (:traceparent data)
-        tracestate (:tracestate data)]
-    (when (and request-id tool-name)
+        tracestate (:tracestate data)
+        ;; Upstream PR #1308: skip auto-resolution for declaration-only tools.
+        handler-registered? (some? (get-in @(:state client)
+                                           [:sessions session-id :tool-handlers tool-name]))]
+    (when (and request-id tool-name handler-registered?)
       (go
         (try
           (let [tool-response (<! (session/handle-tool-call!
@@ -307,18 +313,24 @@
 
 (defn- handle-v3-permission-requested!
   "Handle v3 permission.requested broadcast event.
-   Calls the session's permission handler and responds via the
-   session.permissions.handlePendingPermissionRequest RPC method.
-   When the handler returns :no-result, the RPC call is skipped
-   so the extension does not answer this permission request.
+   When a permission handler is registered, calls it and responds via
+   `session.permissions.handlePendingPermissionRequest`. When no handler is
+   registered (upstream PR #1308 — optional callbacks), leaves the request
+   PENDING for the consumer to resolve via `handle-pending-permission-request!`.
+   When the handler returns :no-result, the RPC call is skipped so the
+   extension does not answer this permission request.
    When :resolved-by-hook is true, the runtime already resolved
    this permission via a permissionRequest hook — skip the handler
    entirely (the event is still published to subscribers)."
   [client session-id event]
   (let [data (:data event)
         request-id (:request-id data)
-        permission-request (:permission-request data)]
+        permission-request (:permission-request data)
+        ;; Upstream PR #1308: skip auto-resolution when no permission handler.
+        handler-registered? (some? (get-in @(:state client)
+                                           [:sessions session-id :permission-handler]))]
     (when (and request-id permission-request
+               handler-registered?
                (not (:resolved-by-hook data)))
       (go
         (try
@@ -1346,11 +1358,6 @@
 (defn- validate-session-config!
   "Validate session config, throwing on invalid input."
   [config]
-  (when-not (:on-permission-request config)
-    (throw (ex-info (str "An :on-permission-request handler is required when creating a session. "
-                         "For example, to allow all permissions, use "
-                         "{:on-permission-request copilot/approve-all}.")
-                    {:config config})))
   (when-not (s/valid? ::specs/session-config config)
     (let [unknown (specs/unknown-keys config specs/session-config-keys)
           explain (s/explain-data ::specs/session-config config)
@@ -1501,6 +1508,8 @@
       (assoc :enable-session-telemetry (:enable-session-telemetry? config))
       (:remote-session config)
       (assoc :remote-session (name (:remote-session config)))
+      (:cloud config)
+      (assoc :cloud (util/clj->wire (:cloud config)))
       (:model-capabilities config)
       (assoc :model-capabilities (util/clj->wire (:model-capabilities config)))
       true (assoc :include-sub-agent-streaming-events
@@ -1609,8 +1618,13 @@
 (defn create-session
   "Create a new conversation session.
    
-   Config options (`:on-permission-request` is **required**):
-   - :on-permission-request - Permission handler function (**required**, e.g. `approve-all`)
+   Config options (`:on-permission-request` is **optional** since upstream
+   PR #1308 — omit it to leave permission requests pending for manual
+   resolution via `copilot/handle-pending-permission-request!`):
+   - :on-permission-request - Permission handler function (optional, e.g. `approve-all`).
+                              When omitted, permission requests are surfaced as
+                              `:copilot/permission.requested` events and remain
+                              pending until resolved by the application.
    - :session-id         - Custom session ID
    - :client-name        - Client name to identify the application (included in User-Agent header)
    - :model              - Model to use (e.g., \"gpt-5.4\")
@@ -1658,6 +1672,11 @@
    - :remote-session     - Keyword. Per-session Mission Control remote mode: :off, :export, or :on.
                            Forwarded as `remoteSession` on session.create. When omitted, the CLI
                            applies its default. (upstream PR #1295, CLI 1.0.48)
+   - :cloud              - Map. Creates a remote session in the cloud instead of a local session.
+                           Optional `:repository` associates the cloud session with a GitHub
+                           repository: `{:repository {:owner \"...\" :name \"...\" :branch \"...\"}}`.
+                           `:branch` is optional. Forwarded as `cloud` on session.create.
+                           (upstream PR #1306)
    
    Returns a CopilotSession."
   [client config]
@@ -1694,8 +1713,13 @@
 (defn resume-session
   "Resume an existing session by ID.
    
-   Config options (`:on-permission-request` is **required**):
-   - :on-permission-request - Permission handler function (**required**, e.g. `approve-all`)
+   Config options (`:on-permission-request` is **optional** since upstream
+   PR #1308 — omit it to leave permission requests pending for manual
+   resolution via `copilot/handle-pending-permission-request!`):
+   - :on-permission-request - Permission handler function (optional, e.g. `approve-all`).
+                              When omitted, permission requests are surfaced as
+                              `:copilot/permission.requested` events and remain
+                              pending until resolved by the application.
    - :client-name        - Client name to identify the application (included in User-Agent header)
    - :model              - Change the model for the resumed session
    - :tools              - Tools exposed to the CLI server
@@ -1734,11 +1758,6 @@
    
    Returns a CopilotSession."
   [client session-id config]
-  (when-not (:on-permission-request config)
-    (throw (ex-info (str "An :on-permission-request handler is required when resuming a session. "
-                         "For example, to allow all permissions, use "
-                         "{:on-permission-request copilot/approve-all}.")
-                    {:config config})))
   (when-not (s/valid? ::specs/resume-session-config config)
     (throw (ex-info "Invalid resume session config"
                     {:config config
@@ -1775,7 +1794,8 @@
 (defn <create-session
   "Async version of create-session. Returns a channel that delivers a CopilotSession.
 
-   Same config options as create-session (`:on-permission-request` is **required**).
+   Same config options as create-session (`:on-permission-request` is **optional**
+   since upstream PR #1308).
    Validation is performed synchronously (throws immediately on invalid config).
    The RPC call parks instead of blocking, making this safe to use inside go blocks.
 
@@ -1834,7 +1854,8 @@
 (defn <resume-session
   "Async version of resume-session. Returns a channel that delivers a CopilotSession.
 
-   Same config options as resume-session (`:on-permission-request` is **required**).
+   Same config options as resume-session (`:on-permission-request` is **optional**
+   since upstream PR #1308).
    Validation is performed synchronously (throws immediately on invalid config).
    The RPC call parks instead of blocking, making this safe to use inside go blocks.
 
@@ -1851,11 +1872,6 @@
            ;; use result as session
            )))"
   [client session-id config]
-  (when-not (:on-permission-request config)
-    (throw (ex-info (str "An :on-permission-request handler is required when resuming a session. "
-                         "For example, to allow all permissions, use "
-                         "{:on-permission-request copilot/approve-all}.")
-                    {:config config})))
   (when-not (s/valid? ::specs/resume-session-config config)
     (throw (ex-info "Invalid resume session config"
                     {:config config
diff --git a/src/github/copilot_sdk/generated/event_specs.clj b/src/github/copilot_sdk/generated/event_specs.clj
index 61a3d2c..4e5fbf3 100644
--- a/src/github/copilot_sdk/generated/event_specs.clj
+++ b/src/github/copilot_sdk/generated/event_specs.clj
@@ -73,9 +73,9 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/compaction-tokens-used clojure.core/map?)
 
-(s/def :github.copilot-sdk.generated.event-specs/content (s/spec (fn [v941] (or (s/valid? clojure.core/string? v941) (s/valid? clojure.core/map? v941)))))
+(s/def :github.copilot-sdk.generated.event-specs/content (s/spec (fn [v943] (or (s/valid? clojure.core/string? v943) (s/valid? clojure.core/map? v943)))))
 
-(s/def :github.copilot-sdk.generated.event-specs/context (s/spec (fn [v939] (or (s/valid? clojure.core/map? v939) (s/valid? clojure.core/string? v939)))))
+(s/def :github.copilot-sdk.generated.event-specs/context (s/spec (fn [v941] (or (s/valid? clojure.core/map? v941) (s/valid? clojure.core/string? v941)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/continue-pending-work clojure.core/boolean?)
 
@@ -101,6 +101,8 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id clojure.core/string?)
 
+(s/def :github.copilot-sdk.generated.event-specs/display-prompt clojure.core/string?)
+
 (s/def :github.copilot-sdk.generated.event-specs/duration clojure.core/number?)
 
 (s/def :github.copilot-sdk.generated.event-specs/duration-ms clojure.core/number?)
@@ -113,7 +115,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/ephemeral clojure.core/boolean?)
 
-(s/def :github.copilot-sdk.generated.event-specs/error (s/spec (fn [v937] (or (s/valid? clojure.core/string? v937) (s/valid? clojure.core/map? v937)))))
+(s/def :github.copilot-sdk.generated.event-specs/error (s/spec (fn [v938] (or (s/valid? clojure.core/string? v938) (s/valid? clojure.core/map? v938)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/error-code clojure.core/string?)
 
@@ -147,7 +149,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/host-type #{"github" "ado"})
 
-(s/def :github.copilot-sdk.generated.event-specs/id (s/spec (fn [v938] (or (s/valid? clojure.core/string? v938) (s/valid? clojure.core/integer? v938)))))
+(s/def :github.copilot-sdk.generated.event-specs/id (s/spec (fn [v939] (or (s/valid? clojure.core/string? v939) (s/valid? clojure.core/integer? v939)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/info-type clojure.core/string?)
 
@@ -205,7 +207,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/new-model clojure.core/string?)
 
-(s/def :github.copilot-sdk.generated.event-specs/operation (s/spec (fn [v940] (or (s/valid? #{"delete" "update" "create"} v940) (s/valid? #{"update" "create"} v940)))))
+(s/def :github.copilot-sdk.generated.event-specs/operation (s/spec (fn [v942] (or (s/valid? #{"delete" "update" "create"} v942) (s/valid? #{"update" "create"} v942)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/output clojure.core/any?)
 
@@ -255,6 +257,8 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/previous-reasoning-effort clojure.core/string?)
 
+(s/def :github.copilot-sdk.generated.event-specs/previous-reasoning-summary #{"detailed" "none" "concise"})
+
 (s/def :github.copilot-sdk.generated.event-specs/producer clojure.core/string?)
 
 (s/def :github.copilot-sdk.generated.event-specs/progress-message clojure.core/string?)
@@ -271,12 +275,14 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/reason #{"user_abort" "remote_command" "user_initiated"})
 
-(s/def :github.copilot-sdk.generated.event-specs/reasoning-effort clojure.core/string?)
+(s/def :github.copilot-sdk.generated.event-specs/reasoning-effort (s/spec (fn [v940] (or (s/valid? clojure.core/string? v940) (s/valid? clojure.core/any? v940)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/reasoning-id clojure.core/string?)
 
 (s/def :github.copilot-sdk.generated.event-specs/reasoning-opaque clojure.core/string?)
 
+(s/def :github.copilot-sdk.generated.event-specs/reasoning-summary #{"detailed" "none" "concise"})
+
 (s/def :github.copilot-sdk.generated.event-specs/reasoning-text clojure.core/string?)
 
 (s/def :github.copilot-sdk.generated.event-specs/reasoning-tokens clojure.core/number?)
@@ -289,7 +295,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/remote-steerable clojure.core/boolean?)
 
-(s/def :github.copilot-sdk.generated.event-specs/repository (s/spec (fn [v936] (or (s/valid? clojure.core/map? v936) (s/valid? clojure.core/string? v936)))))
+(s/def :github.copilot-sdk.generated.event-specs/repository (s/spec (fn [v937] (or (s/valid? clojure.core/map? v937) (s/valid? clojure.core/string? v937)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/repository-host clojure.core/string?)
 
@@ -301,7 +307,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/response clojure.core/string?)
 
-(s/def :github.copilot-sdk.generated.event-specs/result (s/spec (fn [v945] (or (s/valid? clojure.core/map? v945) (s/valid? (s/or :branch-0 clojure.core/map? :branch-1 clojure.core/map? :branch-2 clojure.core/map? :branch-3 clojure.core/map? :branch-4 clojure.core/map? :branch-5 clojure.core/map? :branch-6 clojure.core/map? :branch-7 clojure.core/map? :branch-8 clojure.core/map?) v945)))))
+(s/def :github.copilot-sdk.generated.event-specs/result (s/spec (fn [v947] (or (s/valid? clojure.core/map? v947) (s/valid? (s/or :branch-0 clojure.core/map? :branch-1 clojure.core/map? :branch-2 clojure.core/map? :branch-3 clojure.core/map? :branch-4 clojure.core/map? :branch-5 clojure.core/map? :branch-6 clojure.core/map? :branch-7 clojure.core/map? :branch-8 clojure.core/map?) v947)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/resume-time clojure.core/string?)
 
@@ -329,7 +335,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/skills (s/coll-of clojure.core/map?))
 
-(s/def :github.copilot-sdk.generated.event-specs/source (s/spec (fn [v942] (or (s/valid? clojure.core/string? v942) (s/valid? #{"top_level" "subagent" "mcp_sampling"} v942)))))
+(s/def :github.copilot-sdk.generated.event-specs/source (s/spec (fn [v944] (or (s/valid? clojure.core/string? v944) (s/valid? #{"top_level" "subagent" "mcp_sampling"} v944)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/source-type #{"remote" "local"})
 
@@ -403,7 +409,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/turn-id clojure.core/string?)
 
-(s/def :github.copilot-sdk.generated.event-specs/type (s/spec (fn [v943] (or (s/valid? #{"session.start"} v943) (s/valid? #{"session.resume"} v943) (s/valid? #{"session.remote_steerable_changed"} v943) (s/valid? #{"session.error"} v943) (s/valid? #{"session.idle"} v943) (s/valid? #{"session.title_changed"} v943) (s/valid? #{"session.schedule_created"} v943) (s/valid? #{"session.schedule_cancelled"} v943) (s/valid? #{"session.info"} v943) (s/valid? #{"session.warning"} v943) (s/valid? #{"session.model_change"} v943) (s/valid? #{"session.mode_changed"} v943) (s/valid? #{"session.plan_changed"} v943) (s/valid? #{"session.workspace_file_changed"} v943) (s/valid? #{"session.handoff"} v943) (s/valid? #{"session.truncation"} v943) (s/valid? #{"session.snapshot_rewind"} v943) (s/valid? #{"session.shutdown"} v943) (s/valid? #{"session.context_changed"} v943) (s/valid? #{"session.usage_info"} v943) (s/valid? #{"session.compaction_start"} v943) (s/valid? #{"session.compaction_complete"} v943) (s/valid? #{"session.task_complete"} v943) (s/valid? #{"user.message"} v943) (s/valid? #{"pending_messages.modified"} v943) (s/valid? #{"assistant.turn_start"} v943) (s/valid? #{"assistant.intent"} v943) (s/valid? #{"assistant.reasoning"} v943) (s/valid? #{"assistant.reasoning_delta"} v943) (s/valid? #{"assistant.streaming_delta"} v943) (s/valid? #{"assistant.message"} v943) (s/valid? #{"assistant.message_start"} v943) (s/valid? #{"assistant.message_delta"} v943) (s/valid? #{"assistant.turn_end"} v943) (s/valid? #{"assistant.usage"} v943) (s/valid? #{"model.call_failure"} v943) (s/valid? #{"abort"} v943) (s/valid? #{"tool.user_requested"} v943) (s/valid? #{"tool.execution_start"} v943) (s/valid? #{"tool.execution_partial_result"} v943) (s/valid? #{"tool.execution_progress"} v943) (s/valid? #{"tool.execution_complete"} v943) (s/valid? #{"skill.invoked"} v943) (s/valid? #{"subagent.started"} v943) (s/valid? #{"subagent.completed"} v943) (s/valid? #{"subagent.failed"} v943) (s/valid? #{"subagent.selected"} v943) (s/valid? #{"subagent.deselected"} v943) (s/valid? #{"hook.start"} v943) (s/valid? #{"hook.end"} v943) (s/valid? #{"system.message"} v943) (s/valid? #{"system.notification"} v943) (s/valid? #{"permission.requested"} v943) (s/valid? #{"permission.completed"} v943) (s/valid? #{"user_input.requested"} v943) (s/valid? #{"user_input.completed"} v943) (s/valid? #{"elicitation.requested"} v943) (s/valid? #{"elicitation.completed"} v943) (s/valid? #{"sampling.requested"} v943) (s/valid? #{"sampling.completed"} v943) (s/valid? #{"mcp.oauth_required"} v943) (s/valid? #{"mcp.oauth_completed"} v943) (s/valid? #{"session.custom_notification"} v943) (s/valid? #{"external_tool.requested"} v943) (s/valid? #{"external_tool.completed"} v943) (s/valid? #{"command.queued"} v943) (s/valid? #{"command.execute"} v943) (s/valid? #{"command.completed"} v943) (s/valid? #{"auto_mode_switch.requested"} v943) (s/valid? #{"auto_mode_switch.completed"} v943) (s/valid? #{"commands.changed"} v943) (s/valid? #{"capabilities.changed"} v943) (s/valid? #{"exit_plan_mode.requested"} v943) (s/valid? #{"exit_plan_mode.completed"} v943) (s/valid? #{"session.tools_updated"} v943) (s/valid? #{"session.background_tasks_changed"} v943) (s/valid? #{"session.skills_loaded"} v943) (s/valid? #{"session.custom_agents_updated"} v943) (s/valid? #{"session.mcp_servers_loaded"} v943) (s/valid? #{"session.mcp_server_status_changed"} v943) (s/valid? #{"session.extensions_loaded"} v943)))))
+(s/def :github.copilot-sdk.generated.event-specs/type (s/spec (fn [v945] (or (s/valid? #{"session.start"} v945) (s/valid? #{"session.resume"} v945) (s/valid? #{"session.remote_steerable_changed"} v945) (s/valid? #{"session.error"} v945) (s/valid? #{"session.idle"} v945) (s/valid? #{"session.title_changed"} v945) (s/valid? #{"session.schedule_created"} v945) (s/valid? #{"session.schedule_cancelled"} v945) (s/valid? #{"session.info"} v945) (s/valid? #{"session.warning"} v945) (s/valid? #{"session.model_change"} v945) (s/valid? #{"session.mode_changed"} v945) (s/valid? #{"session.plan_changed"} v945) (s/valid? #{"session.workspace_file_changed"} v945) (s/valid? #{"session.handoff"} v945) (s/valid? #{"session.truncation"} v945) (s/valid? #{"session.snapshot_rewind"} v945) (s/valid? #{"session.shutdown"} v945) (s/valid? #{"session.context_changed"} v945) (s/valid? #{"session.usage_info"} v945) (s/valid? #{"session.compaction_start"} v945) (s/valid? #{"session.compaction_complete"} v945) (s/valid? #{"session.task_complete"} v945) (s/valid? #{"user.message"} v945) (s/valid? #{"pending_messages.modified"} v945) (s/valid? #{"assistant.turn_start"} v945) (s/valid? #{"assistant.intent"} v945) (s/valid? #{"assistant.reasoning"} v945) (s/valid? #{"assistant.reasoning_delta"} v945) (s/valid? #{"assistant.streaming_delta"} v945) (s/valid? #{"assistant.message"} v945) (s/valid? #{"assistant.message_start"} v945) (s/valid? #{"assistant.message_delta"} v945) (s/valid? #{"assistant.turn_end"} v945) (s/valid? #{"assistant.usage"} v945) (s/valid? #{"model.call_failure"} v945) (s/valid? #{"abort"} v945) (s/valid? #{"tool.user_requested"} v945) (s/valid? #{"tool.execution_start"} v945) (s/valid? #{"tool.execution_partial_result"} v945) (s/valid? #{"tool.execution_progress"} v945) (s/valid? #{"tool.execution_complete"} v945) (s/valid? #{"skill.invoked"} v945) (s/valid? #{"subagent.started"} v945) (s/valid? #{"subagent.completed"} v945) (s/valid? #{"subagent.failed"} v945) (s/valid? #{"subagent.selected"} v945) (s/valid? #{"subagent.deselected"} v945) (s/valid? #{"hook.start"} v945) (s/valid? #{"hook.end"} v945) (s/valid? #{"system.message"} v945) (s/valid? #{"system.notification"} v945) (s/valid? #{"permission.requested"} v945) (s/valid? #{"permission.completed"} v945) (s/valid? #{"user_input.requested"} v945) (s/valid? #{"user_input.completed"} v945) (s/valid? #{"elicitation.requested"} v945) (s/valid? #{"elicitation.completed"} v945) (s/valid? #{"sampling.requested"} v945) (s/valid? #{"sampling.completed"} v945) (s/valid? #{"mcp.oauth_required"} v945) (s/valid? #{"mcp.oauth_completed"} v945) (s/valid? #{"session.custom_notification"} v945) (s/valid? #{"external_tool.requested"} v945) (s/valid? #{"external_tool.completed"} v945) (s/valid? #{"command.queued"} v945) (s/valid? #{"command.execute"} v945) (s/valid? #{"command.completed"} v945) (s/valid? #{"auto_mode_switch.requested"} v945) (s/valid? #{"auto_mode_switch.completed"} v945) (s/valid? #{"commands.changed"} v945) (s/valid? #{"capabilities.changed"} v945) (s/valid? #{"exit_plan_mode.requested"} v945) (s/valid? #{"exit_plan_mode.completed"} v945) (s/valid? #{"session.tools_updated"} v945) (s/valid? #{"session.background_tasks_changed"} v945) (s/valid? #{"session.skills_loaded"} v945) (s/valid? #{"session.custom_agents_updated"} v945) (s/valid? #{"session.mcp_servers_loaded"} v945) (s/valid? #{"session.mcp_server_status_changed"} v945) (s/valid? #{"session.extensions_loaded"} v945)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/ui clojure.core/map?)
 
@@ -411,7 +417,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/url clojure.core/string?)
 
-(s/def :github.copilot-sdk.generated.event-specs/version (s/spec (fn [v944] (or (s/valid? clojure.core/number? v944) (s/valid? clojure.core/integer? v944)))))
+(s/def :github.copilot-sdk.generated.event-specs/version (s/spec (fn [v946] (or (s/valid? clojure.core/number? v946) (s/valid? clojure.core/integer? v946)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/warning-type clojure.core/string?)
 
@@ -515,17 +521,17 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/session.mode_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-mode :github.copilot-sdk.generated.event-specs/previous-mode]))
 
-(s/def :github.copilot-sdk.generated.event-specs/session.model_change-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-model] :opt-un [:github.copilot-sdk.generated.event-specs/cause :github.copilot-sdk.generated.event-specs/previous-model :github.copilot-sdk.generated.event-specs/previous-reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-effort]))
+(s/def :github.copilot-sdk.generated.event-specs/session.model_change-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/new-model] :opt-un [:github.copilot-sdk.generated.event-specs/cause :github.copilot-sdk.generated.event-specs/previous-model :github.copilot-sdk.generated.event-specs/previous-reasoning-effort :github.copilot-sdk.generated.event-specs/previous-reasoning-summary :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary]))
 
 (s/def :github.copilot-sdk.generated.event-specs/session.plan_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/operation]))
 
 (s/def :github.copilot-sdk.generated.event-specs/session.remote_steerable_changed-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/remote-steerable]))
 
-(s/def :github.copilot-sdk.generated.event-specs/session.resume-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/event-count :github.copilot-sdk.generated.event-specs/resume-time] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/continue-pending-work :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model :github.copilot-sdk.generated.event-specs/session-was-active]))
+(s/def :github.copilot-sdk.generated.event-specs/session.resume-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/event-count :github.copilot-sdk.generated.event-specs/resume-time] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/continue-pending-work :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model :github.copilot-sdk.generated.event-specs/session-was-active]))
 
 (s/def :github.copilot-sdk.generated.event-specs/session.schedule_cancelled-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id]) (fn [data] (s/valid? clojure.core/integer? (:id data)))))
 
-(s/def :github.copilot-sdk.generated.event-specs/session.schedule_created-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id :github.copilot-sdk.generated.event-specs/interval-ms :github.copilot-sdk.generated.event-specs/prompt] :opt-un [:github.copilot-sdk.generated.event-specs/recurring]) (fn [data] (s/valid? clojure.core/integer? (:id data)))))
+(s/def :github.copilot-sdk.generated.event-specs/session.schedule_created-data (s/and (s/keys :req-un [:github.copilot-sdk.generated.event-specs/id :github.copilot-sdk.generated.event-specs/interval-ms :github.copilot-sdk.generated.event-specs/prompt] :opt-un [:github.copilot-sdk.generated.event-specs/display-prompt :github.copilot-sdk.generated.event-specs/recurring]) (fn [data] (s/valid? clojure.core/integer? (:id data)))))
 
 (s/def :github.copilot-sdk.generated.event-specs/session.shutdown-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/code-changes :github.copilot-sdk.generated.event-specs/model-metrics :github.copilot-sdk.generated.event-specs/session-start-time :github.copilot-sdk.generated.event-specs/shutdown-type :github.copilot-sdk.generated.event-specs/total-api-duration-ms :github.copilot-sdk.generated.event-specs/total-premium-requests] :opt-un [:github.copilot-sdk.generated.event-specs/conversation-tokens :github.copilot-sdk.generated.event-specs/current-model :github.copilot-sdk.generated.event-specs/current-tokens :github.copilot-sdk.generated.event-specs/error-reason :github.copilot-sdk.generated.event-specs/system-tokens :github.copilot-sdk.generated.event-specs/token-details :github.copilot-sdk.generated.event-specs/tool-definitions-tokens :github.copilot-sdk.generated.event-specs/total-nano-aiu]))
 
@@ -533,7 +539,7 @@
 
 (s/def :github.copilot-sdk.generated.event-specs/session.snapshot_rewind-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/events-removed :github.copilot-sdk.generated.event-specs/up-to-event-id]))
 
-(s/def :github.copilot-sdk.generated.event-specs/session.start-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/copilot-version :github.copilot-sdk.generated.event-specs/producer :github.copilot-sdk.generated.event-specs/session-id :github.copilot-sdk.generated.event-specs/start-time :github.copilot-sdk.generated.event-specs/version] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model]))
+(s/def :github.copilot-sdk.generated.event-specs/session.start-data (s/keys :req-un [:github.copilot-sdk.generated.event-specs/copilot-version :github.copilot-sdk.generated.event-specs/producer :github.copilot-sdk.generated.event-specs/session-id :github.copilot-sdk.generated.event-specs/start-time :github.copilot-sdk.generated.event-specs/version] :opt-un [:github.copilot-sdk.generated.event-specs/already-in-use :github.copilot-sdk.generated.event-specs/context :github.copilot-sdk.generated.event-specs/detached-from-spawning-parent-session-id :github.copilot-sdk.generated.event-specs/reasoning-effort :github.copilot-sdk.generated.event-specs/reasoning-summary :github.copilot-sdk.generated.event-specs/remote-steerable :github.copilot-sdk.generated.event-specs/selected-model]))
 
 (s/def :github.copilot-sdk.generated.event-specs/session.task_complete-data (s/keys :opt-un [:github.copilot-sdk.generated.event-specs/success :github.copilot-sdk.generated.event-specs/summary]))
 
diff --git a/src/github/copilot_sdk/instrument.clj b/src/github/copilot_sdk/instrument.clj
index 5155c1e..f4efa3e 100644
--- a/src/github/copilot_sdk/instrument.clj
+++ b/src/github/copilot_sdk/instrument.clj
@@ -220,6 +220,31 @@
   :args (s/cat :session ::specs/session)
   :ret (s/coll-of map?))
 
+;; Upstream PR #1308: manual resolution of pending tool calls and permission
+;; requests. Inner functions perform more thorough validation (e.g. permission
+;; :kind enum, mutual exclusivity of :result/:error). The fdef only enforces
+;; the universally-required :request-id; the rest is checked at call time so
+;; the spec doesn't have to mirror the full result/decision shape here.
+(register-fdef! github.copilot-sdk.session/handle-pending-tool-call!
+  :args (s/cat :session ::specs/session
+               :opts (s/keys :req-un [::specs/request-id]))
+  :ret any?)
+
+(register-fdef! github.copilot-sdk.session/<handle-pending-tool-call!
+  :args (s/cat :session ::specs/session
+               :opts (s/keys :req-un [::specs/request-id]))
+  :ret any?)
+
+(register-fdef! github.copilot-sdk.session/handle-pending-permission-request!
+  :args (s/cat :session ::specs/session
+               :opts (s/keys :req-un [::specs/request-id]))
+  :ret any?)
+
+(register-fdef! github.copilot-sdk.session/<handle-pending-permission-request!
+  :args (s/cat :session ::specs/session
+               :opts (s/keys :req-un [::specs/request-id]))
+  :ret any?)
+
 (register-fdef! github.copilot-sdk.session/destroy!
   :args (s/alt :handle (s/cat :session ::specs/session)
                :explicit (s/cat :client ::specs/client
diff --git a/src/github/copilot_sdk/session.clj b/src/github/copilot_sdk/session.clj
index 0887e74..623a9cc 100644
--- a/src/github/copilot_sdk/session.clj
+++ b/src/github/copilot_sdk/session.clj
@@ -9,6 +9,7 @@
   (:require [clojure.core.async :as async :refer [go go-loop <! >! >!! <!! chan close! put! alts!! mult tap untap]]
             [clojure.core.async.impl.protocols :as async-protocols]
             [clojure.spec.alpha :as s]
+            [clojure.string :as str]
             [clojure.data.json :as json]
             [github.copilot-sdk.protocol :as proto]
             [github.copilot-sdk.logging :as log]
@@ -58,7 +59,14 @@
   (let [event-chan (chan (async/sliding-buffer 4096))
         event-mult (mult event-chan)
         send-lock (doto (chan 1) (>!! :token))
-        tool-handlers (into {} (map (fn [t] [(:tool-name t) (:tool-handler t)]) tools))
+        ;; Upstream PR #1308: declaration-only tools (no :tool-handler) are
+        ;; left out of the handler map — they're distinguished from tools with
+        ;; handlers, and unhandled invocations are left pending for manual
+        ;; resolution via handle-pending-tool-call!.
+        tool-handlers (into {} (keep (fn [t]
+                                       (when-let [h (:tool-handler t)]
+                                         [(:tool-name t) h]))
+                                     tools))
         command-handlers (into {} (map (fn [c] [(:name c) (:command-handler c)]) commands))]
     ;; Store session state and IO in client's atom
     (swap! (:state client)
@@ -631,11 +639,18 @@
                              "sessionEnd" :on-session-end
                              "errorOccurred" :on-error-occurred
                              nil)
-               handler (when handler-key (get hooks handler-key))]
-           (if-not handler
-             {:result nil}
-             (try
-               (let [result (handler input {:session-id session-id})
+           handler (when handler-key (get hooks handler-key))]
+       (if-not handler
+         {:result nil}
+         (try
+           (let [;; Upstream PR #1290: BaseHookInput.sessionId. Preserve the
+                 ;; wire-provided :session-id when present (it may identify a
+                 ;; sub-agent session distinct from the outer session-id);
+                 ;; otherwise fall back to the outer session-id.
+                 input (cond-> input
+                         (not (contains? input :session-id))
+                         (assoc :session-id session-id))
+                 result (handler input {:session-id session-id})
                      ;; If handler returns a channel, await it
                      result (if (channel? result)
                               (<!! result)
@@ -1203,6 +1218,151 @@
           result (proto/send-request! conn "session.getMessages" {:session-id session-id})]
       (mapv coerce+normalize-event (:events result)))))
 
+(def ^:private supported-permission-decision-kinds
+  "Accepted `:kind` values when manually resolving a pending permission
+   request via `handle-pending-permission-request!`. Matches the upstream
+   `PermissionDecision` schema (api.schema.json `$defs/PermissionDecision`),
+   which is the union of six variants:
+   `PermissionDecisionApproveOnce`, `PermissionDecisionApproveForSession`,
+   `PermissionDecisionApproveForLocation`, `PermissionDecisionApprovePermanently`,
+   `PermissionDecisionReject`, `PermissionDecisionUserNotAvailable`.
+   `:no-result` is deliberately excluded — to decline answering, do not call
+   the resolver."
+  #{:approve-once
+    :approve-for-session
+    :approve-for-location
+    :approve-permanently
+    :reject
+    :user-not-available})
+
+(defn- check-pending-request-id!
+  "Validate the :request-id supplied to a pending-RPC resolver. Must be a
+   non-blank string."
+  [request-id opts]
+  (when-not (and (string? request-id) (not (str/blank? request-id)))
+    (throw (ex-info ":request-id must be a non-blank string" {:opts opts}))))
+
+(defn- check-pending-permission-result!
+  "Validate the :result map supplied to a pending permission resolver. Must be
+   a map with a keyword `:kind` from `supported-permission-decision-kinds`."
+  [result opts]
+  (when-not (and (map? result) (contains? result :kind))
+    (throw (ex-info ":result must be a map with a :kind key" {:opts opts})))
+  (let [kind (:kind result)]
+    (when-not (keyword? kind)
+      (throw (ex-info ":result :kind must be a keyword" {:opts opts :kind kind})))
+    (when (= :no-result kind)
+      (throw (ex-info ":no-result is not a valid decision for the pending RPC"
+                      {:opts opts})))
+    (when-not (contains? supported-permission-decision-kinds kind)
+      (throw (ex-info ":result :kind is not a supported permission decision"
+                      {:opts opts
+                       :kind kind
+                       :supported supported-permission-decision-kinds})))))
+
+(defn handle-pending-tool-call!
+  "Manually resolve a pending external tool call (upstream PR #1308).
+
+   Use this when a tool was declared without a `:handler` and the runtime has
+   emitted a `:copilot/external_tool.requested` event. The consumer reads the
+   `:request-id` from `(:data event)` and supplies either `:result` (the tool
+   result string or map) or `:error` (a string message).
+
+   Options map keys:
+   - :request-id - The `:request-id` from the external_tool.requested event (required)
+   - :result     - Tool result (string, map, or anything `normalize-tool-result` accepts)
+   - :error      - Error message (string). Mutually exclusive with `:result`.
+
+   Returns the RPC result map (sync). Use `<handle-pending-tool-call!` for the
+   core.async variant."
+  [session {:keys [request-id result error] :as opts}]
+  (let [{:keys [session-id client]} session]
+    (when (:destroyed? (session-state client session-id))
+      (throw (ex-info "Session has been disconnected" {:session-id session-id})))
+    (check-pending-request-id! request-id opts)
+    (when-not (or (contains? opts :result) (contains? opts :error))
+      (throw (ex-info "exactly one of :result or :error is required" {:opts opts})))
+    (when (and (contains? opts :result) (contains? opts :error))
+      (throw (ex-info ":result and :error are mutually exclusive" {:opts opts})))
+    (when (and (contains? opts :error) (not (string? error)))
+      (throw (ex-info ":error must be a string when provided" {:opts opts})))
+    (let [conn (connection-io client)
+          base {:session-id session-id :request-id request-id}
+          params (cond
+                   (some? error) (assoc base :error error)
+                   :else (assoc base :result (normalize-tool-result result)))]
+      (proto/send-request! conn "session.tools.handlePendingToolCall" params))))
+
+(defn <handle-pending-tool-call!
+  "core.async variant of `handle-pending-tool-call!`. Returns a channel."
+  [session opts]
+  (let [{:keys [session-id client]} session
+        {:keys [request-id result error]} opts]
+    (when (:destroyed? (session-state client session-id))
+      (throw (ex-info "Session has been disconnected" {:session-id session-id})))
+    (check-pending-request-id! request-id opts)
+    (when-not (or (contains? opts :result) (contains? opts :error))
+      (throw (ex-info "exactly one of :result or :error is required" {:opts opts})))
+    (when (and (contains? opts :result) (contains? opts :error))
+      (throw (ex-info ":result and :error are mutually exclusive" {:opts opts})))
+    (when (and (contains? opts :error) (not (string? error)))
+      (throw (ex-info ":error must be a string when provided" {:opts opts})))
+    (let [conn (connection-io client)
+          base {:session-id session-id :request-id request-id}
+          params (cond
+                   (some? error) (assoc base :error error)
+                   :else (assoc base :result (normalize-tool-result result)))]
+      (proto/send-request conn "session.tools.handlePendingToolCall" params))))
+
+(defn handle-pending-permission-request!
+  "Manually resolve a pending permission request (upstream PR #1308).
+
+   Use this when no `:on-permission-request` handler was registered and the
+   runtime has emitted a `:copilot/permission.requested` event. The consumer
+   reads the `:request-id` from `(:data event)` and supplies a permission
+   decision in `:result`.
+
+   Options map keys:
+   - :request-id - The `:request-id` from the permission.requested event (required)
+   - :result     - Permission decision map with `:kind`, matching the upstream
+                   `PermissionDecision` union. Allowed kinds:
+                   `:approve-once`, `:approve-for-session`,
+                   `:approve-for-location`, `:approve-permanently`,
+                   `:reject`, `:user-not-available`. `:no-result` is not
+                   supported here — to decline answering, simply don't call
+                   this function.
+
+   Returns the RPC result map (sync). Use ``copilot/<handle-pending-permission-request!``
+   for the core.async variant."
+  [session {:keys [request-id result] :as opts}]
+  (let [{:keys [session-id client]} session]
+    (when (:destroyed? (session-state client session-id))
+      (throw (ex-info "Session has been disconnected" {:session-id session-id})))
+    (check-pending-request-id! request-id opts)
+    (check-pending-permission-result! result opts)
+    (let [conn (connection-io client)
+          normalized (normalize-permission-result result)]
+      (proto/send-request! conn "session.permissions.handlePendingPermissionRequest"
+                           {:session-id session-id
+                            :request-id request-id
+                            :result normalized}))))
+
+(defn <handle-pending-permission-request!
+  "core.async variant of `handle-pending-permission-request!`. Returns a channel."
+  [session opts]
+  (let [{:keys [session-id client]} session
+        {:keys [request-id result]} opts]
+    (when (:destroyed? (session-state client session-id))
+      (throw (ex-info "Session has been disconnected" {:session-id session-id})))
+    (check-pending-request-id! request-id opts)
+    (check-pending-permission-result! result opts)
+    (let [conn (connection-io client)
+          normalized (normalize-permission-result result)]
+      (proto/send-request conn "session.permissions.handlePendingPermissionRequest"
+                          {:session-id session-id
+                           :request-id request-id
+                           :result normalized}))))
+
 (defn disconnect!
   "Disconnects the session and releases in-memory resources (event handlers,
    tool handlers, permission handler). Session data on disk (conversation
diff --git a/src/github/copilot_sdk/specs.clj b/src/github/copilot_sdk/specs.clj
index 368e3d9..a2c0aaf 100644
--- a/src/github/copilot_sdk/specs.clj
+++ b/src/github/copilot_sdk/specs.clj
@@ -172,8 +172,12 @@
 (s/def ::skip-permission? boolean?)
 
 (s/def ::tool
-  (s/keys :req-un [::tool-name ::tool-handler]
-          :opt-un [::tool-description ::tool-parameters ::overrides-built-in-tool ::skip-permission?]))
+  ;; Upstream PR #1308: handler is now optional. Tools without a handler are
+  ;; declaration-only — they're surfaced as `external_tool.requested` events
+  ;; and the consumer resolves them via `handle-pending-tool-call!`.
+  (s/keys :req-un [::tool-name]
+          :opt-un [::tool-handler ::tool-description ::tool-parameters
+                   ::overrides-built-in-tool ::skip-permission?]))
 
 (s/def ::tools (s/coll-of ::tool))
 
@@ -523,12 +527,16 @@
     :enable-config-discovery :model-capabilities :github-token
     :enable-session-telemetry?
     :remote-session
+    :cloud
     :include-sub-agent-streaming-events?})
 
 (s/def ::session-config
   (closed-keys
-   (s/keys :req-un [::on-permission-request]
-           :opt-un [::session-id ::client-name ::model ::tools ::commands ::system-message
+   ;; Upstream PR #1308: :on-permission-request is now optional. When omitted,
+   ;; permission requests are surfaced as events and left pending for the
+   ;; consumer to resolve via `handle-pending-permission-request!`.
+   (s/keys :opt-un [::on-permission-request
+                    ::session-id ::client-name ::model ::tools ::commands ::system-message
                     ::available-tools ::excluded-tools ::provider
                     ::streaming? ::mcp-servers
                     ::custom-agents ::default-agent ::config-dir ::skill-directories
@@ -540,6 +548,7 @@
                     ::enable-config-discovery ::model-capabilities ::github-token
                     ::enable-session-telemetry?
                     ::remote-session
+                    ::cloud
                     ::include-sub-agent-streaming-events?])
    session-config-keys))
 
@@ -559,8 +568,9 @@
 
 (s/def ::resume-session-config
   (closed-keys
-   (s/keys :req-un [::on-permission-request]
-           :opt-un [::client-name ::model ::tools ::commands ::system-message ::available-tools ::excluded-tools
+   ;; Upstream PR #1308: :on-permission-request is now optional.
+   (s/keys :opt-un [::on-permission-request
+                    ::client-name ::model ::tools ::commands ::system-message ::available-tools ::excluded-tools
                     ::provider ::streaming?
                     ::mcp-servers ::custom-agents ::default-agent ::config-dir ::skill-directories
                     ::instruction-directories
@@ -901,6 +911,29 @@
                (s/valid? ::remote-session-mode (:mode m))))))
 
 (s/def ::agent-mode #{:interactive :plan :autopilot :shell})
+
+;; Cloud session config (upstream PR #1306). When supplied to create-session,
+;; creates a remote session in the cloud instead of a local session. Optional
+;; :repository associates the cloud session with a GitHub repository.
+;;
+;; The literal :repository key inside cloud is a MAP — different from the
+;; existing top-level ::repository spec which is a string used elsewhere.
+;; Validate :repository against ::cloud-repository here via s/and, avoiding
+;; a name collision in s/keys :opt-un.
+(s/def ::owner ::non-blank-string)
+;; The :name key inside ::cloud-repository must be non-blank. The shared
+;; ::name spec is just `string?` (it is reused by many event/data shapes
+;; where blanks are valid), so we enforce non-blankness here with a
+;; predicate rather than redefining ::name globally.
+(s/def ::cloud-repository
+  (s/and (s/keys :req-un [::owner ::name]
+                 :opt-un [::branch])
+         #(not (clojure.string/blank? (:name %)))))
+(s/def ::cloud
+  (s/and map?
+         (fn [m]
+           (or (not (contains? m :repository))
+               (s/valid? ::cloud-repository (:repository m))))))
 (s/def ::interaction-id string?)
 (s/def ::source string?)
 
diff --git a/src/github/copilot_sdk/tools.clj b/src/github/copilot_sdk/tools.clj
index d61e83d..6ce9fc2 100644
--- a/src/github/copilot_sdk/tools.clj
+++ b/src/github/copilot_sdk/tools.clj
@@ -4,18 +4,27 @@
             [clojure.string :as str]))
 
 (defn define-tool
-  "Define a tool with a handler function.
+  "Define a tool the CLI server can call during a session.
    
    Arguments:
    - name        - Tool name (string)
    - opts map:
      - :description             - Tool description
      - :parameters              - JSON schema for parameters (or nil)
-     - :handler                 - Function (fn [args invocation] -> result)
+     - :handler                 - Function (fn [args invocation] -> result).
+                                  **Optional** since upstream PR #1308: when
+                                  omitted, the tool is declaration-only and
+                                  the runtime emits a
+                                  `:copilot/external_tool.requested` event
+                                  whenever the LLM calls it. Applications
+                                  resolve the pending call by reading the
+                                  `:request-id` from the event data and
+                                  calling `copilot/handle-pending-tool-call!`
+                                  (or the async ``copilot/<handle-pending-tool-call!``).
      - :overrides-built-in-tool - When true, explicitly overrides a built-in tool of the same name.
                                   Without this flag, name clashes with built-in tools cause an error.
    
-   The handler receives:
+   The handler (when provided) receives:
    - args       - The parsed arguments from the LLM (no key conversion)
    - invocation - Map with :session-id, :tool-call-id, :tool-name, :arguments
    
@@ -25,7 +34,7 @@
    - Any other value (JSON-encoded as success)
    - A core.async channel that will yield one of the above
    
-   Example:
+   Example (with handler):
    ```clojure
    (define-tool \"get_weather\"
      {:description \"Get weather for a location\"
@@ -34,12 +43,26 @@
                    :required [\"location\"]}
       :handler (fn [args _]
                  (str \"Weather in \" (:location args) \": Sunny, 72°F\"))})
+   ```
+
+   Example (declaration-only, manual resolution):
+   ```clojure
+   (define-tool \"get_weather\"
+     {:description \"Get weather for a location\"
+      :parameters {:type \"object\"
+                   :properties {:location {:type \"string\"}}}})
+   ;; Listen for :copilot/external_tool.requested events and resolve via
+   ;; (copilot/handle-pending-tool-call! session {:request-id ... :result ...})
    ```"
   [name {:keys [description parameters handler overrides-built-in-tool]}]
   (cond-> {:tool-name name
            :tool-description description
-           :tool-parameters parameters
-           :tool-handler handler}
+           :tool-parameters parameters}
+    ;; Upstream PR #1308: handler is optional. Declaration-only tools (no
+    ;; handler) are surfaced as external_tool.requested events; consumers
+    ;; resolve them via handle-pending-tool-call!.
+    (some? handler)
+    (assoc :tool-handler handler)
     (some? overrides-built-in-tool)
     (assoc :overrides-built-in-tool overrides-built-in-tool)))
 
@@ -56,10 +79,22 @@
    - opts map:
      - :description             - Tool description
      - :spec                    - A clojure.spec for the arguments
-     - :handler                 - Function (fn [args invocation] -> result)
+     - :handler                 - Function (fn [args invocation] -> result).
+                                  **Optional** since upstream PR #1308: when
+                                  omitted, no `:tool-handler` is installed
+                                  and the tool is declaration-only. The
+                                  runtime emits a
+                                  `:copilot/external_tool.requested` event
+                                  on call; applications resolve it via
+                                  `copilot/handle-pending-tool-call!`
+                                  (or ``copilot/<handle-pending-tool-call!``).
+                                  Note: when `:handler` is omitted, the
+                                  `:spec` is also not used (no automatic
+                                  validation occurs in the declaration-only
+                                  path).
      - :overrides-built-in-tool - When true, overrides a built-in tool of the same name
    
-   Example:
+   Example (with handler):
    ```clojure
    (s/def ::location string?)
    (s/def ::get-weather-args (s/keys :req-un [::location]))
@@ -72,19 +107,32 @@
                    (str \"Weather: Sunny\")
                    {:text-result-for-llm (str \"Invalid args: \" (s/explain-str ::get-weather-args args))
                     :result-type \"failure\"}))})
+   ```
+
+   Example (declaration-only, manual resolution):
+   ```clojure
+   (define-tool-from-spec \"get_weather\"
+     {:description \"Get weather for a location\"
+      :spec ::get-weather-args})
+   ;; Resolve pending calls via
+   ;; (copilot/handle-pending-tool-call! session {:request-id ... :result ...})
    ```"
   [name {:keys [description spec handler overrides-built-in-tool]}]
   ;; For now, we don't auto-convert spec to JSON schema
   ;; The handler should validate using the spec
   (cond-> {:tool-name name
            :tool-description description
-           :tool-parameters nil  ; User should provide JSON schema if needed
-           :tool-handler (fn [args invocation]
+           :tool-parameters nil}  ; User should provide JSON schema if needed
+    ;; Upstream PR #1308: handler is optional. Declaration-only tools (no
+    ;; handler) are surfaced as external_tool.requested events; consumers
+    ;; resolve them via handle-pending-tool-call!.
+    (some? handler)
+    (assoc :tool-handler (fn [args invocation]
                            (if (and spec (not (s/valid? spec args)))
                              {:text-result-for-llm (str "Invalid arguments: " (s/explain-str spec args))
                               :result-type "failure"
                               :error "spec validation failed"}
-                             (handler args invocation)))}
+                             (handler args invocation))))
     (some? overrides-built-in-tool)
     (assoc :overrides-built-in-tool overrides-built-in-tool)))
 
diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj
index 723a814..2712f0d 100644
--- a/test/github/copilot_sdk/integration_test.clj
+++ b/test/github/copilot_sdk/integration_test.clj
@@ -1192,6 +1192,65 @@
                                      {:on-permission-request sdk/approve-all
                                       :remote-session :bogus})))))
 
+(deftest test-cloud-session-config-forwarded-on-wire
+  (testing "cloud {:repository {...}} is forwarded as cloud.repository on session.create (upstream PR #1306)"
+    (let [seen (atom {})
+          _ (mock/set-request-hook! *mock-server* (fn [method params]
+                                                    (when (= "session.create" method)
+                                                      (swap! seen assoc method params))))
+          _ (sdk/create-session *test-client*
+                                {:on-permission-request sdk/approve-all
+                                 :cloud {:repository {:owner "octocat"
+                                                      :name "hello-world"
+                                                      :branch "main"}}})
+          create-params (get @seen "session.create")]
+      (is (= {:owner "octocat" :name "hello-world" :branch "main"}
+             (get-in create-params [:cloud :repository])))
+      (is (not (contains? create-params :cloud-repository)))))
+
+  (testing "cloud :repository may omit :branch"
+    (let [seen (atom {})
+          _ (mock/set-request-hook! *mock-server* (fn [method params]
+                                                    (when (= "session.create" method)
+                                                      (swap! seen assoc method params))))
+          _ (sdk/create-session *test-client*
+                                {:on-permission-request sdk/approve-all
+                                 :cloud {:repository {:owner "octocat"
+                                                      :name "hello-world"}}})
+          create-params (get @seen "session.create")]
+      (is (= {:owner "octocat" :name "hello-world"}
+             (get-in create-params [:cloud :repository])))))
+
+  (testing "cloud {} (empty options) is forwarded as empty map"
+    (let [seen (atom {})
+          _ (mock/set-request-hook! *mock-server* (fn [method params]
+                                                    (when (= "session.create" method)
+                                                      (swap! seen assoc method params))))
+          _ (sdk/create-session *test-client*
+                                {:on-permission-request sdk/approve-all
+                                 :cloud {}})
+          create-params (get @seen "session.create")]
+      (is (= {} (:cloud create-params)))))
+
+  (testing "cloud is omitted from wire when not set"
+    (let [seen (atom {})
+          _ (mock/set-request-hook! *mock-server* (fn [method params]
+                                                    (when (= "session.create" method)
+                                                      (swap! seen assoc method params))))
+          _ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
+          create-params (get @seen "session.create")]
+      (is (not (contains? create-params :cloud)))))
+
+  (testing "cloud config with invalid :repository shape is rejected by spec"
+    (is (thrown? Exception
+                 (sdk/create-session *test-client*
+                                     {:on-permission-request sdk/approve-all
+                                      :cloud {:repository {:branch "main"}}}))) ; missing :owner and :name
+    (is (thrown? Exception
+                 (sdk/create-session *test-client*
+                                     {:on-permission-request sdk/approve-all
+                                      :cloud {:repository "octocat/hello-world"}})))))
+
 (deftest test-agent-forwarded-on-wire
   (testing "agent is forwarded in session.create when set (upstream PR #722)"
     (let [seen (atom {})
@@ -1304,23 +1363,16 @@
       (is (= {:kind :approve-once}
              (sdk/approve-all {:permission-kind kind} {:session-id "s1"}))))))
 
-(deftest test-permission-handler-required
-  (testing "create-session throws without :on-permission-request"
-    (is (thrown-with-msg? clojure.lang.ExceptionInfo
-                          #"on-permission-request handler is required"
-                          (sdk/create-session *test-client* {}))))
+(deftest test-permission-handler-now-optional
+  ;; Upstream PR #1308 made :on-permission-request optional. Previously this
+  ;; test asserted that create-session/resume-session threw without it.
+  (testing "create-session succeeds without :on-permission-request"
+    (is (some? (sdk/create-session *test-client* {}))))
 
-  (testing "create-session throws with nil handler"
-    (is (thrown-with-msg? clojure.lang.ExceptionInfo
-                          #"on-permission-request handler is required"
-                          (sdk/create-session *test-client* {:on-permission-request nil}))))
-
-  (testing "resume-session throws without :on-permission-request"
-    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
-          session-id (sdk/session-id session)]
-      (is (thrown-with-msg? clojure.lang.ExceptionInfo
-                            #"on-permission-request handler is required"
-                            (sdk/resume-session *test-client* session-id {}))))))
+  (testing "resume-session succeeds without :on-permission-request"
+    (let [_ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
+          session-id (sdk/get-last-session-id *test-client*)]
+      (is (some? (sdk/resume-session *test-client* session-id {}))))))
 
 (deftest test-permission-denied-with-deny-handler
   (testing "Permission requests are denied when handler denies"
@@ -2702,6 +2754,70 @@
                                                     :cwd "/workspace"}})]
       (is (nil? (:result response))))))
 
+(deftest test-hooks-input-exposes-session-id
+  (testing "hook input includes :session-id (upstream PR #1290 — BaseHookInput.sessionId)"
+    (let [handler-called (atom nil)
+          session (sdk/create-session *test-client*
+                                      {:on-permission-request sdk/approve-all
+                                       :hooks {:on-pre-tool-use
+                                               (fn [input _ctx]
+                                                 (reset! handler-called input)
+                                                 nil)}})
+          session-id (sdk/session-id session)
+          _ (mock/send-rpc-request! *mock-server*
+                                    "hooks.invoke"
+                                    {:sessionId session-id
+                                     :hookType "preToolUse"
+                                     :input {:toolName "bash"
+                                             :toolArgs {}
+                                             :sessionId session-id
+                                             :timestamp 12345
+                                             :cwd "/workspace"}})]
+      (is (some? @handler-called))
+      (is (= session-id (:session-id @handler-called)))))
+
+  (testing "hook input :session-id preserves wire-provided value (sub-agent case)"
+    (let [handler-called (atom nil)
+          session (sdk/create-session *test-client*
+                                      {:on-permission-request sdk/approve-all
+                                       :hooks {:on-pre-tool-use
+                                               (fn [input _ctx]
+                                                 (reset! handler-called input)
+                                                 nil)}})
+          parent-session-id (sdk/session-id session)
+          sub-agent-session-id "sub-agent-session-xyz"
+          _ (mock/send-rpc-request! *mock-server*
+                                    "hooks.invoke"
+                                    {:sessionId parent-session-id
+                                     :hookType "preToolUse"
+                                     :input {:toolName "bash"
+                                             :toolArgs {}
+                                             :sessionId sub-agent-session-id
+                                             :timestamp 12345
+                                             :cwd "/workspace"}})]
+      (is (some? @handler-called))
+      (is (= sub-agent-session-id (:session-id @handler-called)))))
+
+  (testing "hook input :session-id falls back to outer session-id when wire omits it"
+    (let [handler-called (atom nil)
+          session (sdk/create-session *test-client*
+                                      {:on-permission-request sdk/approve-all
+                                       :hooks {:on-pre-tool-use
+                                               (fn [input _ctx]
+                                                 (reset! handler-called input)
+                                                 nil)}})
+          session-id (sdk/session-id session)
+          _ (mock/send-rpc-request! *mock-server*
+                                    "hooks.invoke"
+                                    {:sessionId session-id
+                                     :hookType "preToolUse"
+                                     :input {:toolName "bash"
+                                             :toolArgs {}
+                                             :timestamp 12345
+                                             :cwd "/workspace"}})]
+      (is (some? @handler-called))
+      (is (= session-id (:session-id @handler-called))))))
+
 ;; -----------------------------------------------------------------------------
 ;; User Input Handler Tests (server→client RPC)
 ;; -----------------------------------------------------------------------------
@@ -4042,3 +4158,238 @@
                   {:tool-call-id "tc-1"
                    :agent-name "rubber-duck"
                    :agent-display-name "Rubber Duck"}))))
+
+;; -----------------------------------------------------------------------------
+;; Optional callbacks (upstream PR #1308)
+;; -----------------------------------------------------------------------------
+
+(deftest test-create-session-without-permission-handler
+  (testing "create-session accepts omission of :on-permission-request (upstream PR #1308)"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})
+          create-rpcs (filter #(= "session.create" (:method %)) @requests)]
+      (is (= 1 (count create-rpcs)) "session.create still issued")
+      (is (some? (sdk/session-id session))))))
+
+(deftest test-resume-session-without-permission-handler
+  (testing "resume-session accepts omission of :on-permission-request"
+    (let [requests (atom [])
+          _ (sdk/create-session *test-client* {})
+          session-id (sdk/get-last-session-id *test-client*)
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          resumed (sdk/resume-session *test-client* session-id {})
+          resume-rpcs (filter #(= "session.resume" (:method %)) @requests)]
+      (is (= 1 (count resume-rpcs)))
+      (is (some? (sdk/session-id resumed))))))
+
+(deftest test-define-tool-without-handler
+  (testing "define-tool accepts omission of :handler (declaration-only tool, upstream PR #1308)"
+    (let [tool (tools/define-tool "manual_lookup"
+                 {:description "Look up status manually"
+                  :parameters {:type "object"
+                               :properties {:id {:type "string"}}
+                               :required ["id"]}})]
+      (is (= "manual_lookup" (:tool-name tool)))
+      (is (not (contains? tool :tool-handler))
+          "tool map must NOT contain :tool-handler key when handler omitted")
+      ;; Must pass tool spec validation (handler now optional)
+      (is (s/valid? :github.copilot-sdk.specs/tool tool))))
+
+  (testing "define-tool-from-spec accepts omission of :handler (upstream PR #1308)"
+    (let [tool (tools/define-tool-from-spec "manual_spec_tool"
+                 {:description "Declaration-only spec tool"})]
+      (is (= "manual_spec_tool" (:tool-name tool)))
+      (is (not (contains? tool :tool-handler))
+          "define-tool-from-spec must NOT install a wrapper handler when :handler omitted")
+      (is (s/valid? :github.copilot-sdk.specs/tool tool)))))
+
+(deftest test-declaration-only-tool-not-stored-in-handler-map
+  (testing "declaration-only tools don't populate :tool-handlers"
+    (let [decl-tool (tools/define-tool "decl_only" {:description "decl-only"})
+          handled-tool (tools/define-tool "with_handler"
+                         {:description "has handler"
+                          :handler (fn [_ _] "ok")})
+          session (sdk/create-session *test-client*
+                                      {:on-permission-request sdk/approve-all
+                                       :tools [decl-tool handled-tool]})
+          session-id (sdk/session-id session)
+          tool-handlers (get-in @(:state *test-client*)
+                                [:sessions session-id :tool-handlers])]
+      (is (not (contains? tool-handlers "decl_only"))
+          "declaration-only tools must not be in :tool-handlers")
+      (is (contains? tool-handlers "with_handler")
+          "tools with handlers must remain in :tool-handlers"))))
+
+(deftest test-handle-pending-permission-request!-sends-rpc
+  (testing "handle-pending-permission-request! issues session.permissions.handlePendingPermissionRequest"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})]
+      (sdk/handle-pending-permission-request! session
+                                              {:request-id "req-42"
+                                               :result {:kind :approve-once}})
+      (let [pending-rpcs (filter #(= "session.permissions.handlePendingPermissionRequest"
+                                     (:method %))
+                                 @requests)]
+        (is (= 1 (count pending-rpcs)))
+        (is (= "req-42" (get-in (first pending-rpcs) [:params :requestId])))
+        ;; Result is wire-serialized via clj->wire: keyword :kind → "approve-once"
+        (is (= "approve-once" (get-in (first pending-rpcs)
+                                      [:params :result :kind]))))))
+
+  (testing "handle-pending-permission-request! accepts :user-not-available"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})]
+      (sdk/handle-pending-permission-request! session
+                                              {:request-id "req-una"
+                                               :result {:kind :user-not-available}})
+      (let [pending-rpcs (filter #(= "session.permissions.handlePendingPermissionRequest"
+                                     (:method %))
+                                 @requests)]
+        (is (= 1 (count pending-rpcs)))
+        (is (= "user-not-available" (get-in (first pending-rpcs)
+                                            [:params :result :kind]))))))
+
+  (testing "handle-pending-permission-request! accepts :approve-permanently"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})]
+      (sdk/handle-pending-permission-request! session
+                                              {:request-id "req-perm"
+                                               :result {:kind :approve-permanently}})
+      (let [pending-rpcs (filter #(= "session.permissions.handlePendingPermissionRequest"
+                                     (:method %))
+                                 @requests)]
+        (is (= 1 (count pending-rpcs)))
+        (is (= "approve-permanently" (get-in (first pending-rpcs)
+                                             [:params :result :kind]))))))
+
+  (testing "handle-pending-permission-request! rejects :no-result"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown? Exception
+                   (sdk/handle-pending-permission-request!
+                    session
+                    {:request-id "req-1" :result {:kind :no-result}})))))
+
+  (testing "handle-pending-permission-request! rejects malformed result"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown? Exception
+                   (sdk/handle-pending-permission-request!
+                    session
+                    {:request-id "req-1" :result "not-a-map"})))))
+
+  (testing "handle-pending-permission-request! rejects blank :request-id"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #":request-id must be a non-blank string"
+                            (sdk/handle-pending-permission-request!
+                             session
+                             {:request-id "" :result {:kind :approve-once}})))
+      (is (thrown-with-msg? Exception #":request-id must be a non-blank string"
+                            (sdk/handle-pending-permission-request!
+                             session
+                             {:request-id "   " :result {:kind :approve-once}})))))
+
+  (testing "handle-pending-permission-request! rejects non-keyword :kind"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #":kind must be a keyword"
+                            (sdk/handle-pending-permission-request!
+                             session
+                             {:request-id "req-1" :result {:kind "approve-once"}})))
+      (is (thrown-with-msg? Exception #":kind must be a keyword"
+                            (sdk/handle-pending-permission-request!
+                             session
+                             {:request-id "req-1" :result {:kind 42}})))))
+
+  (testing "handle-pending-permission-request! rejects unsupported :kind"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #"not a supported permission decision"
+                            (sdk/handle-pending-permission-request!
+                             session
+                             {:request-id "req-1" :result {:kind :totally-made-up}}))))))
+
+(deftest test-handle-pending-tool-call!-sends-rpc
+  (testing "handle-pending-tool-call! with :result issues session.tools.handlePendingToolCall"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})]
+      (sdk/handle-pending-tool-call! session
+                                     {:request-id "tool-req-7"
+                                      :result "MANUAL_STATUS_OK"})
+      (let [pending (filter #(= "session.tools.handlePendingToolCall" (:method %))
+                            @requests)]
+        (is (= 1 (count pending)))
+        (is (= "tool-req-7" (get-in (first pending) [:params :requestId])))
+        ;; String result is normalized through normalize-tool-result
+        (is (= "MANUAL_STATUS_OK"
+               (get-in (first pending) [:params :result :textResultForLlm]))))))
+
+  (testing "handle-pending-tool-call! with :error forwards error string"
+    (let [requests (atom [])
+          _ (mock/set-request-hook! *mock-server*
+                                    (fn [method params]
+                                      (swap! requests conj {:method method :params params})))
+          session (sdk/create-session *test-client* {})]
+      (sdk/handle-pending-tool-call! session
+                                     {:request-id "tool-req-8"
+                                      :error "manual failure"})
+      (let [pending (first (filter #(= "session.tools.handlePendingToolCall" (:method %))
+                                   @requests))]
+        (is (= "manual failure" (get-in pending [:params :error])))
+        (is (not (contains? (:params pending) :result))))))
+
+  (testing "handle-pending-tool-call! rejects :result and :error together"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown? Exception
+                   (sdk/handle-pending-tool-call!
+                    session
+                    {:request-id "x" :result "a" :error "b"})))))
+
+  (testing "handle-pending-tool-call! rejects non-string :error"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #":error must be a string"
+                            (sdk/handle-pending-tool-call!
+                             session
+                             {:request-id "x" :error {:code 1}})))
+      (is (thrown-with-msg? Exception #":error must be a string"
+                            (sdk/handle-pending-tool-call!
+                             session
+                             {:request-id "x" :error 42})))))
+
+  (testing "handle-pending-tool-call! requires :result or :error"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #"exactly one of :result or :error"
+                            (sdk/handle-pending-tool-call!
+                             session
+                             {:request-id "x"})))))
+
+  (testing "<handle-pending-tool-call! requires :result or :error"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #"exactly one of :result or :error"
+                            (sdk/<handle-pending-tool-call!
+                             session
+                             {:request-id "x"})))))
+
+  (testing "handle-pending-tool-call! rejects blank :request-id"
+    (let [session (sdk/create-session *test-client* {})]
+      (is (thrown-with-msg? Exception #":request-id must be a non-blank string"
+                            (sdk/handle-pending-tool-call!
+                             session
+                             {:request-id "" :result "ok"})))
+      (is (thrown-with-msg? Exception #":request-id must be a non-blank string"
+                            (sdk/handle-pending-tool-call!
+                             session
+                             {:request-id "   " :result "ok"}))))))