[docs] Update documentation for v0.1.24 features (2026-02-14)

doc/reference/API.md

@@ -768,10 +768,12 @@ copilot/tool-events
 | `:copilot/session.context_changed` | Session context (cwd, repo, branch) changed |
 | `:copilot/session.title_changed` | Session title updated |
 | `:copilot/session.warning` | Session warning (e.g., quota limits) |
+| `:copilot/session.shutdown` | Session is shutting down |
 | `:copilot/session.truncation` | Context window truncated |
 | `: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/skill.invoked` | Skill invocation triggered |
 | `:copilot/user.message` | User message added |
 | `:copilot/pending_messages.modified` | Pending message queue updated |
 | `:copilot/assistant.turn_start` | Assistant turn started |

examples/README.md

@@ -47,6 +47,9 @@ clojure -A:examples -X multi-agent/run :topics '["AI safety" "machine learning"]
 # Config directory, skills, and large output
 clojure -A:examples -X config-skill-output/run
 
+# Metadata API (list-tools, get-quota, model switching)
+clojure -A:examples -X metadata-api/run
+
 # Permission handling
 clojure -A:examples -X permission-bash/run
 
@@ -72,7 +75,7 @@ Or run all examples:
 ```
 
 > **Note:** `run-all-examples.sh` runs the core examples (1–9) that need only the Copilot CLI.
-> The BYOK and MCP examples require external dependencies (API keys, Node.js) and must be run manually.
+> Example 10 (BYOK) and Example 11 (MCP) require external dependencies (API keys, Node.js) and must be run manually.
 
 With a custom CLI path:
 ```bash
@@ -327,6 +330,40 @@ clojure -A:examples -X config-skill-output/run
 
 ---
 
+## Example 6: Metadata API (`metadata_api.clj`)
+
+**Difficulty:** Beginner  
+**Concepts:** list-sessions, list-tools, get-quota, get-current-model, switch-model
+
+Demonstrates the metadata API functions introduced in v0.1.24 for inspecting available tools, quota information, and dynamically switching models within a session.
+
+### What It Demonstrates
+
+- `list-sessions` with context filtering (by repository, branch, cwd)
+- `list-tools` to enumerate available tools, with optional model-specific overrides
+- `get-quota` to check account usage and entitlements
+- `get-current-model` to inspect the session's current model
+- `switch-model!` to change the model mid-conversation while maintaining context
+
+### Usage
+
+```bash
+# Run the metadata API demo
+clojure -A:examples -X metadata-api/run
+```
+
+### Key Points
+
+- **list-sessions**: Filter sessions by context (`:repository`, `:branch`, `:cwd`, `:git-root`)
+- **list-tools**: Get tool metadata; pass a model ID for model-specific tool lists
+- **get-quota**: Returns a map of quota type to snapshot (entitlement, used, remaining %)
+- **switch-model!**: Change models dynamically without losing conversation context
+
+> **Note:** Some methods (`tools.list`, `account.getQuota`, `session.model.*`) may not be
+> supported by all CLI versions. The example gracefully skips unsupported operations.
+
+---
+
 ## Example 7: Permission Handling (`permission_bash.clj`)
 
 **Difficulty:** Intermediate  

examples/metadata_api.clj

@@ -0,0 +1,73 @@
+(ns metadata-api
+  "Demonstrates the metadata API functions introduced in v0.1.24:
+   - list-sessions with context filtering
+   - list-tools with model-specific overrides
+   - get-quota for account usage information
+   - get-current-model and switch-model for dynamic model switching
+
+   Note: Some methods (tools.list, account.getQuota, session.model.*)
+   require a CLI version that supports them. The example gracefully
+   handles unsupported methods."
+  (:require [github.copilot-sdk :as copilot]
+            [github.copilot-sdk.helpers :as h]))
+
+;; See examples/README.md for usage
+
+(defn run
+  [& _]
+  (println "=== Copilot Metadata API Demo ===\n")
+
+  (copilot/with-client [client {:log-level :warning}]
+    ;; 1. List sessions (supported on all CLI versions)
+    (println "1. Active Sessions:")
+    (let [sessions (copilot/list-sessions client)]
+      (println (str "   Found " (count sessions) " session(s)"))
+      (when (seq sessions)
+        (doseq [session (take 3 sessions)]
+          (println (str "   - " (:session-id session)))
+          (when-let [ctx (:context session)]
+            (println (str "     Repository: " (:repository ctx)))
+            (println (str "     Branch: " (:branch ctx)))))))
+
+    ;; 2. List available tools
+    (println "\n2. Available Tools:")
+    (try
+      (let [tools (copilot/list-tools client)]
+        (println (str "   Found " (count tools) " tools"))
+        (doseq [tool (take 5 tools)]
+          (println (str "   - " (:name tool) ": " (:description tool)))))
+      (catch Exception e
+        (println (str "   Skipped: " (.getMessage e)))))
+
+    ;; 3. Get quota information
+    (println "\n3. Account Quota:")
+    (try
+      (let [quotas (copilot/get-quota client)]
+        (doseq [[quota-type snapshot] quotas]
+          (println (str "   " quota-type ":"))
+          (println (str "     Entitlement: " (:entitlement-requests snapshot)))
+          (println (str "     Used: " (:used-requests snapshot)))
+          (println (str "     Remaining: " (:remaining-percentage snapshot) "%"))))
+      (catch Exception e
+        (println (str "   Skipped: " (.getMessage e)))))
+
+    ;; 4. Model switching within a session
+    (println "\n4. Dynamic Model Switching:")
+    (copilot/with-session [session client {}]
+      ;; Query with default model
+      (println "   Query: 'What is 2+2? Answer briefly.'")
+      (println (str "   Response: " (h/query "What is 2+2? Answer briefly." :session session)))
+
+      ;; Try model introspection (requires CLI support)
+      (try
+        (let [current (copilot/get-current-model session)]
+          (println (str "\n   Current model: " current))
+          (copilot/switch-model! session "gpt-4o")
+          (println (str "   Switched to: " (copilot/get-current-model session)))
+          (println "   Query: 'What was my previous question?'")
+          (println (str "   Response: " (h/query "What was my previous question?" :session session))))
+        (catch Exception e
+          (println (str "\n   Model switching skipped: " (.getMessage e)))))))
+
+  (println "\n=== Demo Complete ==="))
+

run-all-examples.sh

@@ -26,6 +26,10 @@ echo ""
 echo "=== config-skill-output ==="
 clojure -A:examples -X config-skill-output/run
 
+echo ""
+echo "=== metadata-api ==="
+clojure -A:examples -X metadata-api/run
+
 echo ""
 echo "=== permission-bash ==="
 clojure -A:examples -X permission-bash/run