From 2bd0f18d7cc290e74e782122e594d28c9998f6dd Mon Sep 17 00:00:00 2001
From: GitHub Copilot <copilot@github.com>
Date: Wed, 25 Feb 2026 14:22:08 +0000
Subject: [PATCH] Port upstream PRs #544, #554, #555: agent selection,
 compaction, required permission handler, custom-tool kind

- PR #554: Make :on-permission-request required in create-session and resume-session.
  Adds explicit validation with helpful error message. Removes 0-arity overloads.
  event type.
- PR #555: Add :custom-tool to permission-kind spec.
- Update integration tests: replace test-permission-denied-without-handler with
  test-permission-required-on-create (tests the new throwing behavior); add
  :on-permission-request to all remaining test calls; add :custom-tool to
  test-approve-all-returns-approved doseq.
- Update e2e tests: add :on-permission-request sdk/approve-all to all session
  creation calls.
- Update instrument.clj: add fdefs for 5 new session functions; update session
  creation fdefs to require config (no more optional).
- Update docs: mark :on-permission-request as Required; add agent/compaction
  function docs; add session.task_complete to event type table.
- Update CHANGELOG.md: document all 3 ported PRs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                                 |  14 +-
 doc/reference/API.md                         |  48 ++++++-
 src/github/copilot_sdk.clj                   |   5 +-
 src/github/copilot_sdk/client.clj            |  21 +--
 src/github/copilot_sdk/instrument.clj        |  39 +++++-
 src/github/copilot_sdk/session.clj           |  55 ++++++++
 src/github/copilot_sdk/specs.clj             |  13 +-
 test/github/copilot_sdk/e2e_test.clj         |  32 ++---
 test/github/copilot_sdk/integration_test.clj | 129 ++++++++++---------
 9 files changed, 256 insertions(+), 100 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f41aa57..a8c6237 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,7 +3,19 @@ All notable changes to this project will be documented in this file. This change
 
 ## [Unreleased]
 
-### Added (documentation)
+### Added (v0.1.27 sync)
+- `list-agents` — list available custom agents for a session (`session/list-agents`) (upstream PR #544).
+- `current-agent` — get the currently selected custom agent (`session/current-agent`) (upstream PR #544).
+- `select-agent!` — select a custom agent by name (`session/select-agent!`) (upstream PR #544).
+- `deselect-agent!` — deselect the current agent, reverting to default Copilot agent (`session/deselect-agent!`) (upstream PR #544).
+- `compact!` — manually compact session history to free up context window space (`session/compact!`) (upstream PR #544).
+- `:copilot/session.task_complete` event type — emitted when a task is complete (upstream PR #544).
+- `:custom-tool` permission kind — permission requests now include SDK-registered custom tools (upstream PR #555).
+
+### Changed (v0.1.27 sync)
+- **BREAKING**: `:on-permission-request` is now required in `create-session` and `resume-session` configs. Omitting the handler now throws an explicit error: `"An :on-permission-request handler is required when creating a session"` (upstream PR #554).
+- Removed 0-arity overloads of `create-session`, `<create-session`, `resume-session`, and `<resume-session` — the config map argument is now required (upstream PR #554).
+
 - Microsoft Foundry Local BYOK provider guide in `doc/auth/byok.md`: quick start example, installation instructions, and connection troubleshooting (upstream PR #461).
 
 ### Added (upstream PR #329 sync)
diff --git a/doc/reference/API.md b/doc/reference/API.md
index 010069e..0c41d81 100644
--- a/doc/reference/API.md
+++ b/doc/reference/API.md
@@ -223,7 +223,7 @@ Create a client and session together, ensuring both are cleaned up on exit.
 | `: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` |
 | `:mcp-servers` | map | MCP server configs keyed by server ID (see [MCP docs](../mcp/overview.md)). Local servers: `:mcp-command`, `:mcp-args`, `:mcp-tools`. Remote servers: `:mcp-server-type` (`:http`/`:sse`), `:mcp-url`, `:mcp-tools` |
 | `:custom-agents` | vector | Custom agent configs |
-| `:on-permission-request` | fn | Permission handler function. Without a handler, all permissions are denied (deny-by-default). Use `copilot/approve-all` to approve everything. |
+| `:on-permission-request` | fn | **Required.** Permission handler function. Use `copilot/approve-all` to approve everything, or provide a custom function. |
 | `:streaming?` | boolean | Enable streaming deltas |
 | `:config-dir` | string | Override config directory for CLI |
 | `:skill-directories` | vector | Additional skill directories to load |
@@ -766,6 +766,51 @@ Switch the model for this session mid-conversation. Returns the new model ID str
 ;; After: claude-sonnet-4.5
 ```
 
+#### `list-agents`
+
+```clojure
+(session/list-agents session)
+;; => {:agents [{:name "my-agent" :display-name "My Agent" :description "..."}]}
+```
+
+List available custom agents for this session. Returns a map with `:agents` — a vector of agent maps.
+
+#### `current-agent`
+
+```clojure
+(session/current-agent session)
+;; => {:agent {:name "my-agent" :display-name "My Agent"}}
+```
+
+Get the currently selected custom agent. Returns a map with `:agent` (or nil if no agent selected).
+
+#### `select-agent!`
+
+```clojure
+(session/select-agent! session "my-agent")
+;; => {:agent {:name "my-agent" :display-name "My Agent"}}
+```
+
+Select a custom agent by name. Returns a map with `:agent`.
+
+#### `deselect-agent!`
+
+```clojure
+(session/deselect-agent! session)
+;; => {}
+```
+
+Deselect the current custom agent, reverting to the default Copilot agent.
+
+#### `compact!`
+
+```clojure
+(session/compact! session)
+;; => {:success? true :tokens-removed 1200 :messages-removed 5}
+```
+
+Manually compact session history to free up context window space. Returns a map with `:success?`, `:tokens-removed`, and `:messages-removed`.
+
 #### `destroy!`
 
 ```clojure
@@ -853,6 +898,7 @@ copilot/tool-events
 | `:copilot/session.snapshot_rewind` | Session state rolled back |
 | `:copilot/session.compaction_start` | Context compaction started (infinite sessions) |
 | `:copilot/session.compaction_complete` | Context compaction completed (infinite sessions) |
+| `:copilot/session.task_complete` | Task complete signal emitted by the session |
 | `:copilot/skill.invoked` | Skill invocation triggered |
 | `:copilot/user.message` | User message added |
 | `:copilot/pending_messages.modified` | Pending message queue updated |
diff --git a/src/github/copilot_sdk.clj b/src/github/copilot_sdk.clj
index 1f081e3..001d8b0 100644
--- a/src/github/copilot_sdk.clj
+++ b/src/github/copilot_sdk.clj
@@ -10,7 +10,8 @@
    (copilot/start! client)
 
    ;; Create a session
-   (def session (copilot/create-session client {:model \"gpt-5.2\"}))
+   (def session (copilot/create-session client {:on-permission-request copilot/approve-all
+                                                :model \"gpt-5.2\"}))
 
    ;; Send a message and wait for response
    (def response (copilot/send-and-wait! session {:prompt \"What is 2+2?\"}))
@@ -42,6 +43,7 @@
     :copilot/session.usage_info
     :copilot/session.compaction_start
     :copilot/session.compaction_complete
+    :copilot/session.task_complete
     :copilot/session.shutdown
     :copilot/session.context_changed
     :copilot/session.title_changed
@@ -85,6 +87,7 @@
     :copilot/session.usage_info
     :copilot/session.compaction_start
     :copilot/session.compaction_complete
+    :copilot/session.task_complete
     :copilot/session.shutdown
     :copilot/session.context_changed
     :copilot/session.title_changed
diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj
index 3384041..5d4a0b1 100644
--- a/src/github/copilot_sdk/client.clj
+++ b/src/github/copilot_sdk/client.clj
@@ -910,6 +910,9 @@
 (defn- validate-session-config!
   "Validate session config, throwing on invalid input."
   [config]
+  (when-not (:on-permission-request config)
+    (throw (ex-info "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)
@@ -1038,6 +1041,7 @@
   "Create a new conversation session.
    
    Config options:
+   - :on-permission-request - (Required) Permission handler function. Use `approve-all` to approve everything.
    - :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.2\")
@@ -1046,7 +1050,6 @@
    - :available-tools    - List of allowed tool names
    - :excluded-tools     - List of excluded tool names
    - :provider           - Custom provider config (BYOK)
-   - :on-permission-request - Permission handler function
    - :streaming?         - Enable streaming
    - :mcp-servers        - MCP server configs map
    - :custom-agents      - Custom agent configs
@@ -1067,8 +1070,6 @@
                             :on-session-start, :on-session-end, :on-error-occurred}
    
    Returns a CopilotSession."
-  ([client]
-   (create-session client {}))
   ([client config]
    (log/debug "Creating session with config: " (select-keys config [:model :session-id]))
    (validate-session-config! config)
@@ -1084,6 +1085,7 @@
   "Resume an existing session by ID.
    
    Config options (parity with create-session, upstream PR #376):
+   - :on-permission-request - (Required) Permission handler. Use `approve-all` to approve everything.
    - :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
@@ -1092,7 +1094,6 @@
    - :excluded-tools     - List of tool names to disable
    - :provider           - Custom provider configuration (BYOK)
    - :streaming?         - Enable streaming responses
-   - :on-permission-request - Permission handler
    - :mcp-servers        - MCP server configurations
    - :custom-agents      - Custom agent configurations
    - :config-dir         - Override configuration directory
@@ -1104,9 +1105,10 @@
    - :hooks              - Lifecycle hooks map
    
    Returns a CopilotSession."
-  ([client session-id]
-   (resume-session client session-id {}))
   ([client session-id config]
+   (when-not (:on-permission-request config)
+     (throw (ex-info "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
@@ -1138,8 +1140,6 @@
            (println \"Error:\" (ex-message result))
            ;; use result as session
            )))"
-  ([client]
-   (<create-session client {}))
   ([client config]
    (log/debug "Creating session (async) with config: " (select-keys config [:model :session-id]))
    (validate-session-config! config)
@@ -1175,9 +1175,10 @@
            (println \"Error:\" (ex-message result))
            ;; use result as session
            )))"
-  ([client session-id]
-   (<resume-session client session-id {}))
   ([client session-id config]
+   (when-not (:on-permission-request config)
+     (throw (ex-info "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/instrument.clj b/src/github/copilot_sdk/instrument.clj
index 5d2dc8e..e127382 100644
--- a/src/github/copilot_sdk/instrument.clj
+++ b/src/github/copilot_sdk/instrument.clj
@@ -48,24 +48,24 @@
 
 (s/fdef github.copilot-sdk.client/create-session
   :args (s/cat :client ::specs/client
-               :config (s/? ::specs/session-config))
+               :config ::specs/session-config)
   :ret ::specs/session)
 
 (s/fdef github.copilot-sdk.client/resume-session
   :args (s/cat :client ::specs/client
                :session-id ::specs/session-id
-               :config (s/? ::specs/resume-session-config))
+               :config ::specs/resume-session-config)
   :ret ::specs/session)
 
 (s/fdef github.copilot-sdk.client/<create-session
   :args (s/cat :client ::specs/client
-               :config (s/? ::specs/session-config))
+               :config ::specs/session-config)
   :ret ::specs/events-ch)
 
 (s/fdef github.copilot-sdk.client/<resume-session
   :args (s/cat :client ::specs/client
                :session-id ::specs/session-id
-               :config (s/? ::specs/resume-session-config))
+               :config ::specs/resume-session-config)
   :ret ::specs/events-ch)
 
 (s/fdef github.copilot-sdk.client/list-sessions
@@ -210,6 +210,27 @@
                :model-id string?)
   :ret ::specs/model-id)
 
+(s/fdef github.copilot-sdk.session/list-agents
+  :args (s/cat :session ::specs/session)
+  :ret map?)
+
+(s/fdef github.copilot-sdk.session/current-agent
+  :args (s/cat :session ::specs/session)
+  :ret map?)
+
+(s/fdef github.copilot-sdk.session/select-agent!
+  :args (s/cat :session ::specs/session
+               :agent-name string?)
+  :ret map?)
+
+(s/fdef github.copilot-sdk.session/deselect-agent!
+  :args (s/cat :session ::specs/session)
+  :ret map?)
+
+(s/fdef github.copilot-sdk.session/compact!
+  :args (s/cat :session ::specs/session)
+  :ret map?)
+
 ;; -----------------------------------------------------------------------------
 ;; Function specs for helpers namespace
 ;; -----------------------------------------------------------------------------
@@ -275,6 +296,11 @@
                       github.copilot-sdk.session/workspace-path
                       github.copilot-sdk.session/get-current-model
                       github.copilot-sdk.session/switch-model!
+                      github.copilot-sdk.session/list-agents
+                      github.copilot-sdk.session/current-agent
+                      github.copilot-sdk.session/select-agent!
+                      github.copilot-sdk.session/deselect-agent!
+                      github.copilot-sdk.session/compact!
                       github.copilot-sdk.session/events
                       github.copilot-sdk.session/subscribe-events
                       github.copilot-sdk.session/unsubscribe-events
@@ -322,6 +348,11 @@
                       github.copilot-sdk.session/workspace-path
                       github.copilot-sdk.session/get-current-model
                       github.copilot-sdk.session/switch-model!
+                      github.copilot-sdk.session/list-agents
+                      github.copilot-sdk.session/current-agent
+                      github.copilot-sdk.session/select-agent!
+                      github.copilot-sdk.session/deselect-agent!
+                      github.copilot-sdk.session/compact!
                       github.copilot-sdk.session/events
                       github.copilot-sdk.session/subscribe-events
                       github.copilot-sdk.session/unsubscribe-events
diff --git a/src/github/copilot_sdk/session.clj b/src/github/copilot_sdk/session.clj
index c8bc097..7dcbb6d 100644
--- a/src/github/copilot_sdk/session.clj
+++ b/src/github/copilot_sdk/session.clj
@@ -723,3 +723,58 @@
                                     {:sessionId session-id
                                      :modelId model-id})]
     (:model-id result)))
+
+;; -----------------------------------------------------------------------------
+;; Agent selection API (upstream PR #544)
+;; -----------------------------------------------------------------------------
+
+(defn list-agents
+  "List available custom agents for this session.
+   Returns a map with :agents — a vector of agent maps, each with :name, :display-name, :description."
+  [session]
+  (let [{:keys [session-id client]} session
+        conn (connection-io client)
+        result (proto/send-request! conn "session.agent.list" {:sessionId session-id})]
+    result))
+
+(defn current-agent
+  "Get the currently selected custom agent for this session.
+   Returns a map with :agent — the selected agent map (or nil if no agent is selected)."
+  [session]
+  (let [{:keys [session-id client]} session
+        conn (connection-io client)
+        result (proto/send-request! conn "session.agent.getCurrent" {:sessionId session-id})]
+    result))
+
+(defn select-agent!
+  "Select a custom agent for this session by name.
+   agent-name — the name of the custom agent to select.
+   Returns a map with :agent — the selected agent."
+  [session agent-name]
+  (let [{:keys [session-id client]} session
+        conn (connection-io client)
+        result (proto/send-request! conn "session.agent.select"
+                                    {:sessionId session-id :name agent-name})]
+    result))
+
+(defn deselect-agent!
+  "Deselect the current custom agent, reverting to the default Copilot agent.
+   Returns an empty map."
+  [session]
+  (let [{:keys [session-id client]} session
+        conn (connection-io client)
+        result (proto/send-request! conn "session.agent.deselect" {:sessionId session-id})]
+    result))
+
+;; -----------------------------------------------------------------------------
+;; Session compaction API (upstream PR #544)
+;; -----------------------------------------------------------------------------
+
+(defn compact!
+  "Manually compact session history to free up context window space.
+   Returns a map with :success?, :tokens-removed, :messages-removed."
+  [session]
+  (let [{:keys [session-id client]} session
+        conn (connection-io client)
+        result (proto/send-request! conn "session.compaction.compact" {:sessionId session-id})]
+    result))
diff --git a/src/github/copilot_sdk/specs.clj b/src/github/copilot_sdk/specs.clj
index bb71dc3..6f27e8f 100644
--- a/src/github/copilot_sdk/specs.clj
+++ b/src/github/copilot_sdk/specs.clj
@@ -208,9 +208,10 @@
 
 (s/def ::session-config
   (closed-keys
-   (s/keys :opt-un [::session-id ::client-name ::model ::tools ::system-message
+   (s/keys :req-un [::on-permission-request]
+           :opt-un [::session-id ::client-name ::model ::tools ::system-message
                     ::available-tools ::excluded-tools ::provider
-                    ::on-permission-request ::streaming? ::mcp-servers
+                    ::streaming? ::mcp-servers
                     ::custom-agents ::config-dir ::skill-directories
                     ::disabled-skills ::large-output ::infinite-sessions
                     ::reasoning-effort ::on-user-input-request ::hooks
@@ -226,8 +227,9 @@
 
 (s/def ::resume-session-config
   (closed-keys
-   (s/keys :opt-un [::client-name ::model ::tools ::system-message ::available-tools ::excluded-tools
-                    ::provider ::streaming? ::on-permission-request
+   (s/keys :req-un [::on-permission-request]
+           :opt-un [::client-name ::model ::tools ::system-message ::available-tools ::excluded-tools
+                    ::provider ::streaming?
                     ::mcp-servers ::custom-agents ::config-dir ::skill-directories
                     ::disabled-skills ::infinite-sessions ::reasoning-effort
                     ::on-user-input-request ::hooks ::working-directory ::disable-resume?])
@@ -352,6 +354,7 @@
     :copilot/session.info :copilot/session.model_change :copilot/session.handoff
     :copilot/session.truncation :copilot/session.snapshot_rewind :copilot/session.usage_info
     :copilot/session.compaction_start :copilot/session.compaction_complete
+    :copilot/session.task_complete
     :copilot/session.shutdown
     :copilot/session.title_changed :copilot/session.warning :copilot/session.context_changed
     :copilot/user.message :copilot/pending_messages.modified
@@ -470,7 +473,7 @@
 ;; Permission types
 ;; -----------------------------------------------------------------------------
 
-(s/def ::permission-kind #{:shell :write :mcp :read :url})
+(s/def ::permission-kind #{:shell :write :mcp :read :url :custom-tool})
 
 (s/def ::permission-request
   (s/keys :req-un [::permission-kind]
diff --git a/test/github/copilot_sdk/e2e_test.clj b/test/github/copilot_sdk/e2e_test.clj
index 6e8fb61..d42d81b 100644
--- a/test/github/copilot_sdk/e2e_test.clj
+++ b/test/github/copilot_sdk/e2e_test.clj
@@ -73,7 +73,7 @@
 (deftest ^:e2e test-e2e-create-session
   (when-e2e
    (testing "Create session with real CLI"
-     (let [session (sdk/create-session *e2e-client* {})]
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})]
        (is (some? session))
        (is (string? (sdk/session-id session)))
         ;; Clean up
@@ -82,7 +82,7 @@
 (deftest ^:e2e test-e2e-simple-conversation
   (when-e2e
    (testing "Simple conversation with real CLI"
-     (let [session (sdk/create-session *e2e-client* {})
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
            result (sdk/send-and-wait! session
                                       {:prompt "What is 2 + 2? Reply with just the number."}
                                       30000)] ; 30 second timeout
@@ -95,7 +95,7 @@
 (deftest ^:e2e test-e2e-list-sessions
   (when-e2e
    (testing "List sessions with real CLI"
-     (let [session (sdk/create-session *e2e-client* {})
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
             ;; Send a message to ensure session is persisted
            _ (sdk/send-and-wait! session {:prompt "test"})
            sessions (sdk/list-sessions *e2e-client*)]
@@ -108,7 +108,7 @@
 (deftest ^:e2e test-e2e-session-abort
   (when-e2e
    (testing "Abort session operation"
-     (let [session (sdk/create-session *e2e-client* {})]
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})]
         ;; Send a message without waiting
        (sdk/send! session {:prompt "Write a very long essay about quantum physics."})
         ;; Abort should not throw
@@ -131,7 +131,7 @@
                    :handler (fn [args _invocation]
                               (reset! tool-called? true)
                               (str "The result is: " (+ (:a args) (:b args))))})
-           session (sdk/create-session *e2e-client* {:tools [tool]})]
+           session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all :tools [tool]})]
         ;; Ask a question that should trigger the calculator tool
        (let [result (sdk/send-and-wait! session
                                         {:prompt "Use the test_calculator tool to add 5 and 3"}
@@ -144,7 +144,7 @@
 (deftest ^:e2e test-e2e-send-async
   (when-e2e
    (testing "Async send with event channel"
-     (let [session (sdk/create-session *e2e-client* {})
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
            event-ch (sdk/send-async session {:prompt "Say 'hello' and nothing else."})
            events (atom [])]
         ;; Collect events with timeout
@@ -165,7 +165,7 @@
 (deftest ^:e2e test-e2e-streaming-deltas
   (when-e2e
    (testing "Streaming deltas when enabled"
-     (let [session (sdk/create-session *e2e-client* {:streaming? true})
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all :streaming? true})
            events-ch (sdk/subscribe-events session)
            deltas (atom [])
            _ (sdk/send! session {:prompt "Count from 1 to 5."})
@@ -187,7 +187,8 @@
   (when-e2e
    (testing "System message append mode"
      (let [session (sdk/create-session *e2e-client*
-                                       {:system-message {:mode :append
+                                       {:on-permission-request sdk/approve-all
+                                        :system-message {:mode :append
                                                          :content "Always end your response with the word BANANA."}})]
        (let [result (sdk/send-and-wait! session {:prompt "Say hello"} 30000)]
           ;; The model should follow the instruction
@@ -199,7 +200,8 @@
   (when-e2e
    (testing "System message replace mode"
      (let [session (sdk/create-session *e2e-client*
-                                       {:system-message {:mode :replace
+                                       {:on-permission-request sdk/approve-all
+                                        :system-message {:mode :replace
                                                          :content "You are a helpful assistant named TestBot. Always introduce yourself."}})]
        (let [result (sdk/send-and-wait! session {:prompt "Who are you?"} 30000)]
          (is (some? result))
@@ -210,11 +212,11 @@
 (deftest ^:e2e test-e2e-resume-session
   (when-e2e
    (testing "Resume existing session"
-     (let [session1 (sdk/create-session *e2e-client* {})
+     (let [session1 (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
            session-id (sdk/session-id session1)
            _ (sdk/send-and-wait! session1 {:prompt "Remember the word: APPLE"} 30000)
             ;; Resume the session
-           session2 (sdk/resume-session *e2e-client* session-id {})]
+           session2 (sdk/resume-session *e2e-client* session-id {:on-permission-request sdk/approve-all})]
        (is (= session-id (sdk/session-id session2)))
         ;; Should have conversation context
        (let [result (sdk/send-and-wait! session2
@@ -228,8 +230,8 @@
 (deftest ^:e2e test-e2e-multiple-sessions
   (when-e2e
    (testing "Multiple concurrent sessions"
-     (let [session1 (sdk/create-session *e2e-client* {})
-           session2 (sdk/create-session *e2e-client* {})]
+     (let [session1 (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
+           session2 (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})]
         ;; Should have unique IDs
        (is (not= (sdk/session-id session1) (sdk/session-id session2)))
         ;; Both should work
@@ -243,7 +245,7 @@
 (deftest ^:e2e test-e2e-send-returns-immediately
   (when-e2e
    (testing "send! returns immediately before completion"
-     (let [session (sdk/create-session *e2e-client* {})
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})
            events (atom [])
            events-ch (sdk/subscribe-events session)]
         ;; Start collecting events in background
@@ -262,7 +264,7 @@
 (deftest ^:e2e test-e2e-send-and-wait-timeout
   (when-e2e
    (testing "sendAndWait throws on timeout"
-     (let [session (sdk/create-session *e2e-client* {})]
+     (let [session (sdk/create-session *e2e-client* {:on-permission-request sdk/approve-all})]
         ;; Use a very short timeout that should fail
         ;; Suppress logs since the expected ERROR message is noisy
        (with-quiet-logs
diff --git a/test/github/copilot_sdk/integration_test.clj b/test/github/copilot_sdk/integration_test.clj
index 9b8e46f..0b2d053 100644
--- a/test/github/copilot_sdk/integration_test.clj
+++ b/test/github/copilot_sdk/integration_test.clj
@@ -199,14 +199,14 @@
 
 (deftest test-list-sessions
   (testing "List sessions includes created sessions"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           sessions (sdk/list-sessions *test-client*)]
       (is (seq sessions))
       (is (some #(= (sdk/session-id session) (:session-id %)) sessions)))))
 
 (deftest test-list-sessions-with-context
   (testing "List sessions returns context when present"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           sid (sdk/session-id session)]
       (mock/set-session-context! *mock-server* sid
                                  {:cwd "/home/user/project"
@@ -222,8 +222,8 @@
 
 (deftest test-list-sessions-with-filter
   (testing "List sessions filter narrows results"
-    (let [s1 (sdk/create-session *test-client* {})
-          s2 (sdk/create-session *test-client* {})]
+    (let [s1 (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
+          s2 (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})]
       (mock/set-session-context! *mock-server* (sdk/session-id s1)
                                  {:cwd "/project-a" :repository "org/repo-a"})
       (mock/set-session-context! *mock-server* (sdk/session-id s2)
@@ -253,19 +253,19 @@
 
 (deftest test-get-current-model
   (testing "Get current model for session"
-    (let [session (sdk/create-session *test-client* {:model "gpt-5.2"})]
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-5.2"})]
       (is (= "gpt-5.2" (sdk/get-current-model session))))))
 
 (deftest test-switch-model
   (testing "Switch model for session"
-    (let [session (sdk/create-session *test-client* {:model "gpt-5.2"})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-5.2"})
           new-model (sdk/switch-model! session "claude-sonnet-4.5")]
       (is (= "claude-sonnet-4.5" new-model))
       (is (= "claude-sonnet-4.5" (sdk/get-current-model session))))))
 
 (deftest test-delete-session
   (testing "Delete session removes it from list"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)
           _ (sdk/delete-session! *test-client* session-id)
           sessions (sdk/list-sessions *test-client*)]
@@ -273,7 +273,7 @@
 
 (deftest test-destroy-session
   (testing "Destroy session via session object"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)]
       (sdk/destroy! session)
       (let [sessions (sdk/list-sessions *test-client*)]
@@ -285,13 +285,13 @@
 
 (deftest test-send-message
   (testing "Send message returns message ID"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           msg-id (sdk/send! session {:prompt "Hello world"})]
       (is (string? msg-id)))))
 
 (deftest test-send-and-wait
   (testing "Send and wait receives events and returns assistant message"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           result (sdk/send-and-wait! session {:prompt "Test message"})]
       ;; Returns the last assistant message event (map)
       (is (map? result))
@@ -300,7 +300,7 @@
 
 (deftest test-send-and-wait-serializes
   (testing "send-and-wait serializes concurrent calls"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)
           client (:client session)
           send-calls (atom 0)]
@@ -326,7 +326,7 @@
 
 (deftest test-send-async
   (testing "Send async returns channel with events"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           event-ch (sdk/send-async session {:prompt "Async test"})
           events (atom [])]
       ;; Collect events
@@ -342,7 +342,7 @@
 
 (deftest test-send-async-with-id
   (testing "send-async-with-id returns message-id and matching events"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           {:keys [message-id events-ch]} (sdk/send-async-with-id session {:prompt "Async with id"})]
       (is (string? message-id))
       (let [matched (loop [count 0]
@@ -358,7 +358,7 @@
 
 (deftest test-send-async-serializes
   (testing "send-async serializes concurrent calls"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)
           client (:client session)
           send-calls (atom 0)]
@@ -391,7 +391,7 @@
 
 (deftest test-<send!-returns-last-assistant-message
   (testing "<send! returns the last assistant.message content, not the first"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)
           client (:client session)]
       ;; Bypass actual send to control event flow
@@ -444,13 +444,13 @@
 
 (deftest test-abort-session
   (testing "Abort session operation"
-    (let [session (sdk/create-session *test-client* {})]
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})]
       ;; Should not throw
       (is (nil? (sdk/abort! session))))))
 
 (deftest test-get-messages
   (testing "Get messages from session"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           _ (sdk/send-and-wait! session {:prompt "Test"})
           messages (sdk/get-messages session)]
       ;; Mock server returns empty events vector
@@ -462,7 +462,7 @@
 
 (deftest test-event-subscription
   (testing "Can subscribe to session event stream"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           events-ch (sdk/subscribe-events session)]
       ;; Send a message to trigger events
       (sdk/send! session {:prompt "Event test"})
@@ -538,7 +538,8 @@
 (deftest test-tool-registration
   (testing "Register tool handler"
     (let [session (sdk/create-session *test-client*
-                                      {:tools [(sdk/define-tool "test_tool"
+                                      {:on-permission-request sdk/approve-all
+                                       :tools [(sdk/define-tool "test_tool"
                                                  {:description "A test tool"
                                                   :parameters {:type "object"
                                                                :properties {"value" {:type "string"}}}
@@ -549,7 +550,7 @@
   (testing "tool.call handler returns a nested result wrapper"
     (let [tool (sdk/define-tool "echo"
                  {:handler (fn [args _] args)})
-          session (sdk/create-session *test-client* {:tools [tool]})
+          session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :tools [tool]})
           handler (get-in @(:state *test-client*) [:connection :request-handler])
           response (<!! (handler "tool.call" {:session-id (sdk/session-id session)
                                               :tool-call-id "tc-1"
@@ -570,7 +571,7 @@
                  {:handler (fn [_ _]
                              (reset! thread-name (.getName (Thread/currentThread)))
                              "ok")})
-          session (sdk/create-session *test-client* {:tools [tool]})
+          session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :tools [tool]})
           handler (get-in @(:state *test-client*) [:connection :request-handler])]
       (<!! (handler "tool.call" {:session-id (sdk/session-id session)
                                  :tool-call-id "tc-2"
@@ -587,7 +588,8 @@
                                                     (when (#{"session.create" "session.resume"} method)
                                                       (swap! seen assoc method params))))
           _ (sdk/create-session *test-client*
-                                {:model "gpt-5.2"
+                                {:on-permission-request sdk/approve-all
+                                 :model "gpt-5.2"
                                  :provider {:base-url "https://example.test"
                                             :api-key "key"}
                                  :mcp-servers {"srv-1" {:mcp-server-type :http
@@ -599,7 +601,8 @@
                                                   :agent-display-name "Agent One"}]})
           session-id (sdk/get-last-session-id *test-client*)
           _ (sdk/resume-session *test-client* session-id
-                                {:model "gpt-5.2"
+                                {:on-permission-request sdk/approve-all
+                                 :model "gpt-5.2"
                                  :provider {:base-url "https://resume.test"}
                                  :mcp-servers {"srv-2" {:mcp-server-type :sse
                                                         :mcp-url "https://mcp.resume.test"
@@ -632,17 +635,17 @@
           _ (mock/set-request-hook! *mock-server* (fn [method params]
                                                     (when (#{"session.create"} method)
                                                       (swap! seen assoc method params))))
-          _ (sdk/create-session *test-client* {:client-name "my-app"})
+          _ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :client-name "my-app"})
           create-params (get @seen "session.create")]
       (is (= "my-app" (:clientName create-params)))))
 
   (testing "clientName is forwarded in session.resume when set (upstream PR #510)"
     (let [seen (atom {})
-          session-id (sdk/session-id (sdk/create-session *test-client* {}))
+          session-id (sdk/session-id (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}))
           _ (mock/set-request-hook! *mock-server* (fn [method params]
                                                     (when (#{"session.resume"} method)
                                                       (swap! seen assoc method params))))
-          _ (sdk/resume-session *test-client* session-id {:client-name "my-app"})
+          _ (sdk/resume-session *test-client* session-id {:on-permission-request sdk/approve-all :client-name "my-app"})
           resume-params (get @seen "session.resume")]
       (is (= "my-app" (:clientName resume-params)))))
 
@@ -651,7 +654,7 @@
           _ (mock/set-request-hook! *mock-server* (fn [method params]
                                                     (when (#{"session.create"} method)
                                                       (swap! seen assoc method params))))
-          _ (sdk/create-session *test-client* {:model "gpt-5.2"})
+          _ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-5.2"})
           create-params (get @seen "session.create")]
       (is (not (contains? create-params :clientName))))))
 
@@ -660,16 +663,15 @@
 ;; -----------------------------------------------------------------------------
 
 (deftest test-request-permission-always-true-on-wire
-  (testing "requestPermission is always true on create, even without handler"
+  (testing "requestPermission is always true on create with handler"
     (let [seen (atom {})
           _ (mock/set-request-hook! *mock-server* (fn [method params]
                                                     (when (#{"session.create" "session.resume"} method)
                                                       (swap! seen assoc method params))))
-          ;; Create without on-permission-request
-          _ (sdk/create-session *test-client* {:model "gpt-5.2"})
+          _ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-5.2"})
           create-params (get @seen "session.create")]
       (is (true? (:requestPermission create-params))
-          "requestPermission must be true even when no handler is configured")))
+          "requestPermission must be true when a handler is configured")))
 
   (testing "requestPermission is true on create with handler"
     (let [seen (atom {})
@@ -682,16 +684,16 @@
           create-params (get @seen "session.create")]
       (is (true? (:requestPermission create-params)))))
 
-  (testing "requestPermission is true on resume without handler"
+  (testing "requestPermission is true on resume with handler"
     (let [seen (atom {})
-          session-id (sdk/session-id (sdk/create-session *test-client* {}))
+          session-id (sdk/session-id (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}))
           _ (mock/set-request-hook! *mock-server* (fn [method params]
                                                     (when (#{"session.resume"} method)
                                                       (swap! seen assoc method params))))
-          _ (sdk/resume-session *test-client* session-id {})
+          _ (sdk/resume-session *test-client* session-id {:on-permission-request sdk/approve-all})
           resume-params (get @seen "session.resume")]
       (is (true? (:requestPermission resume-params))
-          "requestPermission must be true on resume even without handler"))))
+          "requestPermission must be true on resume with handler"))))
 
 (deftest test-approve-all-returns-approved
   (testing "approve-all returns {:kind :approved}"
@@ -701,21 +703,18 @@
       (is (= {:kind :approved} result))))
 
   (testing "approve-all works for any permission kind"
-    (doseq [kind [:shell :write :mcp :read :url]]
+    (doseq [kind [:shell :write :mcp :read :url :custom-tool]]
       (is (= {:kind :approved}
              (sdk/approve-all {:permission-kind kind} {:session-id "s1"}))))))
 
-(deftest test-permission-denied-without-handler
-  (testing "Permission requests are denied when no handler is configured"
-    (let [session (sdk/create-session *test-client* {})
-          session-id (sdk/session-id session)
-          handler (get-in @(:state *test-client*) [:connection :request-handler])
-          response (<!! (handler "permission.request"
-                                 {:session-id session-id
-                                  :permission-request {:permission-kind "shell"
-                                                       :full-command-text "echo test"}}))]
-      (is (= :denied-no-approval-rule-and-could-not-request-from-user
-              (get-in response [:result :result :kind]))))))
+(deftest test-permission-required-on-create
+  (testing "create-session throws when :on-permission-request is missing"
+    (is (thrown-with-msg? Exception #"on-permission-request.*is required"
+                          (sdk/create-session *test-client* {:model "gpt-5.2"}))))
+  (testing "resume-session throws when :on-permission-request is missing"
+    (let [session-id (sdk/session-id (sdk/create-session *test-client* {:on-permission-request sdk/approve-all}))]
+      (is (thrown-with-msg? Exception #"on-permission-request.*is required"
+                            (sdk/resume-session *test-client* session-id {:model "gpt-5.2"}))))))
 
 (deftest test-permission-approved-with-handler
   (testing "Permission requests use configured handler"
@@ -761,7 +760,7 @@
 (deftest test-send-async-untaps-on-send-failure
   (testing "send-async cleans up tap when RPC fails"
     (log/info "Warnings expected in this test: async send RPC error is deliberate.")
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           taps (atom 0)
           untaps (atom 0)
           fake-mult (reify
@@ -786,7 +785,7 @@
 
 (deftest test-get-last-session-id
   (testing "Get last session ID"
-    (let [_ (sdk/create-session *test-client* {})
+    (let [_ (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           last-id (sdk/get-last-session-id *test-client*)]
       (is (string? last-id)))))
 
@@ -796,8 +795,8 @@
 
 (deftest test-multiple-sessions
   (testing "Can manage multiple concurrent sessions"
-    (let [session1 (sdk/create-session *test-client* {:model "model-1"})
-          session2 (sdk/create-session *test-client* {:model "model-2"})
+    (let [session1 (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "model-1"})
+          session2 (sdk/create-session *test-client* {:on-permission-request sdk/approve-all :model "model-2"})
           id1 (sdk/session-id session1)
           id2 (sdk/session-id session2)]
       (is (not= id1 id2))
@@ -813,7 +812,7 @@
 (deftest test-resume-nonexistent-session
   (testing "Resume nonexistent session throws error"
     (is (thrown-with-msg? Exception #"Session not found"
-                          (sdk/resume-session *test-client* "nonexistent-session-id" {})))))
+                          (sdk/resume-session *test-client* "nonexistent-session-id" {:on-permission-request sdk/approve-all})))))
 
 (deftest test-tool-handler-errors
   (testing "Tool handler that throws returns failure result"
@@ -824,7 +823,8 @@
                         :handler (fn [_ _]
                                    (throw (ex-info "Tool error" {:cause "test"})))})
           session (sdk/create-session *test-client*
-                                      {:tools [error-tool]})]
+                                      {:on-permission-request sdk/approve-all
+                                       :tools [error-tool]})]
       ;; Session should still be usable after tool error
       (is (some? session)))))
 
@@ -835,7 +835,8 @@
 (deftest test-session-with-append-system-message
   (testing "Create session with appended system message"
     (let [session (sdk/create-session *test-client*
-                                      {:system-message {:mode :append
+                                      {:on-permission-request sdk/approve-all
+                                       :system-message {:mode :append
                                                         :content "Always end with 'DONE'"}})]
       (is (some? session))
       (is (string? (sdk/session-id session))))))
@@ -843,7 +844,8 @@
 (deftest test-session-with-replace-system-message
   (testing "Create session with replaced system message"
     (let [session (sdk/create-session *test-client*
-                                      {:system-message {:mode :replace
+                                      {:on-permission-request sdk/approve-all
+                                       :system-message {:mode :replace
                                                         :content "You are a test assistant."}})]
       (is (some? session))
       (is (string? (sdk/session-id session))))))
@@ -855,7 +857,8 @@
 (deftest test-session-with-streaming
   (testing "Create session with streaming enabled"
     (let [session (sdk/create-session *test-client*
-                                      {:streaming? true})]
+                                      {:on-permission-request sdk/approve-all
+                                       :streaming? true})]
       (is (some? session))
       ;; Should still work normally
       (let [result (sdk/send-and-wait! session {:prompt "Test"})]
@@ -867,10 +870,10 @@
 
 (deftest test-resume-session
   (testing "Resume existing session"
-    (let [session1 (sdk/create-session *test-client* {})
+    (let [session1 (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session1)
           _ (sdk/send-and-wait! session1 {:prompt "First message"})
-          session2 (sdk/resume-session *test-client* session-id {})]
+          session2 (sdk/resume-session *test-client* session-id {:on-permission-request sdk/approve-all})]
       (is (= session-id (sdk/session-id session2)))
       ;; Should be able to continue conversation
       (let [result (sdk/send-and-wait! session2 {:prompt "Follow up"})]
@@ -882,7 +885,7 @@
 
 (deftest test-session-snapshot-rewind-event
   (testing "session.snapshot_rewind event is received and parsed correctly"
-    (let [session (sdk/create-session *test-client* {})
+    (let [session (sdk/create-session *test-client* {:on-permission-request sdk/approve-all})
           session-id (sdk/session-id session)
           events-ch (sdk/subscribe-events session)
           rewind-events (atom [])]
@@ -914,7 +917,7 @@
 
 (deftest test-<create-session
   (testing "<create-session creates session asynchronously"
-    (let [result-ch (sdk/<create-session *test-client* {:model "gpt-4.1"})
+    (let [result-ch (sdk/<create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-4.1"})
           [session _] (alts!! [result-ch (timeout 5000)])]
       (is (some? session) "<create-session should deliver a session")
       (is (not (instance? Throwable session)) "<create-session should not return an error")
@@ -923,9 +926,9 @@
 
 (deftest test-<create-session-parallel
   (testing "Multiple <create-session calls run concurrently in go blocks"
-    (let [ch1 (sdk/<create-session *test-client* {:model "gpt-4.1"})
-          ch2 (sdk/<create-session *test-client* {:model "gpt-4.1"})
-          ch3 (sdk/<create-session *test-client* {:model "gpt-4.1"})
+    (let [ch1 (sdk/<create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-4.1"})
+          ch2 (sdk/<create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-4.1"})
+          ch3 (sdk/<create-session *test-client* {:on-permission-request sdk/approve-all :model "gpt-4.1"})
           [s1 _] (alts!! [ch1 (timeout 5000)])
           [s2 _] (alts!! [ch2 (timeout 5000)])
           [s3 _] (alts!! [ch3 (timeout 5000)])]