feat(tool-set): add github.copilot-sdk.tool-set namespace + isolated preset

Source-qualified tool filter constructors (builtin/mcp/custom + builtins
vector form) plus isolated-builtins / isolated for parity with upstream
BuiltInTools.Isolated. Bare "*" is rejected at construction time.

Adds fdef specs in instrument.clj for every public fn so integration
tests with instrumentation enabled catch contract violations.

Mirrors upstream nodejs/src/toolSet.ts from PR github/copilot-sdk#1428
github/copilot-sdk#1428

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

Author: krukow

script/validate_docs.clj

@@ -42,6 +42,7 @@
     "github.copilot-sdk.specs"
     "github.copilot-sdk.instrument"
     "github.copilot-sdk.tools"
+    "github.copilot-sdk.tool-set"
     "github.copilot-sdk.generated.event-specs"
     "github.copilot-sdk.generated.coerce"})
 

src/github/copilot_sdk/instrument.clj

@@ -14,7 +14,11 @@
      (stest/unstrument)"
   (:require [clojure.spec.alpha :as s]
             [clojure.spec.test.alpha :as stest]
-            [github.copilot-sdk.specs :as specs]))
+            [github.copilot-sdk.specs :as specs]
+            ;; Ensure namespaces hosting public fns referenced by `register-fdef!`
+            ;; are loaded before `stest/instrument` runs (otherwise the missing
+            ;; var would be silently skipped, leaving an instrumentation gap).
+            [github.copilot-sdk.tool-set]))
 
 ;; -----------------------------------------------------------------------------
 ;; Single-source registry for fdefs
@@ -566,6 +570,30 @@
   :args (s/cat :client ::specs/client :params map?)
   :ret map?)
 
+;; -----------------------------------------------------------------------------
+;; Tool filter helpers (upstream PR #1428)
+;; -----------------------------------------------------------------------------
+
+(register-fdef! github.copilot-sdk.tool-set/valid-name?
+  :args (s/cat :name any?)
+  :ret boolean?)
+
+(register-fdef! github.copilot-sdk.tool-set/builtin
+  :args (s/cat :name string?)
+  :ret string?)
+
+(register-fdef! github.copilot-sdk.tool-set/mcp
+  :args (s/cat :name string?)
+  :ret string?)
+
+(register-fdef! github.copilot-sdk.tool-set/custom
+  :args (s/cat :name string?)
+  :ret string?)
+
+(register-fdef! github.copilot-sdk.tool-set/builtins
+  :args (s/cat :names (s/coll-of string?))
+  :ret (s/coll-of string? :kind vector?))
+
 ;; -----------------------------------------------------------------------------
 ;; Instrument all public API functions
 ;; -----------------------------------------------------------------------------

src/github/copilot_sdk/tool_set.clj

@@ -0,0 +1,91 @@
+(ns github.copilot-sdk.tool-set
+  "Helpers for building source-qualified tool filter patterns used by
+   `:available-tools` and `:excluded-tools` in session configs.
+
+   The runtime matches each tool reference against patterns of the form
+   `\"<source>:<name>\"` where source is one of `builtin`, `mcp`, or
+   `custom` and name is either a literal tool name or the wildcard
+   `\"*\"`. The bare wildcard `\"*\"` (no source) is intentionally
+   rejected by the SDK — apps must explicitly opt into a source so an
+   absent source can never silently grant access to unexpected tools.
+
+   Mirrors upstream `ToolSet` and `BuiltInTools` from
+   `nodejs/src/toolSet.ts` (upstream PR #1428).
+
+   Examples:
+
+     (tool-set/builtin \"ask_user\")  ;; => \"builtin:ask_user\"
+     (tool-set/builtin \"*\")          ;; => \"builtin:*\"
+     (tool-set/mcp \"*\")              ;; => \"mcp:*\"
+     (tool-set/builtins [\"task\" \"skill\"]) ;; => [\"builtin:task\" \"builtin:skill\"]
+
+     ;; Ready-to-use: every built-in that is safely session-bounded.
+     tool-set/isolated  ;; => [\"builtin:ask_user\" \"builtin:task_complete\" ...]")
+
+(def ^:private valid-name-regex
+  "Allowed characters in a tool name segment (mirrors upstream `nameRe`)."
+  #"^[a-zA-Z0-9_-]+$")
+
+(defn valid-name?
+  "True when `name` is a valid tool-name segment — alphanumeric plus
+   `_` and `-`, or the literal wildcard `\"*\"`. Returns false for any
+   non-string input."
+  [name]
+  (and (string? name)
+       (or (= "*" name)
+           (some? (re-matches valid-name-regex name)))))
+
+(defn- validate! [source name]
+  (when-not (valid-name? name)
+    (throw (ex-info (format "Invalid %s tool name: %s" source (pr-str name))
+                    {:source source :name name}))))
+
+(defn builtin
+  "Returns the filter pattern `\"builtin:<name>\"`. `name` may be the
+   wildcard `\"*\"`. Throws on invalid names."
+  [name]
+  (validate! "builtin" name)
+  (str "builtin:" name))
+
+(defn mcp
+  "Returns the filter pattern `\"mcp:<name>\"`. `name` may be the
+   wildcard `\"*\"`. Throws on invalid names."
+  [name]
+  (validate! "mcp" name)
+  (str "mcp:" name))
+
+(defn custom
+  "Returns the filter pattern `\"custom:<name>\"`. `name` may be the
+   wildcard `\"*\"`. Throws on invalid names."
+  [name]
+  (validate! "custom" name)
+  (str "custom:" name))
+
+(defn builtins
+  "Returns a vector of `\"builtin:<name>\"` patterns, one per entry in
+   `names`. Throws on the first invalid name."
+  [names]
+  (mapv builtin names))
+
+(def isolated-builtins
+  "Names of the built-in tools that are safely session-bounded (no host
+   I/O). Mirrors upstream `BuiltInTools.Isolated`. Use [[isolated]] for
+   the source-qualified form ready to drop into `:available-tools`."
+  ["ask_user"
+   "task_complete"
+   "exit_plan_mode"
+   "task"
+   "read_agent"
+   "write_agent"
+   "list_agents"
+   "send_inbox"
+   "context_board"
+   "skill"])
+
+(def isolated
+  "Source-qualified `\"builtin:<name>\"` patterns for every tool in
+   [[isolated-builtins]]. Drop directly into `:available-tools`:
+
+     (copilot/create-session client
+       {:available-tools tool-set/isolated})"
+  (builtins isolated-builtins))

test/github/copilot_sdk/tool_set_test.clj

@@ -0,0 +1,89 @@
+(ns github.copilot-sdk.tool-set-test
+  "Unit tests for github.copilot-sdk.tool-set — the source-qualified tool
+   filter helpers introduced by upstream PR #1428."
+  (:require [clojure.test :refer [deftest is testing]]
+            [github.copilot-sdk.tool-set :as tool-set]))
+
+(deftest valid-name?-tests
+  (testing "alphanumeric, underscore, hyphen are valid"
+    (is (true? (tool-set/valid-name? "ask_user")))
+    (is (true? (tool-set/valid-name? "task-complete")))
+    (is (true? (tool-set/valid-name? "Tool123")))
+    (is (true? (tool-set/valid-name? "a"))))
+  (testing "literal wildcard is valid"
+    (is (true? (tool-set/valid-name? "*"))))
+  (testing "wildcards in the middle of a name are invalid"
+    (is (false? (tool-set/valid-name? "ask*"))))
+  (testing "spaces, colons, dots, slashes are invalid"
+    (is (false? (tool-set/valid-name? "ask user")))
+    (is (false? (tool-set/valid-name? "builtin:ask_user")))
+    (is (false? (tool-set/valid-name? "ask.user")))
+    (is (false? (tool-set/valid-name? "ask/user"))))
+  (testing "empty string and non-strings are invalid"
+    (is (false? (tool-set/valid-name? "")))
+    (is (false? (tool-set/valid-name? nil)))
+    (is (false? (tool-set/valid-name? :ask_user)))
+    (is (false? (tool-set/valid-name? 42)))))
+
+(deftest builtin-tests
+  (testing "produces source-qualified pattern"
+    (is (= "builtin:ask_user" (tool-set/builtin "ask_user")))
+    (is (= "builtin:*" (tool-set/builtin "*"))))
+  (testing "rejects invalid name"
+    (is (thrown-with-msg? clojure.lang.ExceptionInfo
+                          #"Invalid builtin tool name"
+                          (tool-set/builtin "bad name")))
+    (is (thrown-with-msg? clojure.lang.ExceptionInfo
+                          #"Invalid builtin tool name"
+                          (tool-set/builtin "")))))
+
+(deftest mcp-tests
+  (testing "produces source-qualified pattern"
+    (is (= "mcp:my_server" (tool-set/mcp "my_server")))
+    (is (= "mcp:*" (tool-set/mcp "*"))))
+  (testing "rejects invalid name"
+    (is (thrown-with-msg? clojure.lang.ExceptionInfo
+                          #"Invalid mcp tool name"
+                          (tool-set/mcp "bad:name")))))
+
+(deftest custom-tests
+  (testing "produces source-qualified pattern"
+    (is (= "custom:reviewer" (tool-set/custom "reviewer")))
+    (is (= "custom:*" (tool-set/custom "*"))))
+  (testing "rejects invalid name"
+    (is (thrown-with-msg? clojure.lang.ExceptionInfo
+                          #"Invalid custom tool name"
+                          (tool-set/custom "has space")))))
+
+(deftest builtins-tests
+  (testing "maps over names and returns a vector"
+    (is (= ["builtin:task" "builtin:skill"]
+           (tool-set/builtins ["task" "skill"])))
+    (is (vector? (tool-set/builtins ["task"]))))
+  (testing "empty input yields empty vector"
+    (is (= [] (tool-set/builtins []))))
+  (testing "throws on the first invalid entry"
+    (is (thrown-with-msg? clojure.lang.ExceptionInfo
+                          #"Invalid builtin tool name"
+                          (tool-set/builtins ["ok" "bad name"])))))
+
+(deftest isolated-builtins-tests
+  (testing "matches upstream BuiltInTools.Isolated exactly"
+    (is (= ["ask_user"
+            "task_complete"
+            "exit_plan_mode"
+            "task"
+            "read_agent"
+            "write_agent"
+            "list_agents"
+            "send_inbox"
+            "context_board"
+            "skill"]
+           tool-set/isolated-builtins))))
+
+(deftest isolated-tests
+  (testing "is the source-qualified form of isolated-builtins"
+    (is (= (mapv #(str "builtin:" %) tool-set/isolated-builtins)
+           tool-set/isolated)))
+  (testing "every entry starts with builtin: prefix"
+    (is (every? #(.startsWith ^String % "builtin:") tool-set/isolated))))