docs(core): add subagent tool isolation draft doc#23275
Conversation
|
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! |
Summary of ChangesHello, I'm Gemini Code Assist1! 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 introduces comprehensive documentation for the "Subagent Tool Isolation" feature in Gemini CLI. This feature significantly enhances the security and stability of subagents by enabling them to operate within isolated execution environments. It provides mechanisms for subagents to declare their own tools and inline MCP servers, and allows for granular, subagent-specific policy enforcement, thereby preventing unintended interactions and improving overall system reliability. Highlights
Using Gemini Code AssistThe 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
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 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
|
|
Size Change: -4 B (0%) Total Size: 34.6 MB
ℹ️ View Unchanged
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This PR adds a new documentation file, docs/core/subagent-tool-isolation-draft.md, which comprehensively explains the subagent tool isolation feature in Gemini CLI. The document covers configuration, policies, architecture, and user experience improvements. The review identified a high severity issue regarding clarity on MCP and a critical issue with an incorrect TOML example, both of which have been retained.
Note: Security Review has been skipped due to the limited scope of the PR.
| ```toml | ||
| [[rules]] | ||
| name = "Allow docs-writer to read docs" | ||
| subagent = "docs-writer" | ||
| description = "Permit reading files in the docs directory." | ||
| action = "allow" | ||
| tools = ["read_file"] | ||
| args = { file_path = "^docs/.*" } | ||
| ``` |
There was a problem hiding this comment.
The TOML example lacks a [[rules]] block name, which is required. This could lead to confusion and incorrect policy configurations. The example should be corrected to include the [[rules]] block name.
| ```toml | |
| [[rules]] | |
| name = "Allow docs-writer to read docs" | |
| subagent = "docs-writer" | |
| description = "Permit reading files in the docs directory." | |
| action = "allow" | |
| tools = ["read_file"] | |
| args = { file_path = "^docs/.*" } | |
| ``` | |
| [[rules]] | |
| name = "Allow docs-writer to read docs" | |
| subagent = "docs-writer" | |
| description = "Permit reading files in the docs directory." | |
| action = "allow" | |
| tools = ["read_file"] | |
| args = { file_path = "^docs/.*" } |
There was a problem hiding this comment.
The name attribute is already present in the TOML example.
|
|
||
| Subagent tool isolation moves Gemini CLI away from a single global tool | ||
| registry. Previously, subagents shared the same tool instances as the main | ||
| agent. This caused state leakage and prevented you from defining agent-specific |
There was a problem hiding this comment.
The description mentions integration via MCP (Model Context Protocol). It would be helpful to briefly define MCP here, as some readers may not be familiar with it. This is especially important given the document focuses on MCP server configurations.
There was a problem hiding this comment.
Good point. I have added a brief explanation of MCP in the overview section where it is first mentioned.
gemini-cli
bot
added
area/agent
abhipatel12
left a comment
abhipatel12
left a comment
There was a problem hiding this comment.
Left a few commnents, lmk what you think
docs/core/subagents.md
Outdated
| (which provide a standardized way to connect AI models to external tools and | ||
| data sources) directly in the subagent's markdown frontmatter, isolating them | ||
| to that specific agent. | ||
| - **Maintain state isolation:** Use an isolated `MessageBus` for communication, |
There was a problem hiding this comment.
This is an impl detail. We don't need this in the public documentation
There was a problem hiding this comment.
Done. I've removed the MessageBus implementation details.
docs/core/subagents.md
Outdated
| - **Maintain state isolation:** Use an isolated `MessageBus` for communication, | ||
| as tools are cloned for each subagent. | ||
| - **Apply subagent-specific policies:** Enforce granular policy rules based on | ||
| the executing subagent's name using TOML configuration. |
There was a problem hiding this comment.
Let's make it clear that this is talking about the policy engine / policy toml files
There was a problem hiding this comment.
Done. I've updated the terminology to explicitly reference the Policy Engine and TOML files.
| To restrict a policy rule to a specific subagent, add the `subagent` property to | ||
| the `[[rules]]` block in your `policy.toml` file. | ||
|
|
||
| **Example:** |
There was a problem hiding this comment.
Should we use a different example? Isn't the read tool default allow already?
There was a problem hiding this comment.
Good point. I've updated the example to use run_shell_command with git push to demonstrate a more practical use case for restricting a tool.
| --- | ||
| ``` | ||
|
|
||
| ### Subagent-specific policies |
There was a problem hiding this comment.
@jkcinouye Is the expert here, but should we put this in the policy section and link there with some short example, or link from the policy docs to this section?
There was a problem hiding this comment.
I've added a link from this section directly to the Policy Engine reference to tie them together.
docs/core/subagents.md
Outdated
|
|
||
| In this configuration, the policy rule only triggers if the executing subagent's | ||
| name matches `docs-writer`. Rules without the `subagent` property apply | ||
| universally to all agents. The `LocalAgentExecutor` automatically injects the |
There was a problem hiding this comment.
Let's avoid implementation details like this.
docs/core/subagents.md
Outdated
| subagent's context into the tool execution flow to ensure accurate policy | ||
| enforcement. | ||
|
|
||
| ### How it works |
There was a problem hiding this comment.
This entire section feels like a lot of technical details that are not entirely necessary for users that want to configure subagents. Maybe we can track this in the future for a architecture style doc.
There was a problem hiding this comment.
Agreed, I've removed the 'How it works' section entirely to keep this focused on user configuration.
- Remove MessageBus and LocalAgentExecutor implementation details from subagents.md - Clarify TOML terminology in policy-engine.md - Update quick start example to use rm -rf for better clarity - Update subagent example to codebase_investigator
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
Co-authored-by: Abhi <43648792+abhipatel12@users.noreply.github.com>
Co-authored-by: Abhi <43648792+abhipatel12@users.noreply.github.com>
Co-authored-by: Abhi <43648792+abhipatel12@users.noreply.github.com>
Co-authored-by: Abhi <43648792+abhipatel12@users.noreply.github.com>
3 participants
Summary
This PR introduces a draft documentation file for the new "Subagent Tool Isolation" feature. It consolidates the behavior, architecture, and user experience improvements shipped across PRs #21935, #22708, #22712, #22718, and #21431.
Details
The document,
docs/core/subagent-tool-isolation-draft.md, provides a comprehensive overview of how subagents can now define their own tools and inline MCP servers in their frontmatter. It also covers the multi-registry architecture for state isolation and the new TOML-based granular policy enforcement per subagent.Related Issues
Related to #21935, #22708, #22712, #22718, #21431.
How to Validate
Read the newly added
docs/core/subagent-tool-isolation-draft.mdfile and verify it aligns with the expected format and content.Pre-Merge Checklist