feat: human-in-the-loop (subagents) (kagent-dev#1491)

This PR implements the last part of HITL system in Kagent -- subagent
HITL flow. When the parent agent calls one or more subagents and any of
them invokes a `requireApproval` tool, HITL request will be cascaded up
to the user (regardless of call stack depth).

In addition, it contains 1. test coverage for previous HITL utils 2.
consistent types in python and UI for HITL 3. large enhancement to
documentation of HITL implementation in Kagent 4. various HITL cleanups

At a high level, this is what the user expects: 

<img width="2890" height="2398" alt="mermaid-diagram-2026-03-11-223608"
src="https://github.com/user-attachments/assets/10d7ba18-8b9a-41d4-8a03-ca969717997f"
/>

For more information of HITL system in Kagent, including full sequence
diagrams of how these flows are carried out, view
`docs/architecture/human-in-the-loop.md`.

---------

Signed-off-by: Jet Chiang <pokyuen.jetchiang-ext@solo.io>

Author: supreme-gg-gg

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

@@ -9,13 +9,13 @@ import (
 )
 
 var (
-	denyWordPatterns    []*regexp.Regexp
+	rejectWordPatterns  []*regexp.Regexp
 	approveWordPatterns []*regexp.Regexp
 )
 
 func init() {
-	for _, keyword := range KAgentHitlResumeKeywordsDeny {
-		denyWordPatterns = append(denyWordPatterns, regexp.MustCompile(`(?i)\b`+regexp.QuoteMeta(keyword)+`\b`))
+	for _, keyword := range KAgentHitlResumeKeywordsReject {
+		rejectWordPatterns = append(rejectWordPatterns, regexp.MustCompile(`(?i)\b`+regexp.QuoteMeta(keyword)+`\b`))
 	}
 	for _, keyword := range KAgentHitlResumeKeywordsApprove {
 		approveWordPatterns = append(approveWordPatterns, regexp.MustCompile(`(?i)\b`+regexp.QuoteMeta(keyword)+`\b`))
@@ -28,20 +28,20 @@ const (
 	KAgentHitlInterruptTypeToolApproval = "tool_approval"
 	KAgentHitlDecisionTypeKey           = "decision_type"
 	KAgentHitlDecisionTypeApprove       = "approve"
-	KAgentHitlDecisionTypeDeny          = "deny"
+	KAgentHitlDecisionTypeReject        = "reject"
 )
 
 var (
 	KAgentHitlResumeKeywordsApprove = []string{"approved", "approve", "proceed", "yes", "continue"}
-	KAgentHitlResumeKeywordsDeny    = []string{"denied", "deny", "reject", "no", "cancel", "stop"}
+	KAgentHitlResumeKeywordsReject  = []string{"denied", "deny", "reject", "no", "cancel", "stop"}
 )
 
 // DecisionType represents a HITL decision.
 type DecisionType string
 
 const (
 	DecisionApprove DecisionType = "approve"
-	DecisionDeny    DecisionType = "deny"
+	DecisionReject  DecisionType = "reject"
 )
 
 // ToolApprovalRequest represents a tool call requiring user approval.
@@ -60,9 +60,9 @@ func GetKAgentMetadataKey(key string) string {
 // keyword matching. Word boundaries prevent false positives from substrings
 // (e.g. "no" inside "know", "yes" inside "yesterday").
 func ExtractDecisionFromText(text string) DecisionType {
-	for _, pattern := range denyWordPatterns {
+	for _, pattern := range rejectWordPatterns {
 		if pattern.MatchString(text) {
-			return DecisionDeny
+			return DecisionReject
 		}
 	}
 	for _, pattern := range approveWordPatterns {
@@ -87,8 +87,8 @@ func ExtractDecisionFromMessage(message *a2atype.Message) DecisionType {
 				switch decision {
 				case KAgentHitlDecisionTypeApprove:
 					return DecisionApprove
-				case KAgentHitlDecisionTypeDeny:
-					return DecisionDeny
+				case KAgentHitlDecisionTypeReject:
+					return DecisionReject
 				}
 			}
 		}

go/adk/pkg/a2a/hitl.go

@@ -41,15 +41,15 @@ func TestExtractDecisionFromMessage_DataPart(t *testing.T) {
 		t.Errorf("ExtractDecisionFromMessage(approve DataPart) = %q, want %q", result, DecisionApprove)
 	}
 
-	denyData := map[string]any{
-		KAgentHitlDecisionTypeKey: KAgentHitlDecisionTypeDeny,
+	rejectData := map[string]any{
+		KAgentHitlDecisionTypeKey: KAgentHitlDecisionTypeReject,
 	}
 	message = a2atype.NewMessage(a2atype.MessageRoleUser,
-		&a2atype.DataPart{Data: denyData},
+		&a2atype.DataPart{Data: rejectData},
 	)
 	result = ExtractDecisionFromMessage(message)
-	if result != DecisionDeny {
-		t.Errorf("ExtractDecisionFromMessage(deny DataPart) = %q, want %q", result, DecisionDeny)
+	if result != DecisionReject {
+		t.Errorf("ExtractDecisionFromMessage(reject DataPart) = %q, want %q", result, DecisionReject)
 	}
 }
 
@@ -66,8 +66,8 @@ func TestExtractDecisionFromMessage_TextPart(t *testing.T) {
 		a2atype.TextPart{Text: "Request denied, do not proceed"},
 	)
 	result = ExtractDecisionFromMessage(message)
-	if result != DecisionDeny {
-		t.Errorf("ExtractDecisionFromMessage(deny text) = %q, want %q", result, DecisionDeny)
+	if result != DecisionReject {
+		t.Errorf("ExtractDecisionFromMessage(reject text) = %q, want %q", result, DecisionReject)
 	}
 
 	message = a2atype.NewMessage(a2atype.MessageRoleUser,
@@ -84,13 +84,13 @@ func TestExtractDecisionFromMessage_Priority(t *testing.T) {
 		a2atype.TextPart{Text: "approved"},
 		&a2atype.DataPart{
 			Data: map[string]any{
-				KAgentHitlDecisionTypeKey: KAgentHitlDecisionTypeDeny,
+				KAgentHitlDecisionTypeKey: KAgentHitlDecisionTypeReject,
 			},
 		},
 	)
 	result := ExtractDecisionFromMessage(message)
-	if result != DecisionDeny {
-		t.Errorf("ExtractDecisionFromMessage(mixed parts) = %q, want %q (DataPart should take priority)", result, DecisionDeny)
+	if result != DecisionReject {
+		t.Errorf("ExtractDecisionFromMessage(mixed parts) = %q, want %q (DataPart should take priority)", result, DecisionReject)
 	}
 }
 
@@ -125,12 +125,12 @@ func TestExtractDecisionFromText_WordBoundary(t *testing.T) {
 		{name: "yes inside yesterday should not match", text: "yesterday was fine", want: ""},
 		{name: "stop inside unstoppable should not match", text: "unstoppable progress", want: ""},
 		{name: "cancel inside cancellation should not match", text: "the cancellation policy", want: ""},
-		{name: "standalone no matches", text: "no, I do not agree", want: DecisionDeny},
+		{name: "standalone no matches", text: "no, I do not agree", want: DecisionReject},
 		{name: "standalone yes matches", text: "yes, go ahead", want: DecisionApprove},
-		{name: "standalone stop matches", text: "stop the process", want: DecisionDeny},
-		{name: "case insensitive whole word", text: "NO", want: DecisionDeny},
-		{name: "keyword at end of sentence", text: "the answer is no", want: DecisionDeny},
-		{name: "keyword with punctuation", text: "no!", want: DecisionDeny},
+		{name: "standalone stop matches", text: "stop the process", want: DecisionReject},
+		{name: "case insensitive whole word", text: "NO", want: DecisionReject},
+		{name: "keyword at end of sentence", text: "the answer is no", want: DecisionReject},
+		{name: "keyword with punctuation", text: "no!", want: DecisionReject},
 		{name: "continue inside discontinue should not match", text: "I will discontinue", want: ""},
 		{name: "approve as standalone", text: "I approve", want: DecisionApprove},
 	}

go/adk/pkg/a2a/hitl_test.go

@@ -345,17 +345,18 @@ async def _publish_failed_status_event(
             logger.error("Failed to publish failure event: %s", enqueue_error, exc_info=True)
 
     @staticmethod
-    def _find_pending_confirmations(session: Session) -> dict[str, str | None]:
+    def _find_pending_confirmations(session: Session) -> dict[str, tuple[str | None, dict | None]]:
         """Find pending adk_request_confirmation calls and their original tool call IDs.
 
         Scans session events backwards for the most recent adk_request_confirmation
         FunctionCall events that haven't been responded to yet.
 
         Returns:
-            Dict mapping confirmation function_call_id to the original tool call ID
-            (from args.originalFunctionCall.id), or None if not available.
+            Dict mapping confirmation function_call_id to a tuple of:
+              - the original tool call ID (from args.originalFunctionCall.id), or None
+              - the original toolConfirmation payload (from args.toolConfirmation.payload), or None
         """
-        pending: dict[str, str | None] = {}
+        pending: dict[str, tuple[str | None, dict | None]] = {}
         responded_ids: set[str] = set()
 
         for event in reversed(session.events or []):
@@ -364,16 +365,23 @@ def _find_pending_confirmations(session: Session) -> dict[str, str | None]:
                 if fr.name == REQUEST_CONFIRMATION_FUNCTION_CALL_NAME and fr.id is not None:
                     responded_ids.add(fr.id)
 
-            # Collect requested confirmation IDs and extract original tool call ID
+            # Collect requested confirmation IDs and extract original tool call ID + payload
             for fc in event.get_function_calls():
                 if fc.name == REQUEST_CONFIRMATION_FUNCTION_CALL_NAME and fc.id is not None:
-                    # Extract original tool call ID from args.originalFunctionCall.id
                     original_id = None
+                    original_payload = None
                     if fc.args and isinstance(fc.args, dict):
                         orig_fc = fc.args.get("originalFunctionCall")
                         if isinstance(orig_fc, dict):
                             original_id = orig_fc.get("id")
-                    pending[fc.id] = original_id
+                        tool_conf = fc.args.get("toolConfirmation")
+                        if isinstance(tool_conf, dict):
+                            original_payload = tool_conf.get("payload")
+                            if isinstance(original_payload, dict):
+                                original_payload = dict(original_payload)
+                            else:
+                                original_payload = None
+                    pending[fc.id] = (original_id, original_payload)
 
             # Stop scanning once we find confirmation requests (they're recent)
             if pending:
@@ -385,6 +393,27 @@ def _find_pending_confirmations(session: Session) -> dict[str, str | None]:
 
         return pending
 
+    @staticmethod
+    def _build_confirmation_payload(
+        original_payload: dict | None,
+        extra: dict | None,
+    ) -> dict | None:
+        """Merge the original request_confirmation payload with decision-specific data.
+
+        The original payload (set by the tool in ``request_confirmation()``) is
+        preserved so that the tool's ``_handle_resume`` can read its own state
+        (e.g. subagent task_id, context_id).  Decision-specific keys (like
+        ``rejection_reason``) are merged on top.
+        """
+        if not original_payload and not extra:
+            return None
+        merged: dict = {}
+        if original_payload:
+            merged.update(original_payload)
+        if extra:
+            merged.update(extra)
+        return merged
+
     def _process_hitl_decision(
         self, session: Session, decision: str, message: Message
     ) -> list[genai_types.Part] | None:
@@ -394,9 +423,9 @@ def _process_hitl_decision(
             return None
 
         logger.info(
-            "HITL continuation detected: decision=%s, pending_confirmations=%d",
+            "HITL continuation: decision=%s, pending=%s",
             decision,
-            len(pending_confirmations),
+            {fc_id: orig_id for fc_id, (orig_id, _) in pending_confirmations.items()},
         )
 
         # Check for ask-user answers — if present, build a single approved
@@ -405,8 +434,9 @@ def _process_hitl_decision(
         ask_user_answers = extract_ask_user_answers_from_message(message)
         if ask_user_answers is not None:
             parts = []
-            for fc_id in pending_confirmations:
-                confirmation = ToolConfirmation(confirmed=True, payload={"answers": ask_user_answers})
+            for fc_id, (_, orig_payload) in pending_confirmations.items():
+                payload = self._build_confirmation_payload(orig_payload, {"answers": ask_user_answers})
+                confirmation = ToolConfirmation(confirmed=True, payload=payload)
                 parts.append(
                     genai_types.Part(
                         function_response=genai_types.FunctionResponse(
@@ -424,19 +454,37 @@ def _process_hitl_decision(
         if decision == KAGENT_HITL_DECISION_TYPE_BATCH:
             # Batch mode: per-tool decisions
             batch_decisions = extract_batch_decisions_from_message(message) or {}
+            logger.info(
+                "HITL batch: batch_decisions=%s, rejection_reasons=%s",
+                batch_decisions,
+                rejection_reasons,
+            )
             parts = []
-            for fc_id, original_id in pending_confirmations.items():
-                # Look up the per-tool decision using the original tool call ID
-                tool_decision = batch_decisions.get(original_id, KAGENT_HITL_DECISION_TYPE_APPROVE)
-                confirmed = tool_decision == KAGENT_HITL_DECISION_TYPE_APPROVE
-                # Attach rejection reason if provided for this specific tool
-                payload: dict | None = None
-                if not confirmed and rejection_reasons:
-                    reason = rejection_reasons.get(original_id) if original_id else None
-                    if reason:
-                        payload = {"rejection_reason": reason}
-                confirmation = ToolConfirmation(confirmed=confirmed, payload=payload)
-                # Append a response for each tool call
+            for fc_id, (original_id, orig_payload) in pending_confirmations.items():
+                # Check if this is a subagent HITL request by checking if orig_payload has hitl_parts.
+                is_subagent = bool(orig_payload and orig_payload.get("hitl_parts"))
+
+                if is_subagent:
+                    # Forward the entire batch decision to the tool so
+                    # _handle_resume can relay it to the subagent as-is.
+                    all_approved = all(d == KAGENT_HITL_DECISION_TYPE_APPROVE for d in batch_decisions.values())
+                    extra: dict = {"batch_decisions": batch_decisions}
+                    if rejection_reasons:
+                        extra["rejection_reasons"] = rejection_reasons
+                    payload = self._build_confirmation_payload(orig_payload, extra)
+                    confirmation = ToolConfirmation(confirmed=all_approved, payload=payload)
+                else:
+                    # Direct tool — look up by original_id as before
+                    tool_decision = batch_decisions.get(original_id, KAGENT_HITL_DECISION_TYPE_APPROVE)
+                    confirmed = tool_decision == KAGENT_HITL_DECISION_TYPE_APPROVE
+                    extra_reject: dict | None = None
+                    if not confirmed and rejection_reasons:
+                        reason = rejection_reasons.get(original_id) if original_id else None
+                        if reason:
+                            extra_reject = {"rejection_reason": reason}
+                    payload = self._build_confirmation_payload(orig_payload, extra_reject)
+                    confirmation = ToolConfirmation(confirmed=confirmed, payload=payload)
+
                 parts.append(
                     genai_types.Part(
                         function_response=genai_types.FunctionResponse(
@@ -451,22 +499,26 @@ def _process_hitl_decision(
             # Uniform mode: same decision for all pending tools
             confirmed = decision == KAGENT_HITL_DECISION_TYPE_APPROVE
             # Attach rejection reason if provided (uniform denial uses "*" sentinel)
-            payload = None
+            uniform_extra: dict | None = None
             if not confirmed and rejection_reasons:
                 reason = rejection_reasons.get("*")
                 if reason:
-                    payload = {"rejection_reason": reason}
-            confirmation = ToolConfirmation(confirmed=confirmed, payload=payload)
-            return [
-                genai_types.Part(
-                    function_response=genai_types.FunctionResponse(
-                        name=REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
-                        id=fc_id,
-                        response={"response": confirmation.model_dump_json()},
+                    uniform_extra = {"rejection_reason": reason}
+            parts = []
+            for fc_id, (_, orig_payload) in pending_confirmations.items():
+                merged_payload = self._build_confirmation_payload(orig_payload, uniform_extra)
+                confirmation = ToolConfirmation(confirmed=confirmed, payload=merged_payload)
+                serialized = confirmation.model_dump_json()
+                parts.append(
+                    genai_types.Part(
+                        function_response=genai_types.FunctionResponse(
+                            name=REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+                            id=fc_id,
+                            response={"response": serialized},
+                        )
                     )
                 )
-                for fc_id in pending_confirmations
-            ]
+            return parts
 
     async def _handle_request(
         self,