feat(core): multi-registry architecture and tool filtering for subagents

[akh64bit]

Summary

This PR is part 2 of the subagent tool isolation rollout. It refactors the MCP and ToolRegistry architecture to support maintaining multiple discrete environments (i.e. isolated sets of tools, prompts, and resources) simultaneously rather than relying exclusively on a single global registry.

Details

• Multi-Registry Architecture: Modified McpClient and McpClientManager to support discovering and updating an arbitrary set of RegistrySet instances (toolRegistry, promptRegistry, resourceRegistry).
• Tool Filtering: Added mainAgentTools to Config and integrated it into ToolRegistry.getActiveTools() so that the main agent can correctly filter its tools when isolated environments are active.
• Bridge to Execution: This safely lays the plumbing for subagents to connect their isolated tool instances directly into the McpClientManager. Since only "main" registries are connected in this step, there is no change to main's runtime execution behavior.

Child of: #22708

Related Issues

Fixes #21901

How to Validate

• Run npm run typecheck and npm run test to verify no regressions in the MCP discovery or tool registry flows.

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:

[gemini-cli]

Hi @akh64bit, 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]

Summary of Changes

Hello, 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 system's ability to manage isolated tool environments, which is crucial for the subagent tool isolation initiative. By introducing a multi-registry architecture and refined tool filtering mechanisms, it provides the foundational components necessary for more complex agent interactions and resource management without altering the main agent's current operational behavior.

Highlights

• Multi-Registry Architecture: The core architecture of McpClient and McpClientManager has been refactored to support managing multiple distinct RegistrySet instances (tool, prompt, and resource registries) simultaneously, moving away from a single global registry.
• Tool Filtering for Main Agent: A new mainAgentTools configuration option has been introduced and integrated into ToolRegistry.getActiveTools(). This allows the main agent to correctly filter its available tools when isolated environments are active, ensuring proper tool isolation.
• Subagent Plumbing: The changes lay the groundwork for subagents to connect their isolated tool instances directly into the McpClientManager. While current execution behavior for the main agent remains unchanged, this PR establishes the necessary infrastructure for future subagent integration.
• McpClientManager Refactoring: The McpClientManager constructor no longer directly accepts a ToolRegistry, instead relying on a new setMainRegistries method to provide the main registries. This decouples the manager from specific registry implementations and allows for dynamic registry assignment.
• Dynamic Client Key Generation: A getClientKey method was added to McpClientManager to generate a stable, unique key for each MCP client based on its name and configuration. This improves the handling of hot-reloading and configuration updates for MCP servers.

Changelog

• packages/core/src/config/config.test.ts
  • Added setMainRegistries mock to McpClientManager for testing purposes.
• packages/core/src/config/config.ts
  • Extended AgentOverride interface with optional tools and mcpServers properties.
  • Introduced mainAgentTools property to ConfigParameters and the Config class.
  • Modified McpClientManager instantiation to remove direct toolRegistry dependency and added a call to setMainRegistries.
  • Updated createToolRegistry to pass an isMainRegistry flag to the ToolRegistry constructor.
  • Added getMainAgentTools getter method to the Config class.
• packages/core/src/tools/mcp-client-manager.test.ts
  • Updated imports to include PromptRegistry and ResourceRegistry types.
  • Refined mocks for McpClient and Config to support new registry interactions and methods.
  • Introduced a setupManager helper function to configure McpClientManager with main registries.
  • Adjusted McpClientManager constructor calls to align with the new signature.
  • Replaced mockedMcpClient.discover calls with mockedMcpClient.discoverInto.
• packages/core/src/tools/mcp-client-manager.ts
  • Added imports for createHash and stableStringify for client key generation.
  • Removed toolRegistry from the constructor and introduced mainToolRegistry, mainPromptRegistry, and mainResourceRegistry properties.
  • Implemented setMainRegistries method to assign the main registries.
  • Added removeRegistries method to allow clients to unregister from registries.
  • Modified disconnectClient to use a unique clientKey for client identification.
  • Introduced getClientKey method to generate a stable hash for each client based on its configuration.
  • Updated maybeDiscoverMcpServer to accept an optional registries parameter and include logic for hot-reloading based on clientKey changes.
  • Refactored restart and restartServer methods to use the new disconnectClient logic with clientKey.
  • Adjusted getMcpInstructions to iterate over McpClient instances directly.
• packages/core/src/tools/mcp-client.test.ts
  • Added eslint-disable comment for any types.
  • Updated McpClient constructor calls in tests to remove direct registry parameters.
  • Modified client.discover calls to client.discoverInto and passed a RegistrySet object.
  • Injected registeredRegistries into McpClient instances in tests for notification handling.
• packages/core/src/tools/mcp-client.ts
  • Defined RegistrySet interface to group tool, prompt, and resource registries.
  • Added registeredRegistries as a Set<RegistrySet> to track all registries this client updates.
  • Removed direct toolRegistry, promptRegistry, and resourceRegistry parameters from the constructor.
  • Added getServerName getter method.
  • Renamed discover method to discoverInto and updated its signature to accept a RegistrySet.
  • Implemented removeRegistries method to remove a RegistrySet from tracking.
  • Modified disconnect to iterate over all registeredRegistries to remove server-specific items.
  • Updated discoverTools to accept a MessageBus parameter.
  • Modified updateResourceRegistry to accept a ResourceRegistry parameter.
  • Refactored resource, prompt, and tool refresh logic to iterate over registeredRegistries and update each one.
• packages/core/src/tools/tool-registry.test.ts
  • Added a new test suite for removeMcpToolsByServer to verify its functionality.
• packages/core/src/tools/tool-registry.ts
  • Added an isMainRegistry property to the ToolRegistry constructor, defaulting to false.
  • Modified getFunctionDeclarations to filter tools based on mainAgentTools from the Config if isMainRegistry is true.

Activity

• The pull request introduces a multi-registry architecture and tool filtering, building on a previous subagent tool isolation rollout.
• The author has added/updated tests to verify no regressions in MCP discovery or tool registry flows.
• The changes are described as laying the plumbing for subagents to connect isolated tool instances, indicating a phased development approach.

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. ↩

[github-actions]

Size Change: +3.85 kB (+0.01%)

Total Size: 26.1 MB

Filename	Size	Change
./bundle/chunk-3L6CEJVG.js	0 B	-13.4 MB (removed)	🏆
./bundle/chunk-R7TVLWCZ.js	0 B	-3.62 MB (removed)	🏆
./bundle/core-SH3JEUHZ.js	0 B	-40.4 kB (removed)	🏆
./bundle/devtoolsService-B633A34M.js	0 B	-27.7 kB (removed)	🏆
./bundle/interactiveCli-A5F6KV27.js	0 B	-1.6 MB (removed)	🏆
./bundle/oauth2-provider-JVQ634EA.js	0 B	-9.19 kB (removed)	🏆
./bundle/chunk-HXMLZHYR.js	13.4 MB	+13.4 MB (new file)	🆕
./bundle/chunk-U5YX6IQD.js	3.62 MB	+3.62 MB (new file)	🆕
./bundle/core-TTPAJGCL.js	40.4 kB	+40.4 kB (new file)	🆕
./bundle/devtoolsService-XWAS4ICS.js	27.7 kB	+27.7 kB (new file)	🆕
./bundle/interactiveCli-6TAJSKM4.js	1.6 MB	+1.6 MB (new file)	🆕
./bundle/oauth2-provider-EGPOJ2PF.js	9.19 kB	+9.19 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size
./bundle/chunk-34MYV7JD.js	2.45 kB
./bundle/chunk-37ZTTFQF.js	966 kB
./bundle/chunk-5AUYMPVF.js	858 B
./bundle/chunk-664ZODQF.js	124 kB
./bundle/chunk-DAHVX5MI.js	206 kB
./bundle/chunk-IUUIT4SU.js	56.5 kB
./bundle/chunk-M7VDGI6V.js	1.95 MB
./bundle/chunk-RJTRUG2J.js	39.8 kB
./bundle/devtools-36NN55EP.js	696 kB
./bundle/dist-T73EYRDX.js	356 B
./bundle/gemini.js	695 kB
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB
./bundle/memoryDiscovery-ZHYVZFWT.js	922 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB
./bundle/src-QVCVGIUX.js	47 kB
./bundle/tree-sitter-7U6MW5PS.js	274 kB
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB
./bundle/undici-4X2YZID5.js	360 B

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed refactoring to support a multi-registry architecture for subagents with isolated toolsets. The changes to McpClientManager and McpClient, particularly the use of a clientKey to manage multiple client instances, are a solid approach. The addition of mainAgentTools for filtering the main agent's tools is also a good enhancement. The changes are logical and the tests have been updated appropriately.

_{Note: Security Review did not run due to the size of the PR.}

[abhipatel12]

lgtm