Add requiresApproval field to custom tools in Node.js and .NET SDKs

Co-authored-by: patniko <26906478+patniko@users.noreply.github.com>

Author: Copilot

dotnet/src/Client.cs

@@ -872,6 +872,41 @@ public async Task<ToolCallResponse> OnToolCall(string sessionId,
                 });
             }
 
+            // Check if tool requires approval
+            if (session.ToolRequiresApproval(toolName))
+            {
+                try
+                {
+                    var permissionResult = await session.HandlePermissionRequestAsync(
+                        JsonSerializer.SerializeToElement(new
+                        {
+                            kind = "tool",
+                            toolCallId,
+                            toolName
+                        }));
+
+                    if (permissionResult.Kind != "approved")
+                    {
+                        return new ToolCallResponse(new ToolResultObject
+                        {
+                            TextResultForLlm = permissionResult.Kind == "denied-interactively-by-user"
+                                ? "Tool execution was denied by user."
+                                : "Tool execution was denied.",
+                            ResultType = "denied"
+                        });
+                    }
+                }
+                catch
+                {
+                    // If permission handler fails or is not configured, deny the tool execution
+                    return new ToolCallResponse(new ToolResultObject
+                    {
+                        TextResultForLlm = "Tool execution requires permission but no permission handler is configured.",
+                        ResultType = "denied"
+                    });
+                }
+            }
+
             try
             {
                 var invocation = new ToolInvocation

dotnet/src/Session.cs

@@ -45,6 +45,7 @@ public partial class CopilotSession : IAsyncDisposable
 {
     private readonly HashSet<SessionEventHandler> _eventHandlers = new();
     private readonly Dictionary<string, AIFunction> _toolHandlers = new();
+    private readonly Dictionary<string, bool> _toolRequiresApproval = new();
     private readonly JsonRpc _rpc;
     private PermissionHandler? _permissionHandler;
     private readonly SemaphoreSlim _permissionHandlerLock = new(1, 1);
@@ -255,12 +256,36 @@ internal void DispatchEvent(SessionEvent sessionEvent)
     /// Tools allow the assistant to execute custom functions. When the assistant invokes a tool,
     /// the corresponding handler is called with the tool arguments.
     /// </remarks>
-    internal void RegisterTools(ICollection<AIFunction> tools)
+    internal void RegisterTools(ICollection<AIFunction>? tools)
     {
         _toolHandlers.Clear();
+        _toolRequiresApproval.Clear();
+        if (tools == null) return;
+        
         foreach (var tool in tools)
         {
             _toolHandlers.Add(tool.Name, tool);
+            _toolRequiresApproval[tool.Name] = false;
+        }
+    }
+
+    /// <summary>
+    /// Registers custom tool handlers for this session with requiresApproval support.
+    /// </summary>
+    /// <param name="tools">A collection of CopilotTools that can be invoked by the assistant.</param>
+    /// <remarks>
+    /// Tools allow the assistant to execute custom functions. When the assistant invokes a tool,
+    /// the corresponding handler is called with the tool arguments.
+    /// CopilotTools support the RequiresApproval flag for permission handling.
+    /// </remarks>
+    internal void RegisterTools(ICollection<CopilotTool> tools)
+    {
+        _toolHandlers.Clear();
+        _toolRequiresApproval.Clear();
+        foreach (var tool in tools)
+        {
+            _toolHandlers.Add(tool.Function.Name, tool.Function);
+            _toolRequiresApproval[tool.Function.Name] = tool.RequiresApproval;
         }
     }
 
@@ -272,6 +297,14 @@ internal void RegisterTools(ICollection<AIFunction> tools)
     internal AIFunction? GetTool(string name) =>
         _toolHandlers.TryGetValue(name, out var tool) ? tool : null;
 
+    /// <summary>
+    /// Checks if a tool requires approval before execution.
+    /// </summary>
+    /// <param name="name">The name of the tool to check.</param>
+    /// <returns>True if the tool requires approval, false otherwise.</returns>
+    internal bool ToolRequiresApproval(string name) =>
+        _toolRequiresApproval.TryGetValue(name, out var requiresApproval) && requiresApproval;
+
     /// <summary>
     /// Registers a handler for permission requests.
     /// </summary>

dotnet/src/Types.cs

@@ -83,6 +83,33 @@ public class ToolInvocation
 
 public delegate Task<object?> ToolHandler(ToolInvocation invocation);
 
+/// <summary>
+/// Wraps an AIFunction with additional metadata for the Copilot SDK.
+/// </summary>
+public class CopilotTool
+{
+    /// <summary>
+    /// The underlying AIFunction that handles tool execution.
+    /// </summary>
+    public AIFunction Function { get; set; } = null!;
+
+    /// <summary>
+    /// Controls whether the tool requires user approval before execution.
+    /// When true, the OnPermissionRequest handler will be called before invoking the tool.
+    /// When false or not specified, the tool executes without requesting permission.
+    /// </summary>
+    public bool RequiresApproval { get; set; }
+
+    /// <summary>
+    /// Creates a CopilotTool from an AIFunction with optional requiresApproval flag.
+    /// </summary>
+    /// <param name="function">The AIFunction to wrap.</param>
+    /// <param name="requiresApproval">Whether the tool requires approval before execution.</param>
+    /// <returns>A CopilotTool wrapping the provided function.</returns>
+    public static implicit operator CopilotTool(AIFunction function) =>
+        new() { Function = function, RequiresApproval = false };
+}
+
 public class PermissionRequest
 {
     [JsonPropertyName("kind")]

nodejs/src/client.ts

@@ -985,6 +985,36 @@ export class CopilotClient {
             return { result: this.buildUnsupportedToolResult(params.toolName) };
         }
 
+        // Check if tool requires approval
+        if (session.toolRequiresApprovalCheck(params.toolName)) {
+            try {
+                const permissionResult = await session._handlePermissionRequest({
+                    kind: "tool",
+                    toolCallId: params.toolCallId,
+                    toolName: params.toolName,
+                });
+
+                if (permissionResult.kind !== "approved") {
+                    return {
+                        result: {
+                            textResultForLlm: `Tool execution was ${permissionResult.kind === "denied-interactively-by-user" ? "denied by user" : "denied"}.`,
+                            resultType: "denied",
+                            toolTelemetry: {},
+                        },
+                    };
+                }
+            } catch (error) {
+                // If permission handler fails or is not configured, deny the tool execution
+                return {
+                    result: {
+                        textResultForLlm: "Tool execution requires permission but no permission handler is configured.",
+                        resultType: "denied",
+                        toolTelemetry: {},
+                    },
+                };
+            }
+        }
+
         return await this.executeToolCall(handler, params);
     }
 

nodejs/src/session.ts

@@ -50,6 +50,7 @@ export type AssistantMessageEvent = Extract<SessionEvent, { type: "assistant.mes
 export class CopilotSession {
     private eventHandlers: Set<SessionEventHandler> = new Set();
     private toolHandlers: Map<string, ToolHandler> = new Map();
+    private toolRequiresApproval: Map<string, boolean> = new Map();
     private permissionHandler?: PermissionHandler;
 
     /**
@@ -238,12 +239,14 @@ export class CopilotSession {
      */
     registerTools(tools?: Tool[]): void {
         this.toolHandlers.clear();
+        this.toolRequiresApproval.clear();
         if (!tools) {
             return;
         }
 
         for (const tool of tools) {
             this.toolHandlers.set(tool.name, tool.handler);
+            this.toolRequiresApproval.set(tool.name, tool.requiresApproval ?? false);
         }
     }
 
@@ -258,6 +261,17 @@ export class CopilotSession {
         return this.toolHandlers.get(name);
     }
 
+    /**
+     * Checks if a tool requires approval before execution.
+     *
+     * @param name - The name of the tool to check
+     * @returns True if the tool requires approval, false otherwise
+     * @internal This method is for internal use by the SDK.
+     */
+    toolRequiresApprovalCheck(name: string): boolean {
+        return this.toolRequiresApproval.get(name) ?? false;
+    }
+
     /**
      * Registers a handler for permission requests.
      *

nodejs/src/types.ts

@@ -131,6 +131,13 @@ export interface Tool<TArgs = unknown> {
     description?: string;
     parameters?: ZodSchema<TArgs> | Record<string, unknown>;
     handler: ToolHandler<TArgs>;
+    /**
+     * Controls whether the tool requires user approval before execution.
+     * When true, the OnPermissionRequest handler will be called before invoking the tool.
+     * When false or undefined, the tool executes without requesting permission.
+     * @default false
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -143,6 +150,13 @@ export function defineTool<T = unknown>(
         description?: string;
         parameters?: ZodSchema<T> | Record<string, unknown>;
         handler: ToolHandler<T>;
+        /**
+         * Controls whether the tool requires user approval before execution.
+         * When true, the OnPermissionRequest handler will be called before invoking the tool.
+         * When false or undefined, the tool executes without requesting permission.
+         * @default false
+         */
+        requiresApproval?: boolean;
     }
 ): Tool<T> {
     return { name, ...config };
@@ -196,8 +210,9 @@ export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageRepla
  * Permission request types from the server
  */
 export interface PermissionRequest {
-    kind: "shell" | "write" | "mcp" | "read" | "url";
+    kind: "shell" | "write" | "mcp" | "read" | "url" | "tool";
     toolCallId?: string;
+    toolName?: string;
     [key: string]: unknown;
 }