feat(tools): add :defer option to tool definitions (upstream PR #1632)

[krukow]

Ports upstream github/copilot-sdk PR #1632, which adds an optional defer: "auto" | "never" field to tool definitions. defer controls whether a tool may be deferred — loaded lazily via tool search rather than always pre-loaded into the model's context — which keeps the active context smaller for large tool sets. Upstream defaults to "auto".

What this adds

define-tool and define-tool-from-spec now accept an optional :defer keyword. The config enum is modeled idiomatically as :auto / :never (matching existing enum conventions like :storage-mode / :remote-session-mode) and converted to its wire string via (name kw). The field is sent on the tool definition in both session.create and session.resume; when omitted it is not sent and the runtime applies its "auto" default.

Implementation notes

• The two session builders (build-create-session-params / build-resume-session-params) previously carried byte-identical tool cond-> blocks. Rather than add the :defer branch in two places — a known drift hazard — this factors the tool-to-wire mapping into a private tool-def->wire helper shared by both paths.
• :defer is a single lowercase wire key, so unlike its siblings (:overridesBuiltInTool / :skipPermission) it needs no camelCase handling — only the keyword→string value conversion.
• No read-back/event surface: upstream exposes defer only on the send side (the Tool interface and defineTool config), so the port mirrors exactly those sites plus the spec and docs. There is no inbound conversion to add.

Validation

• Red/green TDD: test-defer-on-wire (create + resume, :auto/:never → wire string, absent-when-unset) and test-defer-spec (accepts :auto/:never, rejects the "auto" string and :bogus).
• Full instrumented suite green (367 tests, 1952 assertions); bb ci:full green (E2E + examples + docs + JAR); bb validate-docs clean.

Multi-model review

Reviewer	Result
Claude Opus 4.8	No blocking/major/minor issues; two redundant test nits (dismissed)
GPT-5.5	No issues found

Both independently confirmed wire-conversion correctness, full upstream parity (no missed declaration site, no read-back surface), and complete spec coverage.

_{Generated via Copilot on behalf of @krukow}

[Copilot]

Pull request overview

Ports upstream github/copilot-sdk PR #1632 by adding an optional :defer setting to Clojure tool definitions, allowing large tool sets to be lazily loaded via tool search to reduce active model context size.

Changes:

• Added :defer (:auto / :never) to define-tool and define-tool-from-spec, plus ::defer spec support.
• Refactored tool wire-shape construction into a shared private helper (tool-def->wire) used by both session.create and session.resume builders.
• Added integration/spec tests and updated docs + changelog to document the new option and its wire behavior.

Show a summary per file

File	Description
test/github/copilot_sdk/integration_test.clj	Adds tests asserting :defer keyword values serialize to "auto"/"never" on session.create/session.resume, and validates the new spec behavior.
src/github/copilot_sdk/tools.clj	Extends tool definition helpers to accept and carry :defer in the idiomatic tool map.
src/github/copilot_sdk/specs.clj	Introduces ::defer and adds it as an optional key on ::tool.
src/github/copilot_sdk/client.clj	Adds tool-def->wire helper and uses it in both create/resume param builders to include defer on the wire when set.
src/github/copilot_sdk.clj	Updates public API docs for define-tool to include :defer.
doc/reference/API.md	Documents how to use :defer and clarifies keyword→wire-string behavior and omission semantics.
CHANGELOG.md	Records the new tool option under Unreleased, referencing upstream PR #1632.

Copilot's findings

• Files reviewed: 7/7 changed files
• Comments generated: 0