Add requiresApproval field to custom tools in Python and Go SDKs

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

Author: Copilot

go/client.go

@@ -1180,6 +1180,35 @@ func (c *Client) handleToolCallRequest(params map[string]interface{}) (map[strin
 		return map[string]interface{}{"result": buildUnsupportedToolResult(toolName)}, nil
 	}
 
+	// Check if tool requires approval
+	if session.toolRequiresApprovalCheck(toolName) {
+		permissionRequest := map[string]interface{}{
+			"kind":       "tool",
+			"toolCallId": toolCallID,
+			"toolName":   toolName,
+		}
+
+		permissionResult, err := session.handlePermissionRequest(permissionRequest)
+		if err != nil || permissionResult.Kind != "approved" {
+			deniedReason := "denied"
+			if err == nil {
+				deniedReason = permissionResult.Kind
+			}
+			return map[string]interface{}{
+				"result": ToolResult{
+					TextResultForLLM: func() string {
+						if deniedReason == "denied-interactively-by-user" {
+							return "Tool execution was denied by user."
+						}
+						return "Tool execution was denied."
+					}(),
+					ResultType:    "denied",
+					ToolTelemetry: map[string]interface{}{},
+				},
+			}, nil
+		}
+	}
+
 	arguments := params["arguments"]
 	result := c.executeToolCall(sessionID, toolCallID, toolName, arguments, handler)
 

go/session.go

@@ -46,16 +46,17 @@ type sessionHandler struct {
 //	})
 type Session struct {
 	// SessionID is the unique identifier for this session.
-	SessionID         string
-	workspacePath     string
-	client            *JSONRPCClient
-	handlers          []sessionHandler
-	nextHandlerID     uint64
-	handlerMutex      sync.RWMutex
-	toolHandlers      map[string]ToolHandler
-	toolHandlersM     sync.RWMutex
-	permissionHandler PermissionHandler
-	permissionMux     sync.RWMutex
+	SessionID           string
+	workspacePath       string
+	client              *JSONRPCClient
+	handlers            []sessionHandler
+	nextHandlerID       uint64
+	handlerMutex        sync.RWMutex
+	toolHandlers        map[string]ToolHandler
+	toolRequiresApproval map[string]bool
+	toolHandlersM       sync.RWMutex
+	permissionHandler   PermissionHandler
+	permissionMux       sync.RWMutex
 }
 
 // WorkspacePath returns the path to the session workspace directory when infinite
@@ -71,11 +72,12 @@ func (s *Session) WorkspacePath() string {
 // to create sessions with proper initialization.
 func NewSession(sessionID string, client *JSONRPCClient, workspacePath string) *Session {
 	return &Session{
-		SessionID:     sessionID,
-		workspacePath: workspacePath,
-		client:        client,
-		handlers:      make([]sessionHandler, 0),
-		toolHandlers:  make(map[string]ToolHandler),
+		SessionID:            sessionID,
+		workspacePath:        workspacePath,
+		client:               client,
+		handlers:             make([]sessionHandler, 0),
+		toolHandlers:         make(map[string]ToolHandler),
+		toolRequiresApproval: make(map[string]bool),
 	}
 }
 
@@ -262,11 +264,13 @@ func (s *Session) registerTools(tools []Tool) {
 	defer s.toolHandlersM.Unlock()
 
 	s.toolHandlers = make(map[string]ToolHandler)
+	s.toolRequiresApproval = make(map[string]bool)
 	for _, tool := range tools {
 		if tool.Name == "" || tool.Handler == nil {
 			continue
 		}
 		s.toolHandlers[tool.Name] = tool.Handler
+		s.toolRequiresApproval[tool.Name] = tool.RequiresApproval
 	}
 }
 
@@ -279,6 +283,15 @@ func (s *Session) getToolHandler(name string) (ToolHandler, bool) {
 	return handler, ok
 }
 
+// toolRequiresApprovalCheck checks if a tool requires approval before execution.
+// Returns true if the tool requires approval, false otherwise.
+func (s *Session) toolRequiresApprovalCheck(name string) bool {
+	s.toolHandlersM.RLock()
+	defer s.toolHandlersM.RUnlock()
+	requiresApproval, ok := s.toolRequiresApproval[name]
+	return ok && requiresApproval
+}
+
 // registerPermissionHandler registers a permission handler for this session.
 //
 // When the assistant needs permission to perform certain actions (e.g., file

go/types.go

@@ -78,6 +78,7 @@ type SystemMessageConfig struct {
 type PermissionRequest struct {
 	Kind       string                 `json:"kind"`
 	ToolCallID string                 `json:"toolCallId,omitempty"`
+	ToolName   string                 `json:"toolName,omitempty"`
 	Extra      map[string]interface{} `json:"-"` // Additional fields vary by kind
 }
 
@@ -198,6 +199,10 @@ type Tool struct {
 	Description string // optional
 	Parameters  map[string]interface{}
 	Handler     ToolHandler
+	// RequiresApproval controls whether the tool requires user approval before execution.
+	// When true, the OnPermissionRequest handler will be called before invoking the tool.
+	// When false (default), the tool executes without requesting permission.
+	RequiresApproval bool
 }
 
 // ToolInvocation describes a tool call initiated by Copilot

python/copilot/client.py

@@ -1054,6 +1054,38 @@ async def _handle_tool_call_request(self, params: dict) -> dict:
         if not handler:
             return {"result": self._build_unsupported_tool_result(tool_name)}
 
+        # Check if tool requires approval
+        if session._tool_requires_approval(tool_name):
+            try:
+                permission_result = await session._handle_permission_request(
+                    {
+                        "kind": "tool",
+                        "toolCallId": tool_call_id,
+                        "toolName": tool_name,
+                    }
+                )
+
+                if permission_result.get("kind") != "approved":
+                    denied_reason = permission_result.get("kind", "denied")
+                    return {
+                        "result": {
+                            "textResultForLlm": "Tool execution was denied by user."
+                            if denied_reason == "denied-interactively-by-user"
+                            else "Tool execution was denied.",
+                            "resultType": "denied",
+                            "toolTelemetry": {},
+                        }
+                    }
+            except Exception:  # pylint: disable=broad-except
+                # 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": {},
+                    }
+                }
+
         arguments = params.get("arguments")
         result = await self._execute_tool_call(
             session_id,

python/copilot/session.py

@@ -68,6 +68,7 @@ def __init__(self, session_id: str, client: Any, workspace_path: Optional[str] =
         self._event_handlers: set[Callable[[SessionEvent], None]] = set()
         self._event_handlers_lock = threading.Lock()
         self._tool_handlers: dict[str, ToolHandler] = {}
+        self._tool_requires_approval: dict[str, bool] = {}
         self._tool_handlers_lock = threading.Lock()
         self._permission_handler: Optional[PermissionHandler] = None
         self._permission_handler_lock = threading.Lock()
@@ -250,12 +251,14 @@ def _register_tools(self, tools: Optional[list[Tool]]) -> None:
         """
         with self._tool_handlers_lock:
             self._tool_handlers.clear()
+            self._tool_requires_approval.clear()
             if not tools:
                 return
             for tool in tools:
                 if not tool.name or not tool.handler:
                     continue
                 self._tool_handlers[tool.name] = tool.handler
+                self._tool_requires_approval[tool.name] = tool.requires_approval
 
     def _get_tool_handler(self, name: str) -> Optional[ToolHandler]:
         """
@@ -274,6 +277,22 @@ def _get_tool_handler(self, name: str) -> Optional[ToolHandler]:
         with self._tool_handlers_lock:
             return self._tool_handlers.get(name)
 
+    def _tool_requires_approval(self, name: str) -> bool:
+        """
+        Check if a tool requires approval before execution.
+
+        Note:
+            This method is internal and should not be called directly.
+
+        Args:
+            name: The name of the tool to check.
+
+        Returns:
+            True if the tool requires approval, False otherwise.
+        """
+        with self._tool_handlers_lock:
+            return self._tool_requires_approval.get(name, False)
+
     def _register_permission_handler(self, handler: Optional[PermissionHandler]) -> None:
         """
         Register a handler for permission requests.

python/copilot/tools.py

@@ -43,6 +43,7 @@ def define_tool(
     description: str | None = None,
     handler: Callable[[Any, ToolInvocation], Any] | None = None,
     params_type: type[BaseModel] | None = None,
+    requires_approval: bool = False,
 ) -> Tool | Callable[[Callable[[Any, ToolInvocation], Any]], Tool]:
     """
     Define a tool with automatic JSON schema generation from Pydantic models.
@@ -56,7 +57,7 @@ def define_tool(
         class LookupIssueParams(BaseModel):
             id: str = Field(description="Issue identifier")
 
-        @define_tool(description="Fetch issue details")
+        @define_tool(description="Fetch issue details", requires_approval=True)
         def lookup_issue(params: LookupIssueParams) -> str:
             return fetch_issue(params.id).summary
 
@@ -66,7 +67,8 @@ def lookup_issue(params: LookupIssueParams) -> str:
             "lookup_issue",
             description="Fetch issue details",
             handler=lambda params, inv: fetch_issue(params.id).summary,
-            params_type=LookupIssueParams
+            params_type=LookupIssueParams,
+            requires_approval=True
         )
 
     Args:
@@ -75,6 +77,9 @@ def lookup_issue(params: LookupIssueParams) -> str:
         handler: Optional handler function (if not using as decorator)
         params_type: Optional Pydantic model type for parameters (inferred from
                     type hints when using as decorator)
+        requires_approval: Whether the tool requires user approval before execution.
+                          When True, the on_permission_request handler will be called
+                          before invoking the tool. Defaults to False.
 
     Returns:
         A Tool instance
@@ -149,6 +154,7 @@ async def wrapped_handler(invocation: ToolInvocation) -> ToolResult:
             description=description or "",
             parameters=schema,
             handler=wrapped_handler,
+            requires_approval=requires_approval,
         )
 
     # If handler is provided, call decorator immediately

python/copilot/types.py

@@ -88,6 +88,12 @@ class Tool:
     description: str
     handler: ToolHandler
     parameters: dict[str, Any] | None = None
+    requires_approval: bool = False
+    """
+    Controls whether the tool requires user approval before execution.
+    When True, the on_permission_request handler will be called before invoking the tool.
+    When False (default), the tool executes without requesting permission.
+    """
 
 
 # System message configuration (discriminated union)
@@ -121,8 +127,9 @@ class SystemMessageReplaceConfig(TypedDict):
 class PermissionRequest(TypedDict, total=False):
     """Permission request from the server"""
 
-    kind: Literal["shell", "write", "mcp", "read", "url"]
+    kind: Literal["shell", "write", "mcp", "read", "url", "tool"]
     toolCallId: str
+    toolName: str
     # Additional fields vary by kind