feat(client): implement client mode :empty (multitenancy hardening)

Add :mode #{:copilot-cli :empty} client option (default :copilot-cli)
mirroring upstream PR github/copilot-sdk#1428.

In :empty mode the SDK:

- Requires at least one tenant-scoped storage root at construction time
  (:copilot-home, :session-fs, :cli-url, or :is-child-process?) so the
  spawned CLI never falls back to the user's home directory.
- Forces COPILOT_DISABLE_KEYTAR=1 on the spawned CLI via the
  cli-env-overrides :overrides slot so the caller cannot accidentally
  re-enable the host keychain.
- Requires every create-session / resume-session call (sync + async) to
  supply :available-tools; an empty vector is legitimate, the key just
  has to be present so silently-empty filters cannot happen.
- Spreads 9 safe defaults UNDER caller session config (caller always
  wins): :enable-session-telemetry? false,
  :mcp-oauth-token-storage :in-memory, :skip-embedding-retrieval true,
  :embedding-cache-storage :in-memory,
  :enable-on-demand-instruction-discovery false,
  :enable-file-hooks false, :enable-host-git-operations false,
  :enable-session-store false, :enable-skills false.
- Normalizes :system-message so environment_context is stripped unless
  the app has taken control of it (mirrors upstream
  getSystemMessageConfigForMode): no system-message emits
  {:mode customize :sections {:environment_context {:action remove}}};
  :append is promoted to :customize preserving content; :customize
  without an env-context override gets one added; :replace passes
  through unchanged. :copilot-cli mode keeps legacy behavior.
- After session.create / session.resume succeeds, issues a follow-up
  session.options.update RPC carrying four overridable feature flags
  (:skip-custom-instructions true, :custom-agents-local-only true,
  :coauthor-enabled false, :manage-schedule-enabled false) plus
  :installed-plugins []. In :copilot-cli mode only flags the caller
  explicitly set are forwarded; an empty patch skips the RPC entirely.
  On failure the SDK disconnects and removes the half-configured
  session before rethrowing. Wired into create-session,
  resume-session, <create-session, <resume-session.

Both modes always emit :tool-filter-precedence "excluded" on
session.create / session.resume so the ordering between
:available-tools and :excluded-tools is deterministic regardless of
CLI version, and reject bare "*" in :available-tools / :excluded-tools
at the SDK boundary (matches upstream resolveToolFilterOptions).

Adds 23 new integration tests covering validation, env-var overrides,
wire payload mode-defaults, system-message normalization, and the
session.options.update RPC (including async path + cleanup-on-failure).
339 tests / 1578 assertions / 0 failures.

Upstream: github/copilot-sdk#1428

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

Author: krukow

src/github/copilot_sdk/client.clj

@@ -42,7 +42,7 @@
 
    This is a pure helper extracted so we can unit-test the env contract
    without spawning a real process."
-  [{:keys [github-token telemetry copilot-home tcp-connection-token] :as _opts}]
+  [{:keys [github-token telemetry copilot-home tcp-connection-token mode] :as _opts}]
   {:defaults {"NODE_DEBUG" nil}
    :overrides
    (cond-> {}
@@ -55,6 +55,11 @@
      ;; tcpConnectionToken (upstream PR #1176) — required when server enforces a token
      tcp-connection-token
      (assoc "COPILOT_CONNECTION_TOKEN" tcp-connection-token)
+     ;; Client mode :empty disables the system keychain (upstream PR #1428).
+     ;; Applied in :overrides so the caller's `:env` cannot accidentally
+     ;; re-enable it under multitenancy hardening.
+     (= mode :empty)
+     (assoc "COPILOT_DISABLE_KEYTAR" "1")
      ;; OpenTelemetry (upstream PR #785)
      telemetry
      (as-> m
@@ -88,6 +93,9 @@
    - :tcp-connection-token - Connection token sent via COPILOT_CONNECTION_TOKEN (upstream PR #1176)
    - :remote? - When true, append `--remote` so the CLI exposes its session
                 over a GitHub-hosted remote endpoint (upstream PR #1192)
+   - :mode - Client mode `:empty` or `:copilot-cli` (default). When `:empty`,
+             `COPILOT_DISABLE_KEYTAR=1` is forced into the spawned env so the
+             child CLI cannot reach the host keychain (upstream PR #1428).
 
    Returns a ManagedProcess record."
   [{:keys [cli-path cwd env use-stdio?]

src/github/copilot_sdk/process.clj

@@ -186,23 +186,40 @@
 ;; Factory fn: (session) → session-fs-handler
 (s/def ::create-session-fs-handler fn?)
 
+;; Client mode (upstream PR #1428). `:copilot-cli` (the default) preserves
+;; the historical behavior; `:empty` enables multitenancy hardening:
+;; tenant-scoped storage is required, the system keychain is disabled, and
+;; a set of safe session defaults is spread under the caller's config.
+;;
+;; Note: the unqualified key in client-options is `:mode`, but the existing
+;; ::mode spec at line ~899 is already taken by message-options for
+;; #{:enqueue :immediate}. We use a uniquely-named ::client-mode spec and
+;; validate the unqualified `:mode` key via a predicate in ::client-options
+;; (mirrors the ::remote-session-mode pattern further down).
+(s/def ::client-mode #{:empty :copilot-cli})
+
 (def client-options-keys
   #{:cli-path :cli-args :cli-url :cwd :port
     :use-stdio? :log-level :auto-start? :auto-restart?
     :notification-queue-size :router-queue-size
     :tool-timeout-ms :env :github-token :use-logged-in-user?
     :is-child-process? :on-list-models :telemetry :on-get-trace-context
-    :session-fs :copilot-home :tcp-connection-token :remote?})
+    :session-fs :copilot-home :tcp-connection-token :remote?
+    :mode})
 
 (s/def ::client-options
-  (closed-keys
-   (s/keys :opt-un [::cli-path ::cli-args ::cli-url ::cwd ::port
-                    ::use-stdio? ::log-level ::auto-start? ::auto-restart?
-                    ::notification-queue-size ::router-queue-size
-                    ::tool-timeout-ms ::env ::github-token ::use-logged-in-user?
-                    ::is-child-process? ::on-list-models ::telemetry ::on-get-trace-context
-                    ::session-fs ::copilot-home ::tcp-connection-token ::remote?])
-   client-options-keys))
+  (s/and
+   (closed-keys
+    (s/keys :opt-un [::cli-path ::cli-args ::cli-url ::cwd ::port
+                     ::use-stdio? ::log-level ::auto-start? ::auto-restart?
+                     ::notification-queue-size ::router-queue-size
+                     ::tool-timeout-ms ::env ::github-token ::use-logged-in-user?
+                     ::is-child-process? ::on-list-models ::telemetry ::on-get-trace-context
+                     ::session-fs ::copilot-home ::tcp-connection-token ::remote?])
+    client-options-keys)
+   (fn [m]
+     (or (not (contains? m :mode))
+         (s/valid? ::client-mode (:mode m))))))
 
 ;; -----------------------------------------------------------------------------
 ;; Tool definitions
@@ -601,7 +618,7 @@
 
 ;; Multitenancy hardening flags (upstream PR #1474). All optional, plain
 ;; booleans/strings. Application-mode behavior is driven by Client Mode
-;; (upstream PR #1428), which has been deferred to a dedicated future round.
+;; (upstream PR #1428).
 (s/def ::skip-embedding-retrieval boolean?)
 (s/def ::organization-custom-instructions string?)
 (s/def ::enable-on-demand-instruction-discovery boolean?)
@@ -610,6 +627,15 @@
 (s/def ::enable-session-store boolean?)
 (s/def ::enable-skills boolean?)
 
+;; Client-mode session option flags (upstream PR #1428). Sent via
+;; session.options.update after session.create / session.resume. In empty
+;; mode these get safe defaults applied beneath the caller's config; in
+;; CLI mode they are only emitted when explicitly set.
+(s/def ::skip-custom-instructions boolean?)
+(s/def ::custom-agents-local-only boolean?)
+(s/def ::coauthor-enabled boolean?)
+(s/def ::manage-schedule-enabled boolean?)
+
 ;; Reasoning summary mode (upstream PR #813 - pre-existing parity gap).
 ;; Wire enum: "none" | "concise" | "detailed". Mirrors upstream's ReasoningSummary type.
 (s/def ::reasoning-summary #{"none" "concise" "detailed"})
@@ -648,6 +674,10 @@
     :enable-host-git-operations
     :enable-session-store
     :enable-skills
+    :skip-custom-instructions
+    :custom-agents-local-only
+    :coauthor-enabled
+    :manage-schedule-enabled
     :include-sub-agent-streaming-events?})
 
 (s/def ::session-config
@@ -682,6 +712,10 @@
                     ::enable-host-git-operations
                     ::enable-session-store
                     ::enable-skills
+                    ::skip-custom-instructions
+                    ::custom-agents-local-only
+                    ::coauthor-enabled
+                    ::manage-schedule-enabled
                     ::include-sub-agent-streaming-events?])
    session-config-keys))
 
@@ -710,6 +744,10 @@
     :enable-host-git-operations
     :enable-session-store
     :enable-skills
+    :skip-custom-instructions
+    :custom-agents-local-only
+    :coauthor-enabled
+    :manage-schedule-enabled
     :include-sub-agent-streaming-events?})
 
 (s/def ::resume-session-config
@@ -741,6 +779,10 @@
                     ::enable-host-git-operations
                     ::enable-session-store
                     ::enable-skills
+                    ::skip-custom-instructions
+                    ::custom-agents-local-only
+                    ::coauthor-enabled
+                    ::manage-schedule-enabled
                     ::include-sub-agent-streaming-events?])
    resume-session-config-keys))
 
@@ -774,6 +816,10 @@
                     ::enable-host-git-operations
                     ::enable-session-store
                     ::enable-skills
+                    ::skip-custom-instructions
+                    ::custom-agents-local-only
+                    ::coauthor-enabled
+                    ::manage-schedule-enabled
                     ::include-sub-agent-streaming-events?])
    resume-session-config-keys))