Fix permission denial keyword types and pin examples to gpt-5.2

[krukow]

Summary

Two changes bundled together from code review findings:

1. Fix permission denial :kind type consistency

Default permission-denial responses in session.clj and client.clj returned :kind as a string ("denied-no-approval-rule-and-could-not-request-from-user"), while the spec (::permission-result-kind) and approve-all both use keywords. This created an internal type mismatch that could confuse users inspecting responses.

Changes:

• session.clj: 3 denial paths now return keyword :kind
• client.clj: unknown-session denial now returns keyword :kind
• integration_test.clj: updated assertion to expect keyword

Also includes upstream PR #509 sync (deny-by-default permissions):

• requestPermission always true on wire
• approve-all convenience handler
• Integration tests for deny-by-default permission model
• Documentation and changelog updates

2. Pin all examples to gpt-5.2 model

Examples that relied on the CLI default model or used gpt-4.1/gpt-4o now explicitly specify gpt-5.2 for consistent behavior across environments.

Changed: helpers_query.clj, metadata_api.clj, multi_agent.clj
Unchanged: BYOK provider examples (claude-sonnet-4, llama3) — intentionally provider-specific.

Validation

• bb test: 83 tests, 246 assertions, 0 failures ✅
• helpers-query/run, metadata-api/run, multi-agent/run: all pass ✅

[Copilot]

Pull request overview

This PR syncs upstream permission-handling behavior (deny-by-default) while fixing internal :kind type consistency for permission-denial results, and pins example code to the gpt-5.2 model for determinism.

Changes:

• Make default permission-denial :kind values keywords (matching specs and approve-all) and add approve-all helper + docs/changelog for deny-by-default permissions.
• Force requestPermission to be true on create/resume wire params and expand integration tests around the new permission model.
• Update examples/docs to explicitly use gpt-5.2 and document deny-by-default permissions + approve-all.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/github/copilot_sdk/session.clj	Uses keyword :kind in default permission-denial paths.
src/github/copilot_sdk/client.clj	Uses keyword :kind for unknown-session denial; always sends :request-permission true; adds approve-all.
src/github/copilot_sdk/instrument.clj	Adds spec/instrumentation for client/approve-all.
src/github/copilot_sdk.clj	Re-exports approve-all from client.
test/github/copilot_sdk/integration_test.clj	Adds/updates tests for deny-by-default permission model and keyword :kind.
test/github/copilot_sdk/mock_server.clj	Adds a helper intended to inject permission requests in tests.
examples/helpers_query.clj	Pins helper-based queries to gpt-5.2.
examples/metadata_api.clj	Pins session model to gpt-5.2 in the metadata demo (including model switching section).
examples/multi_agent.clj	Pins multi-agent example model to gpt-5.2.
examples/mcp_local_server.clj	Adds :on-permission-request copilot/approve-all to satisfy deny-by-default for MCP tools.
examples/README.md	Updates snippets to use gpt-5.2 and documents deny-by-default permissions + approve-all.
doc/reference/API.md	Documents deny-by-default permissions and adds approve-all reference section.
README.md	Notes deny-by-default permissions in the “Advanced Usage” bullet.
CHANGELOG.md	Adds breaking-change note for deny-by-default permissions and documents approve-all + keyword :kind fix.

Comments suppressed due to low confidence (1)

src/github/copilot_sdk/session.clj:172

• handle-permission-request! passes the incoming request map through to the user handler unchanged. In this PR's integration tests, :permission-kind is a string ("shell"), while ::specs/permission-request requires keyword kinds. Consider normalizing request before invoking the handler (e.g., convert string kinds to keywords) so handler inputs match the documented/spec’d shape and approve-all can be safely instrumented.

         {:result {:kind :denied-no-approval-rule-and-could-not-request-from-user}}
         (try
           (let [result (handler request {:session-id session-id})
                 ;; If handler returns a channel, await it
                 result (if (channel? result)
                          (<!! result)
                          result)]

[Copilot]

inject-permission-request!'s docstring says it returns a channel delivering the permission response, but the function currently returns only request-id and never uses response-ch (also no mechanism to capture the client's JSON-RPC response). Either implement response capture (e.g., track pending request IDs and deliver responses on a channel) or update the docstring/signature and remove the unused local.

[Copilot]

The new approve-all fdef requires :request to conform to ::specs/permission-request, which currently requires keyword :permission-kind. However, wire-level permission requests may carry string kinds (and tests in this PR construct them as strings). Either relax the fdef to accept the wire shape as well, or ensure permission requests are normalized to keyword kinds before calling the handler; otherwise instrumentation can fail when users pass github.copilot-sdk.client/approve-all as :on-permission-request.

Suggested change

	:args (s/cat :request ::specs/permission-request
	:args (s/cat :request (s/or :normalized ::specs/permission-request
	:wire map?)

[Copilot]

This section is labeled “Dynamic Model Switching”, but the session is created with :model "gpt-5.2" and then switch-model! is called with the same model, so it doesn't actually demonstrate switching. Either start the session without an explicit model and switch to gpt-5.2, or switch to a different known-good model while keeping the initial model pinned for the earlier queries.