feat(core): refactor subagent tool to unified invoke_subagent tool

[abhipatel12]

Summary

Refactors specialized subagent tools into a single, unified invoke_agent tool and updates the Policy Engine to support virtual tool aliases for subagents.

Details

• Unified Tooling: Introduced invoke_agent in packages/core as the standard mechanism for subagent delegation, replacing the previous 1:1 tool-to-agent mapping.
• Policy Engine Enhancement: Updated PolicyEngine to automatically treat the agent_name argument of invoke_agent as a virtual tool name. This ensures that existing safety policies (e.g., denying codebase_investigator) remain functional without requiring rule updates.
• Prompt Refactoring: Updated both modern and legacy prompt snippets to instruct the model to use invoke_agent.
• Testing: Added unit tests in policy-engine.test.ts for virtual alias matching and updated subagents.eval.ts to verify successful delegation via the new unified tool.
• Documentation: Updated subagents.md and policy-engine.md to reflect the new invocation pattern and policy syntax.

Related Issues

Related to the effort of simplifying the main agent's toolset and improving context efficiency.

How to Validate

1. Unit Tests: Run npm test -w @google/gemini-cli-core to verify Policy Engine and prompt rendering logic.
2. Evals: Run npm run test:evals -- subagents.eval.ts to ensure the model correctly uses the unified tool for delegation.
3. Policy Verification:
   • Create a local policy denying a specific subagent (e.g., codebase_investigator).
   • Verify that calling invoke_agent with that agent_name results in a DENY decision.

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

[github-actions]

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• 🚀 Maintainer Reminder: Please ensure that these changes do not regress results on benchmark evals before merging.

---

This is an automated guidance message triggered by steering logic signatures.

[github-actions]

Size Change: -1.92 kB (-0.01%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-42YNSZXF.js	0 B	-3.47 kB (removed)	🏆
./bundle/chunk-LEXYTOZN.js	0 B	-14.8 MB (removed)	🏆
./bundle/chunk-OGWWODAT.js	0 B	-1.96 MB (removed)	🏆
./bundle/chunk-XRUV2WUR.js	0 B	-3.16 MB (removed)	🏆
./bundle/core-2FQGKLRS.js	0 B	-45.4 kB (removed)	🏆
./bundle/devtoolsService-HYIF5EJM.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-AJUBQKT5.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-AW6L7ZLZ.js	0 B	-1.64 MB (removed)	🏆
./bundle/oauth2-provider-KDW6YRJD.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-ETSDHTGW.js	1.96 MB	+1.96 MB (new file)	🆕
./bundle/chunk-I7BVQN23.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-JN2NXI7I.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/chunk-KDH4ZJTL.js	3.47 kB	+3.47 kB (new file)	🆕
./bundle/core-OWPXSLFR.js	45.5 kB	+45.5 kB (new file)	🆕
./bundle/devtoolsService-6WBSI2RZ.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-YFPWJU2S.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-2JAEDH34.js	1.64 MB	+1.64 MB (new file)	🆕
./bundle/oauth2-provider-LJ6TOOHQ.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-EFS577AW.js	0 B	-856 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/gemini.js	4.97 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-JNNGTYL3.js	0 B	-980 B (removed)	🏆
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-JJBCQN4X.js	856 B	+856 B (new file)	🆕
./bundle/memoryDiscovery-YL35JRSL.js	980 B	+980 B (new file)	🆕

_{compressed-size-action}

[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 refactors the subagent delegation mechanism by introducing a unified invoke_agent tool. This change simplifies the agent's toolset and improves context efficiency. The Policy Engine has been updated to support virtual tool aliases, allowing existing safety rules to continue functioning without modification. Documentation, prompts, and test suites have been updated to align with this new architectural approach.

Highlights

• Unified Subagent Invocation: Replaced specialized subagent tools with a single, unified invoke_agent tool to streamline delegation.
• Policy Engine Enhancement: Updated the Policy Engine to treat the agent_name argument of invoke_agent as a virtual tool alias, ensuring existing safety policies remain effective.
• Prompt and Documentation Updates: Refactored system prompts and documentation to reflect the new invocation pattern and policy syntax.
• Testing and Evals: Added comprehensive unit tests and updated evaluation scripts to verify the new delegation mechanism and policy enforcement.

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.

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-code-assist]

Code Review

This pull request refactors the subagent invocation mechanism by replacing individual subagent tools with a unified 'AgentTool'. This change simplifies agent management, updates the system prompts to reflect the new invocation syntax, and ensures policy engine compatibility by treating subagent names as virtual tool aliases. I have identified two high-severity issues: an inconsistency in parameter mapping between 'mapParams' and 'withUserHints' that could cause subagent failures, and a missing registry re-initialization in 'onAgentsRefreshed' that prevents dynamic subagent updates.

[abhipatel12]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors subagent invocation by introducing a unified AgentTool (invoke_agent), replacing the previous system of registering each subagent as a separate tool. The changes include updates to the policy engine to support subagent-specific rules via virtual tool aliases, documentation for TOML-based safety policies, and comprehensive updates to system prompts and test suites. Review feedback identifies several critical issues: the parameter mapping logic in AgentTool is fragile when handling multiple input properties, certain properties in DelegateInvocation are inaccessible or undefined, user steering hints are unnecessarily restricted to remote agents, and a potential race condition exists in the AgentRegistry initialization logic.

[github-actions]

✅ 64 tests passed successfully on gemini-3-flash-preview.

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• 🚀 Maintainer Reminder: Please ensure that these changes do not regress results on benchmark evals before merging.

---

This is an automated guidance message triggered by steering logic signatures.

[abhipatel12]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a unified invoke_agent tool to replace individual subagent tools, streamlining agent orchestration and policy management. The changes include the new AgentTool implementation, updates to the AgentRegistry for dynamic policy generation, and extensive modifications to system prompts and integration tests to support the new tool-based invocation. I have identified two high-severity issues: a potential race condition in AgentRegistry.loadAgents during asynchronous reloads and a fragile parameter mapping logic in AgentTool.mapParams that could lead to runtime validation failures for subagents with complex schemas.

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

[gundermanc]

Is this a behavior change?

[abhipatel12]

No. The agents.toml now handles the general policy. Only specifically remote agents require ask permission. This was the case before. Before since we didn't have a single tool we couldnt add a blanket policy in the bundled policy files. We had this before when we originally had the delegation tool but was removed when we switched to 1:1.