Problem Description

When a Team contains another Team as a member, the parent team leader currently sees the full nested member tree in its system prompt and can call delegate_task_to_member directly on a grandchild agent, bypassing the sub-team's own leader.

This breaks encapsulation in nested team hierarchies:

• The sub-team's instructions, member-interaction context, and synthesis step are all skipped when the parent delegates straight to a grandchild.
• The system prompt bloats in deep hierarchies because every level enumerates every descendant.
• The parent leader frequently picks an individual grandchild over the sub-team-as-a-unit, even when treating the sub-team as a single delegate would be the correct decomposition.

There is currently no way to tell a parent team "treat this sub-team as a black box — delegate to it as a unit and let it handle its own routing."

Proposed Solution

Add a per-team flag Team.expose_sub_team_members (default True, fully backwards-compatible) that gates whether a parent leader can see and address the members of nested sub-teams.

When expose_sub_team_members=False on a parent team:

• get_members_system_message_content does not recurse into sub-team members; sub-teams render as opaque <member type="team"> blocks in the parent's prompt.
• _find_member_by_id does not descend into sub-teams, so delegate_task_to_member can only target direct members. The sub-team's own leader resolves its own members (using its own independently-configured flag).
• The delegate_task_to_member not-found error message scope follows the flag ("in the team" vs "in the team or any subteams").

HITL routing via _find_member_route_by_id should remain unchanged: it still recurses through each sub-team's own _find_member_by_id, which follows that sub-team's own flag, so resuming a paused nested member continues to work.

The flag is per-team, so a parent and its sub-team can be configured independently.

Alternatives Considered

• Wrapping a sub-team in a thin agent facade — works but loses streaming, metrics, and team-native features.
• Always hiding nested members unconditionally — breaks existing flat-team-with-team-member setups that rely on the current behavior.

Additional Context

Field would be serialized only when non-default to avoid touching existing snapshots.

PR with implementation + tests + cookbook example: #7689

Would you like to work on this?

• Yes, I'd love to work on it!