Add tests, documentation, and CHANGELOG for session context feature

Co-authored-by: brunoborges <129743+brunoborges@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -8,7 +8,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-> **Upstream sync:** [`github/copilot-sdk@05e3c46`](https://github.com/github/copilot-sdk/commit/05e3c46c8c23130c9c064dc43d00ec78f7a75eab)
+> **Upstream sync:** [`github/copilot-sdk@e40d57c`](https://github.com/github/copilot-sdk/commit/e40d57c86e18b495722adbf42045288c03924342)
+
+### Added
+
+#### Session Context and Filtering
+
+Added session context tracking and filtering capabilities to help manage multiple Copilot sessions across different repositories and working directories.
+
+**New Classes:**
+- `SessionContext` - Represents working directory context (cwd, gitRoot, repository, branch) with fluent setters
+- `SessionListFilter` - Filter sessions by context fields (extends SessionContext)
+- `SessionContextChangedEvent` - Event fired when working directory context changes between turns
+
+**Updated APIs:**
+- `SessionMetadata.getContext()` - Returns optional context information for persisted sessions
+- `CopilotClient.listSessions(SessionListFilter)` - New overload to filter sessions by context criteria
+
+**Example:**
+```java
+// List sessions for a specific repository
+var filter = new SessionListFilter()
+    .setRepository("owner/repo")
+    .setBranch("main");
+var sessions = client.listSessions(filter).get();
+
+// Access context information
+for (var session : sessions) {
+    var ctx = session.getContext();
+    if (ctx != null) {
+        System.out.println("CWD: " + ctx.getCwd());
+        System.out.println("Repo: " + ctx.getRepository());
+    }
+}
+
+// Listen for context changes
+session.on(SessionContextChangedEvent.class, event -> {
+    SessionContext newContext = event.getData();
+    System.out.println("Working directory changed to: " + newContext.getCwd());
+});
+```
+
+**Requirements:**
+- GitHub Copilot CLI 0.0.409 or later
 
 ## [1.0.8] - 2026-02-08
 

src/site/markdown/advanced.md

@@ -24,6 +24,10 @@ This guide covers advanced scenarios for extending and customizing your Copilot
 - [Permission Handling](#Permission_Handling)
 - [Session Hooks](#Session_Hooks)
 - [Manual Server Control](#Manual_Server_Control)
+- [Session Context and Filtering](#Session_Context_and_Filtering)
+  - [Listing Sessions with Context](#Listing_Sessions_with_Context)
+  - [Filtering Sessions by Context](#Filtering_Sessions_by_Context)
+  - [Context Changed Events](#Context_Changed_Events)
 - [Session Lifecycle Events](#Session_Lifecycle_Events)
   - [Subscribing to All Lifecycle Events](#Subscribing_to_All_Lifecycle_Events)
   - [Subscribing to Specific Event Types](#Subscribing_to_Specific_Event_Types)
@@ -500,6 +504,65 @@ client.forceStop().get();
 
 ---
 
+## Session Context and Filtering
+
+Track and filter sessions by their working directory context including the current directory, git repository, and branch information.
+
+### Listing Sessions with Context
+
+Session metadata may include context information for persisted sessions:
+
+```java
+var sessions = client.listSessions().get();
+for (var session : sessions) {
+    var context = session.getContext();
+    if (context != null) {
+        System.out.println("Session: " + session.getSessionId());
+        System.out.println("  Working dir: " + context.getCwd());
+        System.out.println("  Repository: " + context.getRepository());
+        System.out.println("  Branch: " + context.getBranch());
+        System.out.println("  Git root: " + context.getGitRoot());
+    }
+}
+```
+
+### Filtering Sessions by Context
+
+Use `SessionListFilter` to filter sessions by context fields:
+
+```java
+// Find sessions for a specific repository
+var filter = new SessionListFilter()
+    .setRepository("owner/myproject")
+    .setBranch("main");
+
+var sessions = client.listSessions(filter).get();
+```
+
+Filter options:
+- `setCwd(String)` - Filter by exact working directory match
+- `setGitRoot(String)` - Filter by git repository root
+- `setRepository(String)` - Filter by repository in "owner/repo" format
+- `setBranch(String)` - Filter by git branch name
+
+### Context Changed Events
+
+Listen for changes to the working directory context:
+
+```java
+session.on(SessionContextChangedEvent.class, event -> {
+    var newContext = event.getData();
+    System.out.println("Context changed:");
+    System.out.println("  New CWD: " + newContext.getCwd());
+    System.out.println("  Repository: " + newContext.getRepository());
+    System.out.println("  Branch: " + newContext.getBranch());
+});
+```
+
+The `session.context_changed` event fires when the working directory context changes between conversation turns.
+
+---
+
 ## Session Lifecycle Events
 
 Subscribe to lifecycle events to be notified when sessions are created, deleted, updated, or change foreground/background state.

src/test/java/com/github/copilot/sdk/CopilotSessionTest.java

@@ -762,4 +762,60 @@ void testShouldPassStreamingOptionToSessionCreation() throws Exception {
             session.close();
         }
     }
+
+    /**
+     * Verifies that listSessions returns metadata with optional context
+     * information.
+     *
+     * @see Snapshot: session/should_list_sessions
+     */
+    @Test
+    void testListSessionsIncludesContextWhenAvailable() throws Exception {
+        ctx.configureForTest("session", "should_list_sessions");
+
+        try (CopilotClient client = ctx.createClient()) {
+            var session = client.createSession().get();
+
+            var sessions = client.listSessions().get(30, TimeUnit.SECONDS);
+            assertNotNull(sessions);
+
+            // List may be empty or contain sessions depending on test environment
+            // The main goal is to verify the API works and context field is accessible
+            for (var s : sessions) {
+                assertNotNull(s.getSessionId());
+                // Context field is optional
+                if (s.getContext() != null) {
+                    // When context is present, cwd should be non-null
+                    assertNotNull(s.getContext().getCwd());
+                }
+            }
+
+            session.close();
+        }
+    }
+
+    /**
+     * Verifies that SessionListFilter works with fluent setters.
+     */
+    @Test
+    void testSessionListFilterFluentAPI() throws Exception {
+        ctx.configureForTest("session", "should_list_sessions");
+
+        try (CopilotClient client = ctx.createClient()) {
+            var session = client.createSession().get();
+
+            var filter = new com.github.copilot.sdk.json.SessionListFilter().setCwd("/test/path")
+                    .setRepository("owner/repo").setBranch("main").setGitRoot("/test");
+
+            assertEquals("/test/path", filter.getCwd());
+            assertEquals("owner/repo", filter.getRepository());
+            assertEquals("main", filter.getBranch());
+            assertEquals("/test", filter.getGitRoot());
+
+            var filteredSessions = client.listSessions(filter).get(30, TimeUnit.SECONDS);
+            assertNotNull(filteredSessions);
+
+            session.close();
+        }
+    }
 }