feat(agents): migrate subagents to event-driven scheduler

[abhipatel12]

Summary

This PR migrates subagents to use the new event-driven Scheduler. This is a
critical step in unifying tool execution and state management across the CLI.

Details

• Event-Driven Subagents: Transitions LocalAgentExecutor from the legacy
  nonInteractiveToolExecutor to the new Scheduler class via a new
  scheduleAgentTools helper.
• Context Propagation: Introduces AsyncLocalStorage-based
  ToolCallContext to propagate callId, schedulerId, and origin across
  tool validation and execution. This ensures that tools executed by subagents
  are correctly tracked and isolated in the UI.
• Improved Testing: Adds unit tests for the new agent-scheduler helper and
  ToolCallContext propagation.
• UI Consistency: By using the centralized Scheduler, subagent tool calls
  now correctly emit TOOL_CALLS_UPDATE events, allowing for better real-time
  UI feedback.

Related Issues

Related to #14306

How to Validate

1. Run the new unit tests:

   npm test -w @google/gemini-cli-core -- src/agents/agent-scheduler.test.ts src/utils/toolCallContext.test.ts

2. Run all core tests:

   npm test -w @google/gemini-cli-core

3. (Manual) Create and invoke a local subagent that requires tool confirmations
   and verify that tool calls are correctly displayed and tracked in the UI.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt

[gemini-code-assist]

Summary of Changes

Hello @abhipatel12, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the architecture for subagent tool execution by transitioning to a new event-driven Scheduler. This change centralizes the handling of tool calls, leading to more consistent state management and improved real-time user interface feedback. It also establishes a robust mechanism for propagating execution context, which is vital for accurate tracking and isolation of nested tool operations.

Highlights

• Subagent Tool Execution Migration: The LocalAgentExecutor now utilizes the event-driven Scheduler through a new scheduleAgentTools helper, replacing the legacy nonInteractiveToolExecutor for centralized tool call management.
• Tool Call Context Propagation: An AsyncLocalStorage-based ToolCallContext has been introduced to ensure callId, schedulerId, and origin are correctly propagated and isolated across tool validation and execution, particularly for nested subagent calls.
• Enhanced UI Consistency: By integrating with the centralized Scheduler, subagent tool calls now consistently emit TOOL_CALLS_UPDATE events, providing more accurate and real-time feedback in the user interface.
• New Helper and Context Utilities: New files agent-scheduler.ts and toolCallContext.ts have been added to orchestrate agent tool calls and manage asynchronous execution context, respectively.
• Comprehensive Testing: New unit tests were added for the agent-scheduler helper and ToolCallContext propagation, alongside updates to existing LocalAgentExecutor and Scheduler tests to validate the new architecture.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-cli]

Hi @abhipatel12, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[gemini-code-assist]

Code Review

This pull request successfully migrates subagents to use the new event-driven Scheduler and introduces AsyncLocalStorage-based ToolCallContext for propagating callId, schedulerId, and origin across tool validation and execution. The changes are well-implemented, with appropriate refactoring in local-executor.ts and corresponding updates in test files. The new agent-scheduler.ts and toolCallContext.ts files provide the necessary abstractions and utilities for this migration. The tests for these new components are comprehensive and cover the intended functionality, including context propagation and parallel execution isolation.

[github-actions]

Size Change: +2.55 kB (+0.01%)

Total Size: 23.4 MB

Filename	Size	Change
./bundle/gemini.js	23.3 MB	+2.55 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[gundermanc]

LGTM

[abhipatel12]

Thanks for the review!