Sync with upstream copilot-sdk post-v0.2.2 (batch 2)

Port four upstream changes landed after v0.2.2:

- PR #1108: includeSubAgentStreamingEvents session option (default true)
  and :agent-id on base events.
  provider-level :headers on ProviderConfig.
- CLI 1.0.28 (PR #1089): ::can-offer-session-approval? spec for
  writeFile permission events.
- CLI 1.0.32 (PR #1105): ::reasoning-tokens spec for assistant.usage
  and session.usage_info events.

Changes:
- specs.clj: add ::include-sub-agent-streaming-events?,
  ::request-headers, ::headers (provider), ::agent-id,
  ::can-offer-session-approval?, ::reasoning-tokens. Extend
  session-config-keys and resume-session-config-keys sets plus
  corresponding :opt-un lists on ::session-config,
  ::resume-session-config, ::join-session-config, ::send-options,
  ::provider, ::base-event.
- client.clj: build-create-session-params and
  build-resume-session-params unconditionally emit
  :include-sub-agent-streaming-events with default true,
  matching upstream ?? true semantics.
- session.clj: send! and <send-async* forward :request-headers
  when set.
- API.md and CHANGELOG.md: document new options and specs.
- integration_test.clj: 8 new tests covering wire shape for
  includeSubAgentStreamingEvents (create+resume, default+explicit),
  requestHeaders (send! + send-async + omission), provider headers,
  and the three new specs.

All reviewers (Claude Opus 4.6, GPT-5.4, GPT-5.3-Codex) found the
change correct. The GPT-5 finding that :request-headers was not
forwarded through the async send path was addressed in this commit.

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

Author: krukow

CHANGELOG.md

@@ -3,6 +3,15 @@ All notable changes to this project will be documented in this file. This change
 
 ## [Unreleased]
 
+### Added (post-v0.2.2 sync, batch 2)
+- **`includeSubAgentStreamingEvents` session option** — new boolean `:include-sub-agent-streaming-events?` on `::session-config`, `::resume-session-config`, and `::join-session-config`. When `true` (default), sub-agent streaming events are forwarded to the parent session's event stream. (upstream PR #1108)
+- **Per-request HTTP headers on `send!`** — new `:request-headers` option (map of string→string) on `::send-options`. Forwarded as wire `requestHeaders` and merged with provider-level headers by the CLI. (upstream PR #1094)
+- **Provider-level HTTP headers** — new `:headers` field (map of string→string) on `::provider` config. Sent with each model request to BYOK endpoints. (upstream PR #1094)
+- **`::can-offer-session-approval?`** spec — boolean field present on `permission.requested` events of kind `writeFile`, indicating the CLI can offer a "trust this session" choice. (CLI 1.0.28, upstream PR #1089)
+- **`::reasoning-tokens`** spec — non-negative integer field on `assistant.usage` and `session.usage_info` events tracking tokens used for reasoning content. (CLI 1.0.32, upstream PR #1105)
+- **`::agent-id`** spec — optional string field on `::base-event`, identifying which (sub-)agent emitted the event. (upstream PR #1108)
+- Integration tests for all new wire fields and specs (7 new tests).
+
 ### Added (post-v0.2.2 sync)
 - **`convert-mcp-call-tool-result`** — new public function in `tools` namespace that converts MCP `CallToolResult` format into the SDK's `ToolResultObject`. Handles text, image, and resource content types. (upstream PR #1049)
 - **`default-join-session-permission-handler`** — new permission handler for `resume-session` that returns `{:kind :no-result}`, signaling the CLI to handle permissions itself. Sends `requestPermission: false` on the wire. (upstream PR #1056)

doc/reference/API.md

@@ -237,7 +237,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `:system-message` | map | System message customization (see below) |
 | `:available-tools` | vector | List of allowed tool names |
 | `:excluded-tools` | vector | List of excluded tool names |
-| `:provider` | map | Provider config for BYOK (see [BYOK docs](../auth/byok.md)). Required key: `:base-url`. Optional: `:provider-type` (`:openai`/`:azure`/`:anthropic`), `:wire-api` (`:completions`/`:responses`), `:api-key`, `:bearer-token`, `:azure-options` |
+| `:provider` | map | Provider config for BYOK (see [BYOK docs](../auth/byok.md)). Required key: `:base-url`. Optional: `:provider-type` (`:openai`/`:azure`/`:anthropic`), `:wire-api` (`:completions`/`:responses`), `:api-key`, `:bearer-token`, `:azure-options`, `:headers` (map of HTTP header name→value, sent with each provider request — upstream PR #1094) |
 | `:mcp-servers` | map | MCP server configs keyed by server ID (see [MCP docs](../mcp/overview.md)). Local (stdio) servers: `:mcp-command`, `:mcp-args`, `:mcp-tools`. Remote (HTTP/SSE) servers: `:mcp-server-type` (`:http`/`:sse`), `:mcp-url`, `:mcp-tools`. Spec aliases: `::mcp-stdio-server` = `::mcp-local-server`, `::mcp-http-server` = `::mcp-remote-server` |
 | `: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), `:mcp-servers` |
@@ -258,6 +258,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `: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) |
 | `:enable-config-discovery` | boolean | Auto-discover `.mcp.json`, `.vscode/mcp.json`, skills, etc. Instruction files always load regardless. (upstream PR #1044) |
 | `: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) |
 
 #### `resume-session`
 
@@ -683,6 +684,7 @@ Send a message to the session. Returns immediately with the message ID.
 | `:prompt` | string | The message/prompt to send |
 | `:attachments` | vector | File attachments (see below) |
 | `:mode` | keyword | `:enqueue` or `:immediate` |
+| `:request-headers` | map | Extra HTTP headers (string→string) forwarded to the model provider for this request. Merged with provider-level `:headers`. (upstream PR #1094) |
 
 **Attachment types:**
 

src/github/copilot_sdk/client.clj

@@ -1401,6 +1401,10 @@
       (assoc :enable-config-discovery (:enable-config-discovery config))
       (:model-capabilities config)
       (assoc :model-capabilities (util/clj->wire (:model-capabilities config)))
+      true (assoc :include-sub-agent-streaming-events
+                  (if (some? (:include-sub-agent-streaming-events? config))
+                    (:include-sub-agent-streaming-events? config)
+                    true))
       true (assoc :env-value-mode "direct"))))
 
 (defn- build-resume-session-params
@@ -1464,6 +1468,10 @@
       (assoc :enable-config-discovery (:enable-config-discovery config))
       (:model-capabilities config)
       (assoc :model-capabilities (util/clj->wire (:model-capabilities config)))
+      true (assoc :include-sub-agent-streaming-events
+                  (if (some? (:include-sub-agent-streaming-events? config))
+                    (:include-sub-agent-streaming-events? config)
+                    true))
       true (assoc :env-value-mode "direct"))))
 
 (defn- pre-register-session

src/github/copilot_sdk/session.clj

@@ -499,7 +499,8 @@
                           :prompt (:prompt opts)}
                    trace-ctx (merge trace-ctx)
                    wire-attachments (assoc :attachments wire-attachments)
-                   (:mode opts) (assoc :mode (name (:mode opts))))
+                   (:mode opts) (assoc :mode (name (:mode opts)))
+                   (:request-headers opts) (assoc :request-headers (:request-headers opts)))
           result (proto/send-request! conn "session.send" params)
           msg-id (:message-id result)]
       (log/debug "send! completed for session " session-id " message-id=" msg-id)
@@ -705,7 +706,8 @@
                                   :prompt (:prompt opts)}
                            trace-ctx (merge trace-ctx)
                            wire-attachments (assoc :attachments wire-attachments)
-                           (:mode opts) (assoc :mode (name (:mode opts))))
+                           (:mode opts) (assoc :mode (name (:mode opts)))
+                           (:request-headers opts) (assoc :request-headers (:request-headers opts)))
                   response-ch (proto/send-request conn "session.send" params)
                   [result port] (if deadline-ch
                                   (async/alts! [response-ch deadline-ch])

src/github/copilot_sdk/specs.clj

@@ -250,9 +250,14 @@
 (s/def ::azure-options
   (s/keys :opt-un [::azure-api-version]))
 
+;; Provider :headers — extra HTTP headers forwarded with each model request
+;; (upstream PR #1094, available since CLI 1.0.32). Map of header name → value.
+(s/def ::headers (s/map-of string? string?))
+
 (s/def ::provider
   (s/keys :req-un [::base-url]
-          :opt-un [::provider-type ::wire-api ::api-key ::bearer-token ::azure-options]))
+          :opt-un [::provider-type ::wire-api ::api-key ::bearer-token ::azure-options
+                   ::headers]))
 
 ;; -----------------------------------------------------------------------------
 ;; Session configuration
@@ -360,6 +365,10 @@
 ;; enableConfigDiscovery: auto-discover MCP configs, skills, instruction files (upstream PR #1044)
 (s/def ::enable-config-discovery boolean?)
 
+;; includeSubAgentStreamingEvents: forward streaming events from sub-agents to the parent
+;; session's event stream (upstream PR #1108). Defaults to true on the wire.
+(s/def ::include-sub-agent-streaming-events? boolean?)
+
 ;; modelCapabilities override for session config / setModel (upstream PR #1029).
 ;; DeepPartial<ModelCapabilities> — same shape as ::model-capabilities since all fields are already optional.
 
@@ -371,7 +380,8 @@
     :disabled-skills :large-output :infinite-sessions
     :reasoning-effort :on-user-input-request :on-elicitation-request :hooks
     :working-directory :agent :on-event :create-session-fs-handler
-    :enable-config-discovery :model-capabilities})
+    :enable-config-discovery :model-capabilities
+    :include-sub-agent-streaming-events?})
 
 (s/def ::session-config
   (closed-keys
@@ -383,7 +393,8 @@
                     ::disabled-skills ::large-output ::infinite-sessions
                     ::reasoning-effort ::on-user-input-request ::on-elicitation-request ::hooks
                     ::working-directory ::agent ::on-event ::create-session-fs-handler
-                    ::enable-config-discovery ::model-capabilities])
+                    ::enable-config-discovery ::model-capabilities
+                    ::include-sub-agent-streaming-events?])
    session-config-keys))
 
 (def ^:private resume-session-config-keys
@@ -392,7 +403,8 @@
     :mcp-servers :custom-agents :config-dir :skill-directories
     :disabled-skills :infinite-sessions :reasoning-effort
     :on-user-input-request :on-elicitation-request :hooks :working-directory :disable-resume? :agent :on-event
-    :create-session-fs-handler :enable-config-discovery :model-capabilities})
+    :create-session-fs-handler :enable-config-discovery :model-capabilities
+    :include-sub-agent-streaming-events?})
 
 (s/def ::resume-session-config
   (closed-keys
@@ -403,7 +415,8 @@
                     ::disabled-skills ::infinite-sessions ::reasoning-effort
                     ::on-user-input-request ::on-elicitation-request ::hooks ::working-directory ::disable-resume? ::agent
                     ::on-event ::create-session-fs-handler
-                    ::enable-config-discovery ::model-capabilities])
+                    ::enable-config-discovery ::model-capabilities
+                    ::include-sub-agent-streaming-events?])
    resume-session-config-keys))
 
 ;; join-session config: same as resume-session-config but :on-permission-request is optional.
@@ -417,7 +430,8 @@
                     ::disabled-skills ::infinite-sessions ::reasoning-effort
                     ::on-user-input-request ::on-elicitation-request ::hooks ::working-directory ::disable-resume? ::agent
                     ::on-event ::create-session-fs-handler
-                    ::enable-config-discovery ::model-capabilities])
+                    ::enable-config-discovery ::model-capabilities
+                    ::include-sub-agent-streaming-events?])
    resume-session-config-keys))
 
 ;; -----------------------------------------------------------------------------
@@ -504,9 +518,13 @@
 (s/def ::inbound-attachments (s/coll-of ::inbound-attachment))
 (s/def ::mode #{:enqueue :immediate})
 
+;; Per-request HTTP headers forwarded to the model provider (upstream PR #1094).
+;; Map of header name → value, merged with any provider-level headers.
+(s/def ::request-headers (s/map-of string? string?))
+
 (s/def ::send-options
   (s/keys :req-un [::prompt]
-          :opt-un [::attachments ::mode ::timeout-ms]))
+          :opt-un [::attachments ::mode ::timeout-ms ::request-headers]))
 
 (s/def ::timeout-ms pos-int?)
 
@@ -566,6 +584,17 @@
 (s/def ::event-timestamp ::timestamp)
 (s/def ::parent-id (s/nilable ::non-blank-string))
 (s/def ::ephemeral? boolean?)
+;; agent-id: identifies which (sub-)agent emitted an event. Present on most events
+;; once sub-agent streaming is enabled (upstream PR #1108).
+(s/def ::agent-id string?)
+
+;; canOfferSessionApproval: writeFile permission requests carry this hint indicating
+;; whether the CLI can present a "trust this session" option (upstream CLI 1.0.28).
+(s/def ::can-offer-session-approval? boolean?)
+
+;; reasoningTokens: per-message / per-session tokens used for reasoning content
+;; (upstream CLI 1.0.32). Reported on assistant.usage and session.usage_info events.
+(s/def ::reasoning-tokens nat-int?)
 
 ;; Session log specs (upstream PR #737)
 (s/def ::level #{"info" "warning" "error"})
@@ -574,7 +603,7 @@
 
 (s/def ::base-event
   (s/keys :req-un [::event-id ::event-timestamp ::parent-id]
-          :opt-un [::ephemeral?]))
+          :opt-un [::ephemeral? ::agent-id]))
 
 ;; Event type enum (namespaced under :copilot/)
 (s/def ::event-type