feat!: default-deny permissions across all SDK languages

Previously, the SDKs only set requestPermission=true in the JSON-RPC
session.create/session.resume calls when an onPermissionRequest handler
was provided. When no handler was registered, requestPermission was
omitted/false, allowing the CLI to handle permissions itself (permissive
default).

This change makes requestPermission always true so that all permission
requests are routed through the SDK. The SDK's existing deny-by-default
behavior (returning 'denied-no-approval-rule-and-could-not-request-from-user'
when no handler is registered) now takes effect for all sessions.

BREAKING CHANGE: Apps that do not provide an onPermissionRequest handler
will now have all privileged tool operations (file writes, shell commands,
URL fetches, MCP calls) denied by default. Register a handler to approve
operations:

  Node.js:
    onPermissionRequest: async (request) => ({ kind: 'approved' })

  Python:
    'on_permission_request': lambda req, inv: {'kind': 'approved'}

  Go:
    OnPermissionRequest: func(r PermissionRequest, i PermissionInvocation) (PermissionRequestResult, error) {
        return PermissionRequestResult{Kind: 'approved'}, nil
    }

  .NET:
    OnPermissionRequest = (req, inv) => Task.FromResult(new PermissionRequestResult { Kind = 'approved' })

Changes:
- nodejs/src/client.ts: always send requestPermission:true
- python/copilot/client.py: always set requestPermission=True
- go/client.go: always set RequestPermission=true
- dotnet/src/Client.cs: always pass true for RequestPermission
- All samples updated to include onPermissionRequest approve-all handler
- All language READMEs updated with Permission Requests documentation section
- docs/compatibility.md: fix incorrect PermissionRequestResult format and
  add default-deny description
- go/types.go: update OnPermissionRequest doc comment

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

docs/compatibility.md

@@ -124,19 +124,21 @@ The `--share` option is not available via SDK. Workarounds:
 
 ### Permission Control
 
+The SDK uses a **deny-by-default** permission model. All permission requests (file writes, shell commands, URL fetches, etc.) are denied unless your app provides an `onPermissionRequest` handler.
+
 Instead of `--allow-all-paths` or `--yolo`, use the permission handler:
 
 ```typescript
 const session = await client.createSession({
   onPermissionRequest: async (request) => {
     // Auto-approve everything (equivalent to --yolo)
-    return { approved: true };
+    return { kind: "approved" };
 
     // Or implement custom logic
-    if (request.kind === "shell") {
-      return { approved: request.command.startsWith("git") };
-    }
-    return { approved: true };
+    // if (request.kind === "shell") {
+    //   return { kind: "denied-interactively-by-user" };
+    // }
+    // return { kind: "approved" };
   },
 });
 ```

dotnet/README.md

@@ -495,6 +495,43 @@ var session = await client.CreateSessionAsync(new SessionConfig
 });
 ```
 
+## Permission Requests
+
+The SDK uses a **deny-by-default** permission model. When the Copilot agent needs to perform privileged operations (file writes, shell commands, URL fetches, etc.), it sends a permission request to the SDK. If no `OnPermissionRequest` handler is registered, all such requests are **automatically denied**.
+
+To allow operations, provide an `OnPermissionRequest` handler when creating a session:
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    OnPermissionRequest = async (request, invocation) =>
+    {
+        // request.Kind - The type of operation: "shell", "write", "read", "url", or "mcp"
+
+        // Approve everything (equivalent to --yolo mode in the CLI)
+        return new PermissionRequestResult { Kind = "approved" };
+
+        // Or implement fine-grained policy:
+        // if (request.Kind == "shell")
+        //     return new PermissionRequestResult { Kind = "denied-interactively-by-user" };
+        // return new PermissionRequestResult { Kind = "approved" };
+    }
+});
+```
+
+**Permission request kinds:**
+- `"shell"` — Execute a shell command
+- `"write"` — Write to a file
+- `"read"` — Read a file
+- `"url"` — Fetch a URL
+- `"mcp"` — Call an MCP server tool
+
+**Permission result kinds:**
+- `"approved"` — Allow the operation
+- `"denied-interactively-by-user"` — User explicitly denied
+- `"denied-by-rules"` — Denied by policy rules
+- `"denied-no-approval-rule-and-could-not-request-from-user"` — Default deny (no handler)
+
 ## User Input Requests
 
 Enable the agent to ask questions to the user using the `ask_user` tool by providing an `OnUserInputRequest` handler:

dotnet/samples/Chat.cs

@@ -1,7 +1,15 @@
 using GitHub.Copilot.SDK;
 
 await using var client = new CopilotClient();
-await using var session = await client.CreateSessionAsync();
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+    // Permission requests are denied by default. Provide a handler to approve operations.
+    OnPermissionRequest = (request, invocation) =>
+    {
+        // Approve all permission requests. Customize this to implement your own policy.
+        return Task.FromResult(new PermissionRequestResult { Kind = "approved" });
+    }
+});
 
 using var _ = session.On(evt =>
 {

dotnet/src/Client.cs

@@ -377,7 +377,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig? config = nul
             config?.AvailableTools,
             config?.ExcludedTools,
             config?.Provider,
-            config?.OnPermissionRequest != null ? true : null,
+            (bool?)true,
             config?.OnUserInputRequest != null ? true : null,
             hasHooks ? true : null,
             config?.WorkingDirectory,
@@ -461,7 +461,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             config?.AvailableTools,
             config?.ExcludedTools,
             config?.Provider,
-            config?.OnPermissionRequest != null ? true : null,
+            (bool?)true,
             config?.OnUserInputRequest != null ? true : null,
             hasHooks ? true : null,
             config?.WorkingDirectory,

go/README.md

@@ -445,6 +445,42 @@ session, err := client.CreateSession(context.Background(), &copilot.SessionConfi
 > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `Type: "azure"`, not `Type: "openai"`.
 > - The `BaseURL` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically.
 
+## Permission Requests
+
+The SDK uses a **deny-by-default** permission model. When the Copilot agent needs to perform privileged operations (file writes, shell commands, URL fetches, etc.), it sends a permission request to the SDK. If no `OnPermissionRequest` handler is registered, all such requests are **automatically denied**.
+
+To allow operations, provide an `OnPermissionRequest` handler when creating a session:
+
+```go
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+    OnPermissionRequest: func(request copilot.PermissionRequest, invocation copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+        // request.Kind - The type of operation: "shell", "write", "read", "url", or "mcp"
+
+        // Approve everything (equivalent to --yolo mode in the CLI)
+        return copilot.PermissionRequestResult{Kind: "approved"}, nil
+
+        // Or implement fine-grained policy:
+        // if request.Kind == "shell" {
+        //     return copilot.PermissionRequestResult{Kind: "denied-interactively-by-user"}, nil
+        // }
+        // return copilot.PermissionRequestResult{Kind: "approved"}, nil
+    },
+})
+```
+
+**Permission request kinds:**
+- `"shell"` — Execute a shell command
+- `"write"` — Write to a file
+- `"read"` — Read a file
+- `"url"` — Fetch a URL
+- `"mcp"` — Call an MCP server tool
+
+**Permission result kinds:**
+- `"approved"` — Allow the operation
+- `"denied-interactively-by-user"` — User explicitly denied
+- `"denied-by-rules"` — Denied by policy rules
+- `"denied-no-approval-rule-and-could-not-request-from-user"` — Default deny (no handler)
+
 ## User Input Requests
 
 Enable the agent to ask questions to the user using the `ask_user` tool by providing an `OnUserInputRequest` handler:

go/client.go

@@ -473,9 +473,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 		if config.Streaming {
 			req.Streaming = Bool(true)
 		}
-		if config.OnPermissionRequest != nil {
-			req.RequestPermission = Bool(true)
-		}
+		req.RequestPermission = Bool(true)
 		if config.OnUserInputRequest != nil {
 			req.RequestUserInput = Bool(true)
 		}
@@ -562,9 +560,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 		if config.Streaming {
 			req.Streaming = Bool(true)
 		}
-		if config.OnPermissionRequest != nil {
-			req.RequestPermission = Bool(true)
-		}
+		req.RequestPermission = Bool(true)
 		if config.OnUserInputRequest != nil {
 			req.RequestUserInput = Bool(true)
 		}

go/samples/chat.go

@@ -23,7 +23,14 @@ func main() {
 	}
 	defer client.Stop()
 
-	session, err := client.CreateSession(ctx, nil)
+	session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+		CLIPath: cliPath,
+		// Permission requests are denied by default. Provide a handler to approve operations.
+		OnPermissionRequest: func(_ copilot.PermissionRequest, _ copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+			// Approve all permission requests. Customize this to implement your own policy.
+			return copilot.PermissionRequestResult{Kind: "approved"}, nil
+		},
+	})
 	if err != nil {
 		panic(err)
 	}

go/types.go

@@ -349,7 +349,9 @@ type SessionConfig struct {
 	// ExcludedTools is a list of tool names to disable. All other tools remain available.
 	// Ignored if AvailableTools is specified.
 	ExcludedTools []string
-	// OnPermissionRequest is a handler for permission requests from the server
+	// OnPermissionRequest is a handler for permission requests from the server.
+	// If nil, all permission requests are denied by default.
+	// Provide a handler to approve operations (file writes, shell commands, URL fetches, etc.).
 	OnPermissionRequest PermissionHandler
 	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
 	OnUserInputRequest UserInputHandler
@@ -426,7 +428,9 @@ type ResumeSessionConfig struct {
 	// ReasoningEffort level for models that support it.
 	// Valid values: "low", "medium", "high", "xhigh"
 	ReasoningEffort string
-	// OnPermissionRequest is a handler for permission requests from the server
+	// OnPermissionRequest is a handler for permission requests from the server.
+	// If nil, all permission requests are denied by default.
+	// Provide a handler to approve operations (file writes, shell commands, URL fetches, etc.).
 	OnPermissionRequest PermissionHandler
 	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
 	OnUserInputRequest UserInputHandler

nodejs/README.md

@@ -565,6 +565,42 @@ const session = await client.createSession({
 > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `type: "azure"`, not `type: "openai"`.
 > - The `baseUrl` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically.
 
+## Permission Requests
+
+The SDK uses a **deny-by-default** permission model. When the Copilot agent needs to perform privileged operations (file writes, shell commands, URL fetches, etc.), it sends a permission request to the SDK. If no `onPermissionRequest` handler is registered, all such requests are **automatically denied**.
+
+To allow operations, provide an `onPermissionRequest` handler when creating a session:
+
+```typescript
+const session = await client.createSession({
+    onPermissionRequest: async (request, invocation) => {
+        // request.kind - The type of operation: "shell" | "write" | "read" | "url" | "mcp"
+
+        // Approve everything (equivalent to --yolo mode in the CLI)
+        return { kind: "approved" };
+
+        // Or implement fine-grained policy:
+        // if (request.kind === "shell") {
+        //     return { kind: "denied-interactively-by-user" };
+        // }
+        // return { kind: "approved" };
+    },
+});
+```
+
+**Permission request kinds:**
+- `"shell"` — Execute a shell command
+- `"write"` — Write to a file
+- `"read"` — Read a file
+- `"url"` — Fetch a URL
+- `"mcp"` — Call an MCP server tool
+
+**Permission result kinds:**
+- `"approved"` — Allow the operation
+- `"denied-interactively-by-user"` — User explicitly denied
+- `"denied-by-rules"` — Denied by policy rules
+- `"denied-no-approval-rule-and-could-not-request-from-user"` — Default deny (no handler)
+
 ## User Input Requests
 
 Enable the agent to ask questions to the user using the `ask_user` tool by providing an `onUserInputRequest` handler:

nodejs/samples/chat.ts

@@ -3,7 +3,13 @@ import { CopilotClient, type SessionEvent } from "@github/copilot-sdk";
 
 async function main() {
     const client = new CopilotClient();
-    const session = await client.createSession();
+    const session = await client.createSession({
+        // Permission requests are denied by default. Provide a handler to approve operations.
+        onPermissionRequest: async (_request) => {
+            // Approve all permission requests. Customize this to implement your own policy.
+            return { kind: "approved" };
+        },
+    });
 
     session.on((event: SessionEvent) => {
         let output: string | null = null;