feat: gate human-in-the-loop tool confirmation on the caller principal

[cybrdude]

Follow-up to #6461, taking the direction you gave there: the principal belongs in the framework, warn plus opt-in strict now, consider flipping at the next major.

What this changes

ExecuteBashTool and every other confirmation-gated tool run on tool_confirmation.confirmed alone. Nothing upstream establishes who set it, so a remote A2A peer can approve the tool call it just caused.

The earlier attempt (cb1aceb, then 9e9eaa6, reverted by 9a32eba) keyed the guard off the presence of a2a_metadata on RunConfig.custom_metadata. That is a transport marker, and a transport is a proxy for identity. It failed in both directions: it refused authenticated peers because they arrived over A2A, and it admitted anyone reaching a path that does not stamp the marker. It also refused by returning early, which left the adk_request_confirmation call pending with nothing to resolve it and hung every HITL tool. That is what got it reverted.

This asks the authentication question instead.

Shape

CallerPrincipal (new, agents/_caller_principal.py, exported as google.adk.agents.CallerPrincipal) is frozen, extra="forbid", and carries two facts: did a serving layer authenticate the caller, and as whom.

InvocationContext.caller_principal has three meaningful states:

state	meaning	resultt
None	no remote trust boundary was crossed (in-process Runner.run_async)	allow
authenticated=False	a serving edge handled the request and could not say who sent it	warn by default, refuse under STRICT_CALLER_PRINCIPAL
authenticated=True	the edge verified the caller	allow

build_caller_principal() in the A2A request converter reads the same call_context that _get_user_id already reads, and keeps the bit _get_user_id discards. _get_user_id keeps its return contract. A caller is authenticated exactly when _get_user_id takes its call-context branch rather than the A2A_USER_ fallback, plus one extra condition: an a2a User reporting is_authenticated False is not vouched for even if it carries a name. Stricter by one condition, never looser. A parametrized test asserts the two cannot drift apart, since drift is the failure mode that produced this bug in the first place.

Both executors re-derive the principal from the RequestContext immediately after the pluggable request_converter returns, so a custom converter can neither drop it nor assert one the server never established.

explicit refusal

This is the part that matters given the last revert. A refusal rewrites the confirmation to confirmed=False rather than dropping it. confirmed=False is a state the framework already has a contract for: ExecuteBashTool returns {"error": "This tool call is rejected."} for it, and test_request_confirmation_processor_tool_not_confirmed already pins that path. So the pending call resolves with a reason the caller can see and the turn ends. Nothing hangs.

The gate runs after the consumed-confirmation dedup, so the multi-turn re-entry case that _build_consumed_dynamic_confirmation_events describes stays a no-op. There is a test pinning that specifically.

Default behavior and the strict switch

Warn and proceed by default. Strict refusal is FeatureName.STRICT_CALLER_PRINCIPAL, registered EXPERIMENTAL with default_on=False, and read through is_feature_enabled. That gives operators the three things the registry already provides for every staged behavior change: ADK_ENABLE_STRICT_CALLER_PRINCIPAL=1 in the environment, override_feature_enabled(FeatureName.STRICT_CALLER_PRINCIPAL, True) where environment variables are not practical, and a one-line default_on change when the default flips. DYNAMIC_INSTRUCTION_ROUTING and SNAKE_CASE_SKILL_NAME are the existing precedents for an off-by-default entry.

I considered and rejected two alternatives. A field on RunConfig is out because RunConfig is caller-influenceable (/run populates custom_metadata from the request body), and a security switch a caller can reach is not a switch. A bespoke environment variable, which is what the first draft of this branch used, is out because it would be a second mechanism for something the registry already does, without the programmatic override or the test scoping.

Flipping the default is deliberately not in this PR. FeatureStage.STABLE is documented as "no breaking changes without MAJOR version bump," and changing what an existing unauthenticated A2A deployment does with an approval is exactly that kind of change. The registry entry carries a comment saying the flip is the whole of the planned next-major change.

scope

• The AgentRunRequest touched here is the A2A one in a2a/converters/request_converter.py. Nothing under src/google/adk/cli/ references it, so the /run HTTP body cannot set caller_principal.
• The synchronous Runner.run wrapper is untouched. A direct in-process call has no serving layer to vouch for it.
• _new_invocation_context_for_live is untouched. Live sessions get None and behave as today.
• /run still needs real API-server auth. This is not a substitute for that and I am not claiming it is.
• Every hunk is additive against main: 13 files, +745 / -0. The 22 commits are granular by design, including the two that apply what the pre-commit run reported, and squash cleanly.

Tests

test_request_converter.py: seven cases on build_caller_principal, including the parametrized agreement-with-_get_user_id invariant.

test_confirmation.py: absent principal, authenticated, unauthenticated under the default, unauthenticated under strict, strict against an in-process caller, and strict against multi-turn re-entry. The strict test asserts that execution is reached carrying confirmed=False, rather than asserting no events. A stall would also produce no events, so that assertion would not distinguish the fix from the bug it replaces.