fix: audit Java code samples against SDK implementation

- Fix PreToolUseHookOutput: record cannot use setters, use deny() factory
- Fix SessionStartHookOutput: record cannot use setters, use constructor
- Fix session.getId() → session.getSessionId()
- Fix input.getPrompt() → input.prompt() (record accessor)
- Fix response.data() → response.getData() (class accessor)
- Fix setOnListModels: wrap return in CompletableFuture.completedFuture()
- Fix custom-agents event handler: use instanceof pattern matching
  (AbstractSessionEvent has no getData() method)
- Fix streaming-events: remove event.getData() from generic handler
- Fix SubagentCompleted/Failed: use agentName() not agentDisplayName()
- Fix CopilotClientOptions import: class is in json package, not sdk
- Fix hook type signatures: use PreToolUseHandler etc. instead of BiFunction

Author: brunoborges

docs/auth/byok.md

@@ -169,7 +169,6 @@ Console.WriteLine(response?.Data.Content);
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
 import com.github.copilot.sdk.events.*;
 import com.github.copilot.sdk.json.*;
 
@@ -448,17 +447,18 @@ var client = new CopilotClient(new CopilotClientOptions
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
+import com.github.copilot.sdk.json.*;
+import java.util.concurrent.CompletableFuture;
 
 var client = new CopilotClient(new CopilotClientOptions()
-    .setOnListModels(() -> List.of(
+    .setOnListModels(() -> CompletableFuture.completedFuture(List.of(
         new ModelInfo()
             .setId("my-custom-model")
             .setName("My Custom Model")
             .setCapabilities(new ModelCapabilities()
                 .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))
                 .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))
-    ))
+    )))
 );
 ```
 

docs/auth/index.md

@@ -207,7 +207,7 @@ await using var client = new CopilotClient(new CopilotClientOptions
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
+import com.github.copilot.sdk.json.*;
 
 var client = new CopilotClient(new CopilotClientOptions()
     .setGitHubToken(userAccessToken)  // Token from OAuth flow
@@ -385,7 +385,7 @@ await using var client = new CopilotClient(new CopilotClientOptions
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
+import com.github.copilot.sdk.json.*;
 
 var client = new CopilotClient(new CopilotClientOptions()
     .setUseLoggedInUser(false)  // Only use explicit tokens

docs/features/custom-agents.md

@@ -623,23 +623,19 @@ await session.SendAndWaitAsync(new MessageOptions
 
 ```java
 session.on(event -> {
-    switch (event.getType()) {
-        case "subagent.started" -> {
-            System.out.println("▶ Sub-agent started: " + event.getData().agentDisplayName());
-            System.out.println("  Description: " + event.getData().agentDescription());
-            System.out.println("  Tool call ID: " + event.getData().toolCallId());
-        }
-        case "subagent.completed" ->
-            System.out.println("✅ Sub-agent completed: " + event.getData().agentDisplayName());
-        case "subagent.failed" -> {
-            System.out.println("❌ Sub-agent failed: " + event.getData().agentDisplayName());
-            System.out.println("  Error: " + event.getData().error());
-        }
-        case "subagent.selected" ->
-            System.out.println("🎯 Agent selected: " + event.getData().agentDisplayName());
-        case "subagent.deselected" ->
-            System.out.println("↩ Agent deselected, returning to parent");
-        default -> {}
+    if (event instanceof SubagentStartedEvent e) {
+        System.out.println("▶ Sub-agent started: " + e.getData().agentDisplayName());
+        System.out.println("  Description: " + e.getData().agentDescription());
+        System.out.println("  Tool call ID: " + e.getData().toolCallId());
+    } else if (event instanceof SubagentCompletedEvent e) {
+        System.out.println("✅ Sub-agent completed: " + e.getData().agentName());
+    } else if (event instanceof SubagentFailedEvent e) {
+        System.out.println("❌ Sub-agent failed: " + e.getData().agentName());
+        System.out.println("  Error: " + e.getData().error());
+    } else if (event instanceof SubagentSelectedEvent e) {
+        System.out.println("🎯 Agent selected: " + e.getData().agentDisplayName());
+    } else if (event instanceof SubagentDeselectedEvent e) {
+        System.out.println("↩ Agent deselected, returning to parent");
     }
 });
 

docs/features/hooks.md

@@ -417,10 +417,8 @@ var hooks = new SessionHooks()
     .setOnPreToolUse((input, invocation) -> {
         if (!readOnlyTools.contains(input.getToolName())) {
             return CompletableFuture.completedFuture(
-                new PreToolUseHookOutput()
-                    .setPermissionDecision("deny")
-                    .setPermissionDecisionReason(
-                        "Only read-only tools are allowed. \"" + input.getToolName() + "\" was blocked.")
+                PreToolUseHookOutput.deny(
+                    "Only read-only tools are allowed. \"" + input.getToolName() + "\" was blocked.")
             );
         }
         return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());

docs/features/streaming-events.md

@@ -196,7 +196,7 @@ session.On(evt =>
 
 ```java
 // All events
-session.on(event -> System.out.println(event.getType() + " " + event.getData()));
+session.on(event -> System.out.println(event.getType()));
 
 // Specific event type — data is narrowed to the matching class
 session.on(AssistantMessageDeltaEvent.class, event ->

docs/getting-started.md

@@ -1707,7 +1707,7 @@ await using var session = await client.CreateSessionAsync(new()
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
+import com.github.copilot.sdk.json.*;
 
 var client = new CopilotClient(
     new CopilotClientOptions().setCliUrl("localhost:4321")
@@ -1811,7 +1811,7 @@ No extra dependencies — uses built-in `System.Diagnostics.Activity`.
 <!-- docs-validate: skip -->
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.CopilotClientOptions;
+import com.github.copilot.sdk.json.*;
 
 var client = new CopilotClient(new CopilotClientOptions()
     .setTelemetry(new TelemetryConfig()

docs/hooks/error-handling.md

@@ -284,7 +284,7 @@ var session = client.createSession(
 
 session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
 session.setEventErrorHandler((event, ex) -> {
-    System.err.println("[" + session.getId() + "] Error: " + ex.getMessage());
+    System.err.println("[" + session.getSessionId() + "] Error: " + ex.getMessage());
     System.err.println("  Event: " + event.getType());
 });
 ```

docs/hooks/index.md

@@ -178,7 +178,7 @@ try (var client = new CopilotClient()) {
         })
         .setOnSessionStart((input, invocation) -> {
             return CompletableFuture.completedFuture(
-                new SessionStartHookOutput().setAdditionalContext("User prefers concise answers.")
+                new SessionStartHookOutput("User prefers concise answers.", null)
             );
         });
 

docs/hooks/post-tool-use.md

@@ -104,11 +104,8 @@ public delegate Task<PostToolUseHookOutput?> PostToolUseHandler(
 
 ```java
 import com.github.copilot.sdk.json.*;
-import java.util.concurrent.CompletableFuture;
-import java.util.function.BiFunction;
 
-BiFunction<PostToolUseHookInput, HookInvocation,
-    CompletableFuture<PostToolUseHookOutput>> postToolUseHandler;
+PostToolUseHandler postToolUseHandler;
 ```
 
 </details>

docs/hooks/pre-tool-use.md

@@ -104,11 +104,8 @@ public delegate Task<PreToolUseHookOutput?> PreToolUseHandler(
 
 ```java
 import com.github.copilot.sdk.json.*;
-import java.util.concurrent.CompletableFuture;
-import java.util.function.BiFunction;
 
-BiFunction<PreToolUseHookInput, HookInvocation,
-    CompletableFuture<PreToolUseHookOutput>> preToolUseHandler;
+PreToolUseHandler preToolUseHandler;
 ```
 
 </details>