feat: Rich Approval Mechanism for Human in the loop Tool Approvals

Author: calvingiles

src/google/adk/approval/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# from .approval_handler import ApprovalHandler
+# from .approval_tool import ApprovalConfig
+# from .approval_processor import request_processor

src/google/adk/approval/approval_grant.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+from datetime import datetime
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+class ApprovalActor(BaseModel):
+  id: str
+  type: str = Literal["user", "agent", "tool"]
+  on_behalf_of: ApprovalActor | None = None
+
+
+class ApprovalEffect(str, Enum):
+  allow = "allow"
+  deny = "deny"
+  challenge = "challenge"
+
+
+ApprovalAction = str
+ApprovalResource = str
+
+
+class ApprovalGrant(BaseModel):
+  """Effect the actions on the resources to the grantee by the grantor until the expiration."""
+
+  effect: Literal[ApprovalEffect.allow, ApprovalEffect.deny]
+  """Whether to grant an allow or deny."""
+  actions: list[ApprovalAction]
+  """The actions to which the grant will effect."""
+  resources: list[ApprovalResource]
+  """The resources that this grant affects."""
+  grantee: ApprovalActor
+  """Who the grant applies to."""
+  grantor: ApprovalActor
+  """The permission holder that granted toe access (e.g. user, or delegated by a parent agent)."""
+  expiration_time: Optional[datetime] = None  # Optional expiration time
+  """The time after which the grant ceases to be valid."""
+
+  comment: Optional[str] = None
+  """Comment from the grantor (typically the end user) from the point of granting. This is used when communicating a grant update to a model, for example a deny, to explain the reason."""