refactor: ElicitationRequest → ElicitationContext single-arg handler (upstream PR #960)

Port upstream PR #960 cross-SDK consistency change:
- Elicitation handler now takes single ElicitationContext arg instead of
  (request, ctx) — context includes :session-id alongside request fields
- Rename ::elicitation-request spec to ::elicitation-context, add :session-id
- Update all handler call sites, tests, example, and docs
- BREAKING: handler signature change from (fn [request ctx]) to (fn [context])

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: krukow

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file. This change
 
 ## [Unreleased]
 
+### Changed (v0.2.1 sync)
+- **BREAKING**: Elicitation handler signature changed from 2-arg `(fn [request ctx])` to single-arg `(fn [context])`. The `ElicitationContext` map now includes `:session-id` alongside request fields (`:message`, `:requested-schema`, `:mode`, `:elicitation-source`, `:url`). Matches upstream cross-SDK consistency change (upstream PR #960). `::elicitation-request` spec renamed to `::elicitation-context`.
+
 ### Added (v0.2.1 sync)
 - **`remote-steerable?` field on `session.start` and `session.resume` events** — event data now includes optional `:remote-steerable?` boolean field indicating whether the session supports remote steering via Mission Control. Replaces previous `:steerable?` (upstream PRs #927, #908).
 - **`get-session-metadata`** — new function on client for efficient O(1) session lookup by ID. Returns session metadata map if found, or `nil` if not found. Sends `session.getMetadata` JSON-RPC call. Shared `wire->session-metadata` helper extracted from `list-sessions` to eliminate duplication (upstream PR #899).

doc/reference/API.md

@@ -255,7 +255,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `:hooks` | map | Lifecycle hooks (see below) |
 | `:agent` | string | Name of a custom agent to activate at session start. Must match a name in `:custom-agents`. Equivalent to calling `agent.select` after creation. |
 | `:on-event` | fn | Event handler (1-arg fn receiving event maps). Registered before the RPC call, guaranteeing early events like `session.start` are not missed. |
-| `:on-elicitation-request` | fn | Handler for elicitation requests from the agent. When provided, advertises `requestElicitation=true` and handles `elicitation.requested` broadcast events. Receives `(request ctx)` where request has `:message`, `:requested-schema`, `:mode`, `:elicitation-source`, `:url`. Returns an `ElicitationResult` map `{:action "accept"/"decline"/"cancel" :content {...}}`. See [Elicitation Provider](#elicitation-provider) |
+| `:on-elicitation-request` | fn | Handler for elicitation requests from the agent. When provided, advertises `requestElicitation=true` and handles `elicitation.requested` broadcast events. Single-arg handler receives an `ElicitationContext` map with `:session-id`, `:message`, `:requested-schema`, `:mode`, `:elicitation-source`, `:url`. Returns an `ElicitationResult` map `{:action "accept"/"decline"/"cancel" :content {...}}`. See [Elicitation Provider](#elicitation-provider) |
 | `:create-session-fs-handler` | fn | Factory for session filesystem handlers. Required when `:session-fs` is set on the client. Called as `(factory session)`, returns a map of FS handler functions. See [Session Filesystem](#session-filesystem) |
 
 #### `resume-session`
@@ -1691,19 +1691,22 @@ Provide a handler for elicitation requests from the agent. This enables the SDK
   (copilot/create-session client
     {:on-permission-request copilot/approve-all
      :on-elicitation-request
-     (fn [request {:keys [session-id]}]
-       ;; request keys: :message, :requested-schema, :mode, :elicitation-source, :url
-       (println "Elicitation:" (:message request))
+     (fn [{:keys [session-id message requested-schema mode]}]
+       (println "Elicitation for session" session-id ":" message)
        {:action "accept"
         :content {:name "user-input"}})}))
 ```
 
-The handler receives two arguments:
+The handler receives a single `ElicitationContext` map:
 
-| Argument | Description |
-|----------|-------------|
-| `request` | Map with `:message` (string), optional `:requested-schema` (JSON Schema map), `:mode` (`"form"` or `"url"`), `:elicitation-source` (string), `:url` (string) |
-| `ctx` | Map with `:session-id` (string) |
+| Key | Type | Description |
+|-----|------|-------------|
+| `:session-id` | string | Session that triggered the request |
+| `:message` | string | What information is needed from the user |
+| `:requested-schema` | map | JSON Schema describing form fields (optional) |
+| `:mode` | string | `"form"` for structured input, `"url"` for browser redirect (optional) |
+| `:elicitation-source` | string | Source that initiated the request, e.g. MCP server name (optional) |
+| `:url` | string | URL to open in browser, url mode only (optional) |
 
 Return an `ElicitationResult` map:
 

examples/elicitation_provider.clj

@@ -15,30 +15,31 @@
 (defn handle-elicitation
   "Handle an elicitation request from the runtime.
    In a real app this would render a UI dialog or open a browser.
-   Here we print the request and auto-approve."
-  [request {:keys [session-id]}]
+   Here we print the request and auto-approve.
+   Takes a single ElicitationContext map (upstream PR #960)."
+  [{:keys [session-id message mode elicitation-source url requested-schema] :as _context}]
   (println "\n📋 Elicitation request received!")
   (println "   Session:" session-id)
-  (println "   Message:" (:message request))
-  (when-let [mode (:mode request)]
+  (println "   Message:" message)
+  (when mode
     (println "   Mode:" mode))
-  (when-let [source (:elicitation-source request)]
-    (println "   Source:" source))
-  (when-let [url (:url request)]
+  (when elicitation-source
+    (println "   Source:" elicitation-source))
+  (when url
     (println "   URL:" url))
-  (when-let [schema (:requested-schema request)]
-    (println "   Schema:" (pr-str schema)))
+  (when requested-schema
+    (println "   Schema:" (pr-str requested-schema)))
 
   ;; Decide how to respond based on mode
-  (case (:mode request)
+  (case mode
     ;; URL mode: the server wants us to open a browser
     "url"
     (do
       (println "   → Auto-approving URL-based elicitation (would open browser)")
       {:action "accept"})
 
     ;; Form mode (or nil): the server wants form field values
-    (if-let [props (get-in request [:requested-schema :properties])]
+    (if-let [props (get-in requested-schema [:properties])]
       (do
         (println "   → Auto-filling form fields:")
         (let [content (reduce-kv

src/github/copilot_sdk/client.clj

@@ -355,21 +355,22 @@
 
 (defn- handle-v3-elicitation-requested!
   "Handle v3 elicitation.requested broadcast event.
-   Calls the session's elicitation handler and responds via the
-   session.ui.handlePendingElicitation RPC method.
+   Builds an ElicitationContext (single-arg, includes session-id) and calls
+   the session's elicitation handler. Responds via handlePendingElicitation RPC.
    If the handler fails, sends a cancel response to avoid hanging."
   [client session-id event]
   (let [data (:data event)
         request-id (:request-id data)]
     (when request-id
       (go
         (try
-          (let [request {:message (:message data)
+          (let [context {:session-id session-id
+                         :message (:message data)
                          :requested-schema (:requested-schema data)
                          :mode (:mode data)
                          :elicitation-source (:elicitation-source data)
                          :url (:url data)}
-                result (<! (session/handle-elicitation-request! client session-id request))]
+                result (<! (session/handle-elicitation-request! client session-id context))]
             (when result
               (let [conn (:connection-io @(:state client))]
                 (when conn
@@ -1437,10 +1438,11 @@
                             :buffer-exhaustion-threshold (0.0-1.0, default 0.95)}
    - :reasoning-effort   - Reasoning effort level: \"low\", \"medium\", \"high\", or \"xhigh\" (PR #302)
    - :on-user-input-request - Handler for ask_user requests (PR #269)
-   - :on-elicitation-request - Handler for elicitation requests from the agent (upstream PR #908).
+   - :on-elicitation-request - Handler for elicitation requests from the agent (upstream PRs #908, #960).
                                When provided, sends requestElicitation=true and enables the
-                               elicitation capability. Handler is (fn [request ctx]) returning
-                               an ElicitationResult map ({:action \"accept\" :content {...}}).
+                               elicitation capability. Single-arg handler receives an ElicitationContext
+                               map with :session-id, :message, :requested-schema, :mode,
+                               :elicitation-source, :url. Returns an ElicitationResult map.
    - :hooks              - Lifecycle hooks map (PR #269):
                            {:on-pre-tool-use, :on-post-tool-use, :on-user-prompt-submitted,
                             :on-session-start, :on-session-end, :on-error-occurred}

src/github/copilot_sdk/session.clj

@@ -428,15 +428,16 @@
 
 (defn handle-elicitation-request!
   "Handle an incoming elicitation.requested broadcast event.
-   Calls the session's elicitation handler and returns a channel with the result.
+   Calls the session's elicitation handler with a single ElicitationContext arg
+   (includes :session-id alongside request fields). Returns a channel with the result.
    If the handler fails, returns {:action \"cancel\"} to avoid hanging requests."
-  [client session-id request]
+  [client session-id context]
   (async/thread-call
    (fn []
      (let [handler (:elicitation-handler (session-state client session-id))]
        (when handler
          (try
-           (let [result (handler request {:session-id session-id})
+           (let [result (handler context)
                  result (if (channel? result) (<!! result) result)]
              (or result {:action "cancel"}))
            (catch Throwable t

src/github/copilot_sdk/specs.clj

@@ -327,13 +327,13 @@
 (s/def ::elicitation-params
   (s/keys :req-un [::message ::requested-schema]))
 
-;; Elicitation request — inbound from server when this client is an elicitation provider
+;; Elicitation context — passed to :on-elicitation-request handler (upstream PR #960).
+;; Single-arg pattern: context includes session-id alongside request fields.
 ;; Note: :mode here is "form"/"url" (different from message-options ::mode which is :enqueue/:immediate)
-;; We validate with s/and to avoid spec name collision.
 (s/def ::elicitation-source string?)
 (s/def ::url string?)
-(s/def ::elicitation-request
-  (s/and (s/keys :req-un [::message]
+(s/def ::elicitation-context
+  (s/and (s/keys :req-un [::session-id ::message]
                  :opt-un [::requested-schema ::elicitation-source ::url])
          #(if-let [m (:mode %)]
             (contains? #{"form" "url"} m)

test/github/copilot_sdk/integration_test.clj

@@ -1403,7 +1403,7 @@
                 (swap! requests conj {:method method :params params})))
           session (sdk/create-session *test-client*
                                       {:on-permission-request sdk/approve-all
-                                       :on-elicitation-request (fn [_req _ctx] {:action "cancel"})})
+                                       :on-elicitation-request (fn [_ctx] {:action "cancel"})})
           create-rpcs (filter #(= "session.create" (:method %)) @requests)]
       (is (= 1 (count create-rpcs)))
       (when (seq create-rpcs)
@@ -1434,8 +1434,8 @@
           session (sdk/create-session *test-client*
                                       {:on-permission-request sdk/approve-all
                                        :on-elicitation-request
-                                       (fn [request ctx]
-                                         (reset! handler-called {:request request :ctx ctx})
+                                       (fn [context]
+                                         (reset! handler-called context)
                                          {:action "accept"
                                           :content {:name "test-value"}})})
           session-id (sdk/session-id session)]
@@ -1451,10 +1451,10 @@
                                  :mode "form"
                                  :elicitationSource "mcp-server"})
       (is (.await rpc-latch 5 java.util.concurrent.TimeUnit/SECONDS))
-      ;; Handler was called
+      ;; Handler was called with ElicitationContext (single arg, includes session-id)
       (is (some? @handler-called))
-      (is (= "Enter your name" (:message (:request @handler-called))))
-      (is (= session-id (:session-id (:ctx @handler-called))))
+      (is (= "Enter your name" (:message @handler-called)))
+      (is (= session-id (:session-id @handler-called)))
       ;; handlePendingElicitation RPC was sent with handler's result
       (let [rpcs (filter #(= "session.ui.handlePendingElicitation" (:method %)) @requests)]
         (is (= 1 (count rpcs)))
@@ -1474,7 +1474,7 @@
           session (sdk/create-session *test-client*
                                       {:on-permission-request sdk/approve-all
                                        :on-elicitation-request
-                                       (fn [_req _ctx]
+                                       (fn [_ctx]
                                          (throw (Exception. "UI unavailable")))})
           session-id (sdk/session-id session)]
       (swap! (:state *test-client*) assoc :negotiated-protocol-version 3)