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

[calvingiles]

This is an initial proposal seeking feedback adds an Approval Mechanism.

This is a fully working implementation that we have begun using in our internal agents.

This mechanism allows tools to be annotated like:

@tool_policy(
    actions=["tool:local_file:read"],
    resources=resource_parameters("tool:local_file", ["path"]),
)
def read_file(*, path: str):
  try:
    with open(path, "r") as f:
      return f.read()
  except Exception as e:
    return str(e)

when you then try to use the agent, you will receive an approval request in response with the challenges that need to be granted in order to call the tool:

{
  "id": "adk-38e8d3c6-a14c-4673-b4e8-cc2e2908d64a",
  "args": {
    "grantee": {
      "id": "tool:list_directory:adk-6b26eed9-2fa7-496e-ba8f-9d75362d0e0a",
      "type": "tool",
      "on_behalf_of": {
        "id": "3a0400f2-d9d9-4909-8ec3-41f8f28c76fe",
        "type": "agent",
        "on_behalf_of": {
          "id": "calvingiles",
          "type": "user"
        }
      }
    },
    "challenges": [
      {
        "actions": [
          "tool:local_file:read"
        ],
        "resources": [
          "tool:local_file:/Users/calvingiles/eng/repos/adk-python"
        ]
      }
    ],
    "function_call": {
      "id": "adk-6b26eed9-2fa7-496e-ba8f-9d75362d0e0a",
      "args": {
        "dir_path": "/Users/calvingiles/eng/repos/adk-python"
      },
      "name": "list_directory"
    }
  },
  "name": "adk_request_approval"
}

This can then be granted by sending a message like:

{
  "name": "adk_request_approval",
  "response": {
    "grants": [
      {
        "effect": "allow",
        "actions": [
          "tool:local_file:read"
        ],
        "grantee": {
          "id": "tool:list_directory:*",
          "type": "tool",
          "on_behalf_of": {
            "id": "3a0400f2-d9d9-4909-8ec3-41f8f28c76fe",
            "type": "agent",
            "on_behalf_of": {
              "id": "calvingiles",
              "type": "user"
            }
          }
        },
        "grantor": {
          "id": "calvingiles",
          "type": "user"
        },
        "resources": [
          "tool:local_file:/Users/calvingiles/eng/repos/adk-python"
        ]
      }
    ]
  }
}

Where the grant can include wildcards so that )for example, in this case) any function call that matches these actions and resources called by this agent will be approved in the future.

This is working in our internal service, but I am interested in whether this would be suitable to include in adk directly.

Relates to the issue #640

[calvingiles]

This PR is now significantly updated from its initial version - we are using it day to day with our UI and it is working well. I have simplified the design, but it still requires changes to the core logic - implementing it using only callbacks would be challenging as it relies on logic in the content preprocessor before the before_model_callback and it would be very hard to replicate this entirely after that preprocessor has run.

[hangfei]

@calvingiles thanks for your contribution. We will evaluate it in the upcoming weeks.