Allow tools to set skipPermission

Author: MRayermannMSFT

dotnet/README.md

@@ -449,6 +449,24 @@ var session = await client.CreateSessionAsync(new SessionConfig
 });
 ```
 
+#### Skipping Permission Prompts
+
+Set `skip_permission` in the tool's `AdditionalProperties` to allow it to execute without triggering a permission prompt:
+
+```csharp
+var safeLookup = AIFunctionFactory.Create(
+    async ([Description("Lookup ID")] string id) => {
+        // your logic
+    },
+    "safe_lookup",
+    "A read-only lookup that needs no confirmation",
+    new AIFunctionFactoryOptions
+    {
+        AdditionalProperties = new ReadOnlyDictionary<string, object?>(
+            new Dictionary<string, object?> { ["skip_permission"] = true })
+    });
+```
+
 ### System Message Customization
 
 Control the system prompt using `SystemMessage` in session config:

dotnet/src/Client.cs

@@ -1470,13 +1470,16 @@ internal record ToolDefinition(
         string Name,
         string? Description,
         JsonElement Parameters, /* JSON schema */
-        bool? OverridesBuiltInTool = null)
+        bool? OverridesBuiltInTool = null,
+        bool? SkipPermission = null)
     {
         public static ToolDefinition FromAIFunction(AIFunction function)
         {
             var overrides = function.AdditionalProperties.TryGetValue("is_override", out var val) && val is true;
+            var skipPerm = function.AdditionalProperties.TryGetValue("skip_permission", out var skipVal) && skipVal is true;
             return new ToolDefinition(function.Name, function.Description, function.JsonSchema,
-                overrides ? true : null);
+                overrides ? true : null,
+                skipPerm ? true : null);
         }
     }
 

go/README.md

@@ -281,6 +281,18 @@ editFile := copilot.DefineTool("edit_file", "Custom file editor with project-spe
 editFile.OverridesBuiltInTool = true
 ```
 
+#### Skipping Permission Prompts
+
+Set `SkipPermission = true` on a tool to allow it to execute without triggering a permission prompt:
+
+```go
+safeLookup := copilot.DefineTool("safe_lookup", "A read-only lookup that needs no confirmation",
+    func(params LookupParams, inv copilot.ToolInvocation) (any, error) {
+        // your logic
+    })
+safeLookup.SkipPermission = true
+```
+
 ## Streaming
 
 Enable streaming to receive assistant response chunks as they're generated:

go/client_test.go

@@ -509,6 +509,47 @@ func TestOverridesBuiltInTool(t *testing.T) {
 	})
 }
 
+func TestSkipPermission(t *testing.T) {
+	t.Run("SkipPermission is serialized in tool definition", func(t *testing.T) {
+		tool := Tool{
+			Name:           "my_tool",
+			Description:    "A tool that skips permission",
+			SkipPermission: true,
+			Handler:        func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		if v, ok := m["skipPermission"]; !ok || v != true {
+			t.Errorf("expected skipPermission=true, got %v", m)
+		}
+	})
+
+	t.Run("SkipPermission omitted when false", func(t *testing.T) {
+		tool := Tool{
+			Name:        "custom_tool",
+			Description: "A custom tool",
+			Handler:     func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		if _, ok := m["skipPermission"]; ok {
+			t.Errorf("expected skipPermission to be omitted, got %v", m)
+		}
+	})
+}
+
 func TestClient_CreateSession_RequiresPermissionHandler(t *testing.T) {
 	t.Run("returns error when config is nil", func(t *testing.T) {
 		client := NewClient(nil)

go/types.go

@@ -414,6 +414,7 @@ type Tool struct {
 	Description          string         `json:"description,omitempty"`
 	Parameters           map[string]any `json:"parameters,omitempty"`
 	OverridesBuiltInTool bool           `json:"overridesBuiltInTool,omitempty"`
+	SkipPermission       bool           `json:"skipPermission,omitempty"`
 	Handler              ToolHandler    `json:"-"`
 }
 

nodejs/README.md

@@ -426,6 +426,19 @@ defineTool("edit_file", {
 })
 ```
 
+#### Skipping Permission Prompts
+
+Set `skipPermission: true` on a tool definition to allow it to execute without triggering a permission prompt:
+
+```ts
+defineTool("safe_lookup", {
+    description: "A read-only lookup that needs no confirmation",
+    parameters: z.object({ id: z.string() }),
+    skipPermission: true,
+    handler: async ({ id }) => { /* your logic */ },
+})
+```
+
 ### System Message Customization
 
 Control the system prompt using `systemMessage` in session config:

nodejs/src/client.ts

@@ -580,6 +580,7 @@ export class CopilotClient {
                     description: tool.description,
                     parameters: toJsonSchema(tool.parameters),
                     overridesBuiltInTool: tool.overridesBuiltInTool,
+                    skipPermission: tool.skipPermission,
                 })),
                 systemMessage: config.systemMessage,
                 availableTools: config.availableTools,
@@ -682,6 +683,7 @@ export class CopilotClient {
                     description: tool.description,
                     parameters: toJsonSchema(tool.parameters),
                     overridesBuiltInTool: tool.overridesBuiltInTool,
+                    skipPermission: tool.skipPermission,
                 })),
                 provider: config.provider,
                 requestPermission: true,

nodejs/src/types.ts

@@ -167,6 +167,10 @@ export interface Tool<TArgs = unknown> {
      * will return an error.
      */
     overridesBuiltInTool?: boolean;
+    /**
+     * When true, the tool can execute without a permission prompt.
+     */
+    skipPermission?: boolean;
 }
 
 /**
@@ -180,6 +184,7 @@ export function defineTool<T = unknown>(
         parameters?: ZodSchema<T> | Record<string, unknown>;
         handler: ToolHandler<T>;
         overridesBuiltInTool?: boolean;
+        skipPermission?: boolean;
     }
 ): Tool<T> {
     return { name, ...config };

nodejs/test/client.test.ts

@@ -378,6 +378,64 @@ describe("CopilotClient", () => {
         });
     });
 
+    describe("skipPermission in tool definitions", () => {
+        it("sends skipPermission in tool definition on session.create", async () => {
+            const client = new CopilotClient();
+            await client.start();
+            onTestFinished(() => client.forceStop());
+
+            const spy = vi.spyOn((client as any).connection!, "sendRequest");
+            await client.createSession({
+                onPermissionRequest: approveAll,
+                tools: [
+                    {
+                        name: "my_tool",
+                        description: "a tool that skips permission",
+                        handler: async () => "ok",
+                        skipPermission: true,
+                    },
+                ],
+            });
+
+            const payload = spy.mock.calls.find((c) => c[0] === "session.create")![1] as any;
+            expect(payload.tools).toEqual([
+                expect.objectContaining({ name: "my_tool", skipPermission: true }),
+            ]);
+        });
+
+        it("sends skipPermission in tool definition on session.resume", async () => {
+            const client = new CopilotClient();
+            await client.start();
+            onTestFinished(() => client.forceStop());
+
+            const session = await client.createSession({ onPermissionRequest: approveAll });
+            // Mock sendRequest to capture the call without hitting the runtime
+            const spy = vi
+                .spyOn((client as any).connection!, "sendRequest")
+                .mockImplementation(async (method: string, params: any) => {
+                    if (method === "session.resume") return { sessionId: params.sessionId };
+                    throw new Error(`Unexpected method: ${method}`);
+                });
+            await client.resumeSession(session.sessionId, {
+                onPermissionRequest: approveAll,
+                tools: [
+                    {
+                        name: "my_tool",
+                        description: "a tool that skips permission",
+                        handler: async () => "ok",
+                        skipPermission: true,
+                    },
+                ],
+            });
+
+            const payload = spy.mock.calls.find((c) => c[0] === "session.resume")![1] as any;
+            expect(payload.tools).toEqual([
+                expect.objectContaining({ name: "my_tool", skipPermission: true }),
+            ]);
+            spy.mockRestore();
+        });
+    });
+
     describe("agent parameter in session creation", () => {
         it("forwards agent in session.create request", async () => {
             const client = new CopilotClient();

python/README.md

@@ -232,6 +232,16 @@ async def edit_file(params: EditFileParams) -> str:
     # your logic
 ```
 
+#### Skipping Permission Prompts
+
+Set `skip_permission=True` on a tool definition to allow it to execute without triggering a permission prompt:
+
+```python
+@define_tool(name="safe_lookup", description="A read-only lookup that needs no confirmation", skip_permission=True)
+async def safe_lookup(params: LookupParams) -> str:
+    # your logic
+```
+
 ## Image Support
 
 The SDK supports image attachments via the `attachments` parameter. You can attach images by providing their file path: