Skip to content

fix(runtime): guard nested agent delegation - #3905

Merged
Sayt-0 merged 1 commit into
mainfrom
fix/delegation-cycle-depth-guard
Aug 4, 2026
Merged

fix(runtime): guard nested agent delegation#3905
Sayt-0 merged 1 commit into
mainfrom
fix/delegation-cycle-depth-guard

Conversation

@Sayt-0

@Sayt-0 Sayt-0 commented Aug 4, 2026

Copy link
Copy Markdown
Member

Summary

  • reject direct and indirect nested agent-delegation cycles with the attempted path
  • cap transfer_task and run_background_agent chains at 10 delegation edges
  • preserve valid multi-level foreground and background delegation with session-aware caller resolution
  • keep pinned background sessions isolated from the shared foreground agent
  • document the delegation limit and add deterministic async end-to-end coverage

Context

This follows #3886, which establishes that agents started with run_background_agent may delegate to their own sub-agents. Supporting that pattern requires both termination guards and session-aware routing: a pinned background session must validate, attribute, and execute nested work as its pinned agent rather than the runtime's shared foreground agent.

Issue expectations

Expectation Implementation
Direct cycles are rejected validateDelegation rejects self-delegation before a child session starts
Indirect cycles are rejected Per-session lineage detects an ancestor target and reports paths such as a -> b -> a
Acyclic multi-level delegation remains supported Lineage propagates through foreground, background, and mixed nested paths
Excessive nesting stops with an actionable error A fixed runtime maximum of 10 edges is documented; depth 10 is accepted and depth 11 is rejected
Foreground and background paths are covered Tests cover transfer_task, RunAgent, pinned sessions, concurrent nested transfers, and real async background handlers
Background delegation from #3886 remains safe Handler target validation resolves from the calling session; pinned children do not mutate shared foreground state

Test coverage

  • direct and indirect cycles
  • exact maximum-depth boundary
  • foreground transfer switching and restoration
  • nested transfers from pinned background sessions
  • concurrent pinned nested transfers
  • nested background-agent hook attribution
  • forked skills from pinned sessions without adding a delegation edge
  • legacy Runner compatibility fallback
  • end-to-end root -> run_background_agent(worker) -> run_background_agent(helper) -> list/view through the real dispatcher and detached goroutines

Validation

  • task test
  • task lint
  • task build
  • focused runtime tests with -race, including repeated async end-to-end runs

Closes #3904
Related to #3886

@Sayt-0
Sayt-0 requested a review from a team as a code owner August 4, 2026 12:20
@aheritier aheritier added area/docs Documentation changes area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection area/sessions For features/issues/fixes related to session lifecycle (resume, persistence, export) area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/fix PR fixes a bug (maps to fix:). Use on PRs only. labels Aug 4, 2026
@Sayt-0
Sayt-0 merged commit b5ec2a7 into main Aug 4, 2026
21 checks passed
@Sayt-0
Sayt-0 deleted the fix/delegation-cycle-depth-guard branch August 4, 2026 15:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation changes area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection area/sessions For features/issues/fixes related to session lifecycle (resume, persistence, export) area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/fix PR fixes a bug (maps to fix:). Use on PRs only.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

runtime: guard transfer_task against cyclic and excessive nested delegation

3 participants