Add onPermissionRequest handler to session creation across multiple files

Author: horihiro

docs/auth/byok.md

@@ -79,6 +79,7 @@ const session = await client.createSession({
         wireApi: "responses",  // Use "completions" for older models
         apiKey: process.env.FOUNDRY_API_KEY,
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 session.on("assistant.message", (event) => {
@@ -350,12 +351,14 @@ When using BYOK, the `model` parameter is **required**:
 // ❌ Error: Model required with custom provider
 const session = await client.createSession({
     provider: { type: "openai", baseUrl: "..." },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // ✅ Correct: Model specified
 const session = await client.createSession({
     model: "gpt-4",  // Required!
     provider: { type: "openai", baseUrl: "..." },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 

docs/compatibility.md

@@ -158,6 +158,7 @@ const session = await client.createSession({
     backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
     bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
   },
+  onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 

docs/debugging.md

@@ -376,8 +376,9 @@ const client = new CopilotClient({
    ```typescript
    const session = await client.createSession({
      tools: [myTool],
+     onPermissionRequest: async () => ({ kind: "approved" }),
    });
-   
+
    // Check registered tools
    console.log("Registered tools:", session.getTools?.());
    ```

docs/getting-started.md

@@ -105,7 +105,7 @@ Create `index.ts`:
 import { CopilotClient } from "@github/copilot-sdk";
 
 const client = new CopilotClient();
-const session = await client.createSession({ model: "gpt-4.1" });
+const session = await client.createSession({ model: "gpt-4.1", onPermissionRequest: async () => ({ kind: "approved" }) });
 
 const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
 console.log(response?.data.content);
@@ -248,6 +248,7 @@ const client = new CopilotClient();
 const session = await client.createSession({
     model: "gpt-4.1",
     streaming: true,
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // Listen for response chunks
@@ -624,6 +625,7 @@ const session = await client.createSession({
     model: "gpt-4.1",
     streaming: true,
     tools: [getWeather],
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 session.on("assistant.message_delta", (event) => {
@@ -876,6 +878,7 @@ const session = await client.createSession({
     model: "gpt-4.1",
     streaming: true,
     tools: [getWeather],
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 session.on("assistant.message_delta", (event) => {
@@ -1221,6 +1224,7 @@ const session = await client.createSession({
             url: "https://api.githubcopilot.com/mcp/",
         },
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -1238,6 +1242,7 @@ const session = await client.createSession({
         description: "Reviews pull requests for best practices",
         prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
     }],
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -1250,6 +1255,7 @@ const session = await client.createSession({
     systemMessage: {
         content: "You are a helpful assistant for our engineering team. Always be concise.",
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 

docs/guides/session-persistence.md

@@ -34,6 +34,7 @@ const client = new CopilotClient();
 const session = await client.createSession({
   sessionId: "user-123-task-456",
   model: "gpt-5.2-codex",
+  onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // Do some work...
@@ -111,10 +112,10 @@ flowchart LR
     subgraph Day1["Day 1"]
         A1[Client A:<br/>createSession] --> A2[Work...]
     end
-    
+
     A2 --> S[(💾 Storage:<br/>~/.copilot/session-state/)]
     S --> B1
-    
+
     subgraph Day2["Day 2"]
         B1[Client B:<br/>resumeSession] --> B2[Continue]
     end
@@ -210,6 +211,7 @@ const session = await client.createSession({
     apiKey: process.env.AZURE_OPENAI_KEY,
     deploymentId: "my-gpt-deployment",
   },
+  onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // When resuming, you MUST re-provide the provider config
@@ -311,7 +313,7 @@ const repoSessions = await client.listSessions({ repository: "owner/repo" });
 async function cleanupExpiredSessions(maxAgeMs: number) {
   const sessions = await client.listSessions();
   const now = Date.now();
-  
+
   for (const session of sessions) {
     const age = now - new Date(session.createdAt).getTime();
     if (age > maxAgeMs) {
@@ -333,7 +335,7 @@ When a task completes, destroy the session explicitly rather than waiting for ti
 try {
   // Do work...
   await session.sendAndWait({ prompt: "Complete the task" });
-  
+
   // Task complete - clean up
   await session.destroy();
 } catch (error) {
@@ -408,11 +410,11 @@ async function resumeSessionWithAuth(
 ): Promise<Session> {
   // Parse user from session ID
   const [sessionUserId] = sessionId.split("-");
-  
+
   if (sessionUserId !== currentUserId) {
     throw new Error("Access denied: session belongs to another user");
   }
-  
+
   return client.resumeSession(sessionId);
 }
 ```
@@ -446,10 +448,10 @@ flowchart LR
     subgraph Before["Container A"]
         CLI1[CLI + Session X]
     end
-    
+
     CLI1 --> |persist| Azure[(☁️ Azure File Share)]
     Azure --> |restore| CLI2
-    
+
     subgraph After["Container B (restart)"]
         CLI2[CLI + Session X]
     end
@@ -469,6 +471,7 @@ const session = await client.createSession({
     backgroundCompactionThreshold: 0.80,  // Start compaction at 80% context
     bufferExhaustionThreshold: 0.95,      // Block at 95% if needed
   },
+  onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -499,11 +502,11 @@ async function withSessionLock<T>(
 ): Promise<T> {
   const lockKey = `session-lock:${sessionId}`;
   const acquired = await redis.set(lockKey, "locked", "NX", "EX", 300);
-  
+
   if (!acquired) {
     throw new Error("Session is in use by another client");
   }
-  
+
   try {
     return await fn();
   } finally {

docs/guides/setup/azure-managed-identity.md

@@ -145,6 +145,7 @@ const session = await client.createSession({
     bearerToken: tokenResponse.token,
     wireApi: "responses",
   },
+  onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 const response = await session.sendAndWait({ prompt: "Hello!" });

docs/guides/setup/backend-services.md

@@ -99,6 +99,7 @@ const client = new CopilotClient({
 const session = await client.createSession({
     sessionId: `user-${userId}-${Date.now()}`,
     model: "gpt-4.1",
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 const response = await session.sendAndWait({ prompt: req.body.message });
@@ -213,6 +214,7 @@ app.post("/chat", authMiddleware, async (req, res) => {
     const session = await client.createSession({
         sessionId: `user-${req.user.id}-chat`,
         model: "gpt-4.1",
+        onPermissionRequest: async () => ({ kind: "approved" }),
     });
 
     const response = await session.sendAndWait({
@@ -239,6 +241,7 @@ const session = await client.createSession({
         baseUrl: "https://api.openai.com/v1",
         apiKey: process.env.OPENAI_API_KEY,
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -285,6 +288,7 @@ app.post("/api/chat", async (req, res) => {
         session = await client.createSession({
             sessionId,
             model: "gpt-4.1",
+            onPermissionRequest: async () => ({ kind: "approved" }),
         });
     }
 
@@ -312,6 +316,7 @@ async function processJob(job: Job) {
     const session = await client.createSession({
         sessionId: `job-${job.id}`,
         model: "gpt-4.1",
+        onPermissionRequest: async () => ({ kind: "approved" }),
     });
 
     const response = await session.sendAndWait({

docs/guides/setup/bundled-cli.md

@@ -72,7 +72,7 @@ const client = new CopilotClient({
     cliPath: path.join(__dirname, "vendor", "copilot"),
 });
 
-const session = await client.createSession({ model: "gpt-4.1" });
+const session = await client.createSession({ model: "gpt-4.1" }, onPermissionRequest: async () => ({ kind: "approved" }),);
 const response = await session.sendAndWait({ prompt: "Hello!" });
 console.log(response?.data.content);
 
@@ -200,6 +200,7 @@ const session = await client.createSession({
         baseUrl: "https://api.openai.com/v1",
         apiKey: process.env.OPENAI_API_KEY,
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -219,6 +220,7 @@ const sessionId = `project-${projectName}`;
 const session = await client.createSession({
     sessionId,
     model: "gpt-4.1",
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // User closes app...

docs/guides/setup/byok.md

@@ -78,6 +78,7 @@ const session = await client.createSession({
         baseUrl: "https://api.openai.com/v1",
         apiKey: process.env.OPENAI_API_KEY,
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 const response = await session.sendAndWait({ prompt: "Hello!" });
@@ -255,6 +256,7 @@ app.post("/chat", authMiddleware, async (req, res) => {
             baseUrl: "https://api.openai.com/v1",
             apiKey: process.env.OPENAI_API_KEY,  // Your key, your billing
         },
+        onPermissionRequest: async () => ({ kind: "approved" }),
     });
 
     const response = await session.sendAndWait({ prompt: req.body.message });
@@ -303,6 +305,7 @@ async function createSessionForCustomer(customerId: string) {
             baseUrl: config.baseUrl,
             apiKey: config.apiKey,
         },
+        onPermissionRequest: async () => ({ kind: "approved" }),
     });
 }
 ```
@@ -321,6 +324,7 @@ const session = await client.createSession({
         baseUrl: "https://api.openai.com/v1",
         apiKey: process.env.OPENAI_API_KEY,
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // Resume later — must re-provide provider config

docs/guides/setup/github-oauth.md

@@ -134,6 +134,7 @@ const client = createClientForUser("gho_user_access_token");
 const session = await client.createSession({
     sessionId: `user-${userId}-session`,
     model: "gpt-4.1",
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 const response = await session.sendAndWait({ prompt: "Hello!" });