feat: human in the loop (confirmation) (kagent-dev#1398)

Supports confirmation flow for HITL (single and parallel tool use). Flow
documented in `docs/architecture/human-in-the-loop.md`

Todo: custom payload so the agent can invoke tools that require user
input

---------

Signed-off-by: Eitan Yarmush <eitan.yarmush@solo.io>
Signed-off-by: Jet Chiang <pokyuen.jetchiang-ext@solo.io>
Co-authored-by: Eitan Yarmush <eitan.yarmush@solo.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/architecture/human-in-the-loop.md

@@ -377,6 +377,7 @@ func (s *Tool) ResolveHeaders(ctx context.Context, client client.Client, namespa
 	return result, nil
 }
 
+// +kubebuilder:validation:XValidation:message="each RequireApproval entry must also appear in ToolNames",rule="!has(self.requireApproval) || self.requireApproval.all(x, has(self.toolNames) && x in self.toolNames)"
 type McpServerTool struct {
 	// The reference to the ToolServer that provides the tool.
 	// +optional
@@ -385,8 +386,17 @@ type McpServerTool struct {
 	// The names of the tools to be provided by the ToolServer
 	// For a list of all the tools provided by the server,
 	// the client can query the status of the ToolServer object after it has been created
+	// +kubebuilder:validation:MaxItems=50
 	ToolNames []string `json:"toolNames,omitempty"`
 
+	// RequireApproval lists tool names that require human approval before
+	// execution. Each name must also appear in ToolNames. When a tool in
+	// this list is invoked by the agent, execution pauses and the user is
+	// prompted to approve or reject the call.
+	// +optional
+	// +kubebuilder:validation:MaxItems=50
+	RequireApproval []string `json:"requireApproval,omitempty"`
+
 	// AllowedHeaders specifies which headers from the A2A request should be
 	// propagated to MCP tool calls. Header names are case-insensitive.
 	//

go/api/v1alpha2/agent_types.go

@@ -10091,17 +10091,33 @@ spec:
                               type: string
                             namespace:
                               type: string
+                            requireApproval:
+                              description: |-
+                                RequireApproval lists tool names that require human approval before
+                                execution. Each name must also appear in ToolNames. When a tool in
+                                this list is invoked by the agent, execution pauses and the user is
+                                prompted to approve or reject the call.
+                              items:
+                                type: string
+                              maxItems: 50
+                              type: array
                             toolNames:
                               description: |-
                                 The names of the tools to be provided by the ToolServer
                                 For a list of all the tools provided by the server,
                                 the client can query the status of the ToolServer object after it has been created
                               items:
                                 type: string
+                              maxItems: 50
                               type: array
                           required:
                           - name
                           type: object
+                          x-kubernetes-validations:
+                          - message: each RequireApproval entry must also appear in
+                              ToolNames
+                            rule: '!has(self.requireApproval) || self.requireApproval.all(x,
+                              has(self.toolNames) && x in self.toolNames)'
                         type:
                           allOf:
                           - enum:

go/api/v1alpha2/zz_generated.deepcopy.go

@@ -1337,19 +1337,21 @@ func (a *adkApiTranslator) translateRemoteMCPServerTarget(ctx context.Context, a
 			return err
 		}
 		agent.SseTools = append(agent.SseTools, adk.SseMcpServerConfig{
-			Params:         *tool,
-			Tools:          mcpServerTool.ToolNames,
-			AllowedHeaders: mcpServerTool.AllowedHeaders,
+			Params:          *tool,
+			Tools:           mcpServerTool.ToolNames,
+			AllowedHeaders:  mcpServerTool.AllowedHeaders,
+			RequireApproval: mcpServerTool.RequireApproval,
 		})
 	default:
 		tool, err := a.translateStreamableHttpTool(ctx, remoteMcpServer, agentHeaders, proxyURL)
 		if err != nil {
 			return err
 		}
 		agent.HttpTools = append(agent.HttpTools, adk.HttpMcpServerConfig{
-			Params:         *tool,
-			Tools:          mcpServerTool.ToolNames,
-			AllowedHeaders: mcpServerTool.AllowedHeaders,
+			Params:          *tool,
+			Tools:           mcpServerTool.ToolNames,
+			AllowedHeaders:  mcpServerTool.AllowedHeaders,
+			RequireApproval: mcpServerTool.RequireApproval,
 		})
 	}
 	return nil

go/config/crd/bases/kagent.dev_agents.yaml

@@ -0,0 +1,58 @@
+operation: translateAgent
+targetObject: agent
+namespace: test
+objects:
+  - apiVersion: v1
+    kind: Secret
+    metadata:
+      name: openai-secret
+      namespace: test
+    data:
+      api-key: c2stdGVzdC1hcGkta2V5  # base64 encoded "sk-test-api-key"
+  - apiVersion: kagent.dev/v1alpha2
+    kind: ModelConfig
+    metadata:
+      name: test-model
+      namespace: test
+    spec:
+      provider: OpenAI
+      model: gpt-4o
+      apiKeySecret: openai-secret
+      apiKeySecretKey: api-key
+  - apiVersion: kagent.dev/v1alpha2
+    kind: Agent
+    metadata:
+      name: agent
+      namespace: test
+    spec:
+      type: Declarative
+      declarative:
+        description: A file management agent
+        systemMessage: You help users manage files.
+        modelConfig: test-model
+        tools:
+          - type: MCPServer
+            mcpServer:
+              name: toolserver
+              kind: Service
+              toolNames:
+                - read_file
+                - write_file
+                - delete_file
+              requireApproval:
+                - delete_file
+                - write_file
+  - apiVersion: v1
+    kind: Service
+    metadata:
+      name: toolserver
+      annotations:
+        kagent.dev/mcp-service-path: "/mcp"
+      namespace: test
+    spec:
+      ports:
+      - name: mcp
+        port: 8084
+        targetPort: 8084
+        protocol: TCP
+        appProtocol: mcp