docs: correct the documented contract of the invocation-subtree event filter

`_get_events(current_branch=True)` documented itself as returning events on
"the current branch or any descendant sub-branch", but that is only the user
arm, and not even all of it. The docstring now states the whole rule:

  * A user event matches this branch, a descendant sub-branch, or no branch.
  * When `self.branch` is `None`, every user event matches whatever branch it
    is on. An empty-string branch is the opposite rather than a synonym: it is
    a real value in the workflow code and matches no branched event.
  * A user event carrying function responses must additionally answer a call
    issued on this branch or below it, and is dropped otherwise even when it
    sits on exactly this branch.
  * Every other event must sit on exactly this branch.

So a confirmation answered by the user on a sub-branch is visible while the
agent event that requested it is not. The asymmetry needs a per-caller review
before it is widened -- not because sibling trees would become reachable
(`_BranchPath.is_descendant_of` already excludes those) but because every
caller would start seeing a descendant's internal events.

No behavior change. The docstring also notes that
`contents._is_event_belongs_to_branch` deliberately matches the *opposite*
direction, because it answers a different question -- "what history may this
agent see?" rather than "what happened inside this invocation?".

The descendant test also now uses `_BranchPath.is_descendant_of` instead of a
hand-rolled `startswith(f"{branch}.")`. That helper was already imported and
used elsewhere in the same file. The empty-branch guard is kept: an empty
branch is a real value in the workflow code, and a bare descendant test would
treat every branched event as its descendant.

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 970789610

Author: DeanChensj

src/google/adk/agents/invocation_context.py

@@ -449,7 +449,36 @@ def _get_events(
     if current_branch:
 
       def _is_branch_match(event: Event) -> bool:
-        """Determines if an event belongs to the current branch or any descendant sub-branch."""
+        """Determines whether an event is part of this invocation's subtree.
+
+        The rule differs by author, deliberately but asymmetrically.
+
+        A user event matches when it sits on this branch, on a descendant
+        sub-branch (e.g. a child NodeTool/WorkflowTool execution tree), or on
+        no branch at all; and when ``self.branch`` is ``None``, every user
+        event matches whatever branch it is on. An empty-string branch is the
+        opposite rather than a synonym for that: it is a real branch value in
+        the workflow code and matches no branched event. A user event carrying
+        function responses must additionally answer a function call issued on
+        this branch or below it -- one answering a call from anywhere else is
+        dropped even when it sits on exactly this branch, which is what keeps
+        a reply from leaking across parallel trees.
+
+        Any other event must sit on exactly this branch; a descendant's own
+        events are not returned.
+
+        So a confirmation answered by the user on a sub-branch is visible here
+        while the agent event that requested it is not. Widening the non-user
+        rule to descendants would not expose sibling trees --
+        ``_BranchPath.is_descendant_of`` excludes those -- but it would hand
+        every caller a descendant's internal events, so it needs a per-caller
+        review rather than a blanket change.
+
+        Note this is the opposite direction from
+        ``contents._is_event_belongs_to_branch``, which asks a different
+        question -- "what history may this agent see?" -- and so matches
+        *ancestor* branches instead. Both are intended.
+        """
         if getattr(event, "author", None) == "user":
           frs = event.get_function_responses()
           if frs and self.branch and self.session:
@@ -477,16 +506,24 @@ def _is_branch_match(event: Event) -> bool:
               if not (fr_ids & branch_fc_ids):
                 return False
 
-          # Match events yielded directly on this branch or on descendant sub-branches
-          # (e.g. child NodeTool/WorkflowTool execution trees).
+          # Match events yielded directly on this branch or on descendant
+          # sub-branches (e.g. child NodeTool/WorkflowTool execution trees).
+          # The `self.branch` guard keeps an empty branch from matching every
+          # branched event, which a bare descendant test would do.
           if (
               event.branch is None
               or self.branch is None
               or event.branch == self.branch
-              or (self.branch and event.branch.startswith(f"{self.branch}."))
+              or (
+                  self.branch
+                  and _BranchPath.from_string(event.branch).is_descendant_of(
+                      _BranchPath.from_string(self.branch)
+                  )
+              )
           ):
             return True
           return False
+        # Non-user events: exactly this branch, per the docstring above.
         return event.branch == self.branch
 
       results = [e for e in results if _is_branch_match(e)]

tests/unittests/agents/test_invocation_context.py

@@ -26,6 +26,7 @@
 from google.adk.sessions.session import Session
 from google.genai.types import Content
 from google.genai.types import FunctionCall
+from google.genai.types import FunctionResponse
 from google.genai.types import Part
 import pytest
 
@@ -794,3 +795,131 @@ def test_count_is_per_invocation_context(self):
 
     with pytest.raises(LlmCallsLimitExceededError):
       second.increment_llm_call_count()
+
+
+def _ctx_on_branch(branch, events):
+  """An InvocationContext on `branch` over a session holding `events`."""
+  return InvocationContext(
+      session_service=Mock(spec=BaseSessionService),
+      agent=Mock(spec=BaseAgent),
+      invocation_id='inv_1',
+      branch=branch,
+      session=Mock(spec=Session, events=events),
+  )
+
+
+def test_get_events_current_branch_includes_user_event_on_sub_branch():
+  """A user event from a descendant sub-branch belongs to this subtree."""
+  user_on_child = Event(
+      invocation_id='inv_1', author='user', branch='agent_1.child'
+  )
+  ctx = _ctx_on_branch('agent_1', [user_on_child])
+
+  assert ctx._get_events(current_branch=True) == [user_on_child]
+
+
+def test_get_events_current_branch_excludes_agent_event_on_sub_branch():
+  """A non-user event from a descendant sub-branch is not returned.
+
+  This is asymmetric with the user case above on purpose: widening it would
+  hand every caller a descendant's internal events. Pinned here so the
+  asymmetry is a stated contract rather than an accident.
+  """
+  agent_on_child = Event(
+      invocation_id='inv_1', author='some_agent', branch='agent_1.child'
+  )
+  ctx = _ctx_on_branch('agent_1', [agent_on_child])
+
+  assert ctx._get_events(current_branch=True) == []
+
+
+def test_get_events_current_branch_excludes_sibling_branch():
+  """A sibling branch is never part of this subtree."""
+  user_on_sibling = Event(
+      invocation_id='inv_1', author='user', branch='agent_2'
+  )
+  ctx = _ctx_on_branch('agent_1', [user_on_sibling])
+
+  assert ctx._get_events(current_branch=True) == []
+
+
+def test_get_events_empty_branch_does_not_match_every_branched_event():
+  """An empty branch must not behave like "match everything".
+
+  An empty string is a real branch value in the workflow code, and a bare
+  descendant test would treat every branched event as its descendant.
+  """
+  user_on_branch = Event(invocation_id='inv_1', author='user', branch='agent_1')
+  ctx = _ctx_on_branch('', [user_on_branch])
+
+  assert ctx._get_events(current_branch=True) == []
+
+
+def _call_event(branch, call_id):
+  """A non-user event issuing function call `call_id` on `branch`."""
+  return Event(
+      invocation_id='inv_1',
+      author='some_agent',
+      branch=branch,
+      content=Content(
+          parts=[Part(function_call=FunctionCall(id=call_id, name='t'))]
+      ),
+  )
+
+
+def _user_response_event(branch, call_id):
+  """A user event answering function call `call_id` on `branch`."""
+  return Event(
+      invocation_id='inv_1',
+      author='user',
+      branch=branch,
+      content=Content(
+          parts=[
+              Part(
+                  function_response=FunctionResponse(
+                      id=call_id, name='t', response={}
+                  )
+              )
+          ]
+      ),
+  )
+
+
+def test_get_events_current_branch_keeps_user_response_to_a_call_here():
+  """A reply answering a call issued in this subtree is returned."""
+  call_here = _call_event('agent_1.child', 'fc_1')
+  reply = _user_response_event('agent_1', 'fc_1')
+  ctx = _ctx_on_branch('agent_1', [call_here, reply])
+
+  assert ctx._get_events(current_branch=True) == [reply]
+
+
+def test_get_events_current_branch_drops_user_response_to_a_call_elsewhere():
+  """Sitting on this branch is not enough for a reply to a foreign call.
+
+  The function-response gate is the only difference from the test above, so a
+  reply that answers a parallel tree's call is dropped even though its own
+  branch matches exactly.
+  """
+  call_elsewhere = _call_event('agent_2', 'fc_1')
+  reply = _user_response_event('agent_1', 'fc_1')
+  ctx = _ctx_on_branch('agent_1', [call_elsewhere, reply])
+
+  assert ctx._get_events(current_branch=True) == []
+
+
+def test_get_events_without_a_branch_matches_every_user_event():
+  """A context with no branch sees user events wherever they sit.
+
+  Non-user events stay on the strict rule, so this also pins the asymmetry:
+  the agent event beside it is not returned.
+  """
+  user_elsewhere = Event(
+      invocation_id='inv_1', author='user', branch='agent_2.child'
+  )
+  agent_elsewhere = Event(
+      invocation_id='inv_1', author='some_agent', branch='agent_2.child'
+  )
+  ctx = _ctx_on_branch(None, [user_elsewhere, agent_elsewhere])
+
+  assert ctx._get_events(current_branch=True) == [user_elsewhere]