fix: nested parallel agents can't see output from earlier parallel stages (#3470) - #7242

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Inconsistent Event Visibility in Parallel Agent Branching and LLM Context #3470
• Supersedes: Overhaul Branch Logic from string based to token set based.  #3889

Problem:

Agents cannot see finished output from other branches of a ParallelAgent. #3470 reports two shapes:

Sequential[ Parallel[ Sequential[Parallel[a, b, c], r1],        r1 cannot see a, b, c
                       Sequential[Parallel[d, e, f], r2] ],      r2 cannot see d, e, f
            r3 ]

Sequential[ Parallel[a, b], Parallel[c, d] ]                    c, d cannot see a, b

The events exist in the session. _is_event_belongs_to_branch in flows/llm_flows/contents.py filters them out of the LLM request because it uses prefix matching: an agent on branch X sees an event on branch Y only if Y is a prefix of X. That answers "is the event from above me?", but the question it needs to answer is "are we in isolated lanes?"

Solution:

Change one function. No new types, no new fields, no storage or schema change. Event.branch stays a plain string.

The fix rests on one fact. ParallelAgent is the only agent that writes to branch (agents/parallel_agent.py:35), and it always appends exactly one dot-separated pair: parallel_agent_name.sub_agent_name. SequentialAgent and LoopAgent never touch it. So a branch string is a sequence of these pairs, and the segments alternate: even positions name a ParallelAgent, odd positions name one of its sub-agents.

Walk both branch strings segment by segment to the first mismatch. The index of that mismatch tells you everything:

The odd case is the only thing that creates isolation. Two sub-agents of the same ParallelAgent are in sibling lanes and never see each other's output, regardless of whether one finished before the other started.

The even case is where directionality matters. If the first mismatch is at an even index, the two branches name different ParallelAgents at that position. But every segment before that point matched — same ParallelAgents, same sub-agents, all the way up. That means no ParallelAgent above them forked them into different lanes. Whatever container holds these two ParallelAgents is a SequentialAgent or LoopAgent, which runs children one after another. They are not isolated.

The fourth example in the table below shows why the walk must go left to right. gp.x.p1.a and gp.y.p2.d have different ParallelAgents at index 2 (p1 vs p2), but the walk never reaches index 2 — it stops at index 1 (x vs y), where the two are sub-agents of the same ParallelAgent gp. That odd-index mismatch means they are in sibling lanes of gp, and the event is hidden.

stage1.a    vs  stage1.b        mismatch at 1 (odd)   → hidden
stage2.c    vs  stage1.a        mismatch at 0 (even)  → visible
par.r1      vs  par.r1.abc.a    no mismatch (prefix)  → visible
gp.x.p1.a  vs  gp.y.p2.d      mismatch at 1 (odd)   → hidden

def _is_event_belongs_to_branch(invocation_branch, event):
  """Check if an event belongs to the current branch.

  Sub-agents of a ParallelAgent are isolated lanes: an agent never sees output
  from a sibling lane or from anything nested inside one. Everything else is
  visible.

  Only ParallelAgent writes branches, always as `parallel_agent.sub_agent`
  pairs, so even segments name a ParallelAgent and odd segments name one of
  its sub-agents. Walk both branches to the first mismatch:

    odd    same ParallelAgent, different sub-agents: sibling lanes. Hidden.
    even   different ParallelAgents. Every earlier segment matched, so no
           ParallelAgent above forked them into different lanes. Visible.
    none   one branch is a prefix of the other: same lane. Visible.

    stage1.a    vs  stage1.b        mismatch at 1, odd   hidden
    stage2.c    vs  stage1.a        mismatch at 0, even  visible
    par.r1      vs  par.r1.abc.a    no mismatch, prefix  visible
    gp.x.p1.a  vs  gp.y.p2.d      mismatch at 1, odd   hidden
  """
  if not invocation_branch or not event.branch:
    return True
  current = invocation_branch.split('.')
  other = event.branch.split('.')
  for i, (a, b) in enumerate(zip(current, other)):
    if a != b:
      return i % 2 == 0
  return True

Prior approaches:

• The bidirectional prefix check proposed in Inconsistent Event Visibility in Parallel Agent Branching and LLM Context #3470's comments fixes the reducer case but not the sequence-of-stages case (stage2.c and stage1.a are not prefixes of each other). It also drops the .-delimiter guard, so agent_0 matches agent_00.
• Overhaul Branch Logic from string based to token set based.  #3889 replaced the branch string with a set of integer tokens. The visibility logic is sound, but it changes the type of Event.branch, which reaches session storage, the Vertex session service, the BigQuery plugin, and the web UI. This PR gets the same result from the string already stored.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

tests/unittests/flows/llm_flows/test_contents_branch.py

• test_is_event_belongs_to_branch: nine-row parametrized truth table over the function — one row per case in the table above, plus no-branch, same-branch, and name-prefix-collision rows.
• test_branch_filtering_parent_sees_finished_children (renamed from test_branch_filtering_parent_cannot_see_child — the old assertion was the reported bug).
• test_branch_filtering_grandchild_sees_grandparent updated to use parallel.sub pair shapes.

tests/unittests/agents/test_parallel_branch_visibility.py (new)

• test_reducer_nested_in_parallel_sees_its_workers — the exact architecture from Inconsistent Event Visibility in Parallel Agent Branching and LLM Context #3470.
• test_sequence_of_parallel_stages_sees_earlier_stages — the follow-up case from Inconsistent Event Visibility in Parallel Agent Branching and LLM Context #3470.
• test_visibility_matches_tree_structure[0..19] — 20 seeded random Sequential/Parallel trees run through InMemoryRunner. Expected visibility is derived from the tree structure alone, then checked against what the real runner put in each agent's LLM request. 231 agents, 2,684 pairs checked.

The new tests reject the alternatives:

Full suite: 6846 passed (v1 baseline: 6815; difference is the new tests).

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.

Additional context

This targets v1. LoopAgent reuses the same branch strings across iterations, so Loop[Parallel[a, b]] has a separate visibility gap — that is a pre-existing issue and will be a separate PR.