From d9d51ba15b3c0d61d51278f66696335d79e744b7 Mon Sep 17 00:00:00 2001 From: AK Date: Wed, 1 Apr 2026 11:45:21 -0700 Subject: [PATCH] docs(core): add subagent tool isolation draft doc (#23275) Co-authored-by: Abhi <43648792+abhipatel12@users.noreply.github.com> --- docs/core/subagents.md | 73 +++++++++++++++++++++++++++++++++ docs/reference/policy-engine.md | 32 +++++++-------- 2 files changed, 89 insertions(+), 16 deletions(-) diff --git a/docs/core/subagents.md b/docs/core/subagents.md index 70c6f9d7e5..a789e0f741 100644 --- a/docs/core/subagents.md +++ b/docs/core/subagents.md @@ -332,6 +332,7 @@ it yourself; just report it. | `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this subagent. | | `kind` | string | No | `local` (default) or `remote`. | | `tools` | array | No | List of tool names this agent can use. Supports wildcards: `*` (all tools), `mcp_*` (all MCP tools), `mcp_server_*` (all tools from a server). **If omitted, it inherits all tools from the parent session.** | +| `mcpServers` | object | No | Configuration for inline Model Context Protocol (MCP) servers isolated to this specific agent. | | `model` | string | No | Specific model to use (e.g., `gemini-3-preview`). Defaults to `inherit` (uses the main session model). | | `temperature` | number | No | Model temperature (0.0 - 2.0). Defaults to `1`. | | `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `30`. | @@ -359,6 +360,78 @@ Each subagent runs in its own isolated context loop. This means: subagents **cannot** call other subagents. If a subagent is granted the `*` tool wildcard, it will still be unable to see or invoke other agents. +## Subagent tool isolation + +Subagent tool isolation moves Gemini CLI away from a single global tool +registry. By providing isolated execution environments, you can ensure that +subagents only interact with the parts of the system they are designed for. This +prevents unintended side effects, improves reliability by avoiding state +contamination, and enables fine-grained permission control. + +With this feature, you can: + +- **Specify tool access:** Define exactly which tools an agent can access using + a `tools` list in the agent definition. +- **Define inline MCP servers:** Configure Model Context Protocol (MCP) servers + (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:** Ensure that subagents only interact with their + own set of tools and servers, preventing side effects and state contamination. +- **Apply subagent-specific policies:** Enforce granular rules in your + [Policy Engine](../reference/policy-engine.md) TOML configuration based on the + executing subagent's name. + +### Configuring isolated tools and servers + +You can configure tool isolation for a subagent by updating its markdown +frontmatter. This allows you to explicitly state which tools the subagent can +use, rather than relying on the global registry. + +Add an `mcpServers` object to define inline MCP servers that are unique to the +agent. + +**Example:** + +```yaml +--- +name: my-isolated-agent +tools: + - grep_search + - read_file +mcpServers: + my-custom-server: + command: 'node' + args: ['path/to/server.js'] +--- +``` + +### Subagent-specific policies + +You can enforce fine-grained control over subagents using the +[Policy Engine's](../reference/policy-engine.md) TOML configuration. This allows +you to grant or restrict permissions specifically for an agent, without +affecting the rest of your CLI session. + +To restrict a policy rule to a specific subagent, add the `subagent` property to +the `[[rules]]` block in your `policy.toml` file. + +**Example:** + +```toml +[[rules]] +name = "Allow pr-creator to push code" +subagent = "pr-creator" +description = "Permit pr-creator to push branches automatically." +action = "allow" +toolName = "run_shell_command" +commandPrefix = "git push" +``` + +In this configuration, the policy rule only triggers if the executing subagent's +name matches `pr-creator`. Rules without the `subagent` property apply +universally to all agents. + ## Managing subagents You can manage subagents interactively using the `/agents` command or diff --git a/docs/reference/policy-engine.md b/docs/reference/policy-engine.md index bb00f30f77..597e74f111 100644 --- a/docs/reference/policy-engine.md +++ b/docs/reference/policy-engine.md @@ -29,13 +29,12 @@ To create your first policy: ```toml [[rule]] toolName = "run_shell_command" - commandPrefix = "git status" - decision = "allow" + commandPrefix = "rm -rf" + decision = "deny" priority = 100 ``` 3. **Run a command** that triggers the policy (e.g., ask Gemini CLI to - `git status`). The tool will now execute automatically without prompting for - confirmation. + `rm -rf /`). The tool will now be blocked automatically. ## Core concepts @@ -143,25 +142,26 @@ engine transforms this into a final priority using the following formula: This system guarantees that: -- Admin policies always override User, Workspace, and Default policies. +- Admin policies always override User, Workspace, and Default policies (defined + in policy TOML files). - User policies override Workspace and Default policies. - Workspace policies override Default policies. - You can still order rules within a single tier with fine-grained control. For example: -- A `priority: 50` rule in a Default policy file becomes `1.050`. -- A `priority: 10` rule in a Workspace policy policy file becomes `2.010`. -- A `priority: 100` rule in a User policy file becomes `3.100`. -- A `priority: 20` rule in an Admin policy file becomes `4.020`. +- A `priority: 50` rule in a Default policy TOML becomes `1.050`. +- A `priority: 10` rule in a Workspace policy TOML becomes `2.010`. +- A `priority: 100` rule in a User policy TOML becomes `3.100`. +- A `priority: 20` rule in an Admin policy TOML becomes `4.020`. ### Approval modes Approval modes allow the policy engine to apply different sets of rules based on -the CLI's operational mode. A rule can be associated with one or more modes -(e.g., `yolo`, `autoEdit`, `plan`). The rule will only be active if the CLI is -running in one of its specified modes. If a rule has no modes specified, it is -always active. +the CLI's operational mode. A rule in a TOML policy file can be associated with +one or more modes (e.g., `yolo`, `autoEdit`, `plan`). The rule will only be +active if the CLI is running in one of its specified modes. If a rule has no +modes specified, it is always active. - `default`: The standard interactive mode where most write tools require confirmation. @@ -179,8 +179,8 @@ outcome. A rule matches a tool call if all of its conditions are met: -1. **Tool name**: The `toolName` in the rule must match the name of the tool - being called. +1. **Tool name**: The `toolName` in the TOML rule must match the name of the + tool being called. - **Wildcards**: You can use wildcards like `*`, `mcp_server_*`, or `mcp_*_toolName` to match multiple tools. See [Tool Name](#tool-name) for details. @@ -264,7 +264,7 @@ toolName = "run_shell_command" # (Optional) The name of a subagent. If provided, the rule only applies to tool # calls made by this specific subagent. -subagent = "generalist" +subagent = "codebase_investigator" # (Optional) The name of an MCP server. Can be combined with toolName # to form a composite FQN internally like "mcp_mcpName_toolName".