# Subagent 工具范围与策略

> 区分工具继承、专用 MCP、代理入口和内部调用者约束。

- 网址：https://funcoding.ai/agents/gemini-cli/build/subagent-policies/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：Subagents](https://geminicli.com/docs/core/subagents)、[Gemini CLI 官方文档：Policy engine](https://geminicli.com/docs/reference/policy-engine)、[官方 TOML 解析器（固定 revision）](https://github.com/google-gemini/gemini-cli/blob/ef59c532f07fbb3a58dd68bac024ae217e9c73ce/packages/core/src/policy/toml-loader.ts)

---
Subagent 有独立历史和工具注册范围。它不自动拥有操作系统级隔离，也不因独立上下文就免受普通工具策略约束。

## 工具继承与通配符

tools 省略时继承父会话全部工具；显式列表可缩小范围。支持 `*`（全部可用工具）、`mcp_*`（全部 MCP）和 `mcp_my-server_*`（指定服务）。官方同时说明 subagent 不能调用其他 subagent，即使使用 `*` 也不开放代理递归。

将 mcpServers 放进代理 frontmatter 可定义该代理专用服务。官方短示例省略必需 description；实际文件应保留[定义页](https://funcoding.ai/agents/gemini-cli/build/custom-subagents/)列出的必需元数据。

## 控制代理入口

主 Agent 调用 invoke_agent 时，agent_name 会作为虚拟工具名称参与策略。例如禁止某个内置代理：

```toml
[[rule]]
toolName = "codebase_investigator"
decision = "deny"
priority = 500
denyMessage = "This agent is disabled for the current workflow."
```

这是限制是否进入该代理，与限制代理内部 Shell 操作不同。

## 控制代理内部操作

```toml
[[rule]]
subagent = "code-auditor"
toolName = "run_shell_command"
decision = "deny"
priority = 500
denyMessage = "The auditor must use read-only inspection tools."
```

subagent 是调用者条件；未写该条件的规则普遍适用。仍需考虑更高层策略和匹配优先级。

## 官方示例差异

Subagents 专页有 `[[rules]]`、action 的旧策略示例，以及缺少 priority 的拒绝示例；当前 Policy Engine 和固定解析器要求 `[[rule]]`、decision 和 0–999 priority。本页使用核实后的字段，deny_message 兼容旧格式但新规则用 denyMessage。

## 验证结果

先看代理可见的工具与专用服务，再验证被拒绝调用的反馈。不要仅因正文说“只读”就认定 Shell 不可用，也不要把独立历史当成独立文件系统。