Tool Scoping for Sub-Agents

### Describe the feature or problem you'd like to solve

**Product:** GitHub Copilot CLI (Agent Mode) **Type:** Feature Request **Priority:** Medium --- ## Summary When spawning a sub-agent via the `task` tool, the sub-agent inherits the **full tool set** registered in the parent session. There is no mechanism to restrict which tools are passed to the sub-agent. This causes sub-agent spawning to fail entirely when the environment has a large number of MCP tools registered and the target model has a tool count limit. --- ## Problem In enterprise environments, multiple MCP servers are typically registered simultaneously — for example: - Azure DevOps MCP (ADO) - Confluence MCP - MSSQL MCP - GitHub MCP - Custom agent tools This results in **150+ tools** being registered in a single session. When spawning a sub-agent targeting `gpt-4.1`, the platform passes **all 150+ tools** to the sub-agent. GPT-4.1 has a hard API limit of approximately **128 tools per request**. The result is an immediate rejection: ``` Error: tool count exceeded limit (151 > 128) ``` The sub-agent fails to spawn entirely, even if its actual task requires only 5–6 tools (e.g., `grep`, `view`, `edit`, `create`, `glob` for wiki/catalog work). --- ## Impact 1. **Model choice is constrained.** `gpt-4.1` is the preferred model for deterministic, low-cost tasks (catalog sweeps, file transforms, registry updates) because it is free in this environment and has a 1M token context. The tool count limit makes it completely unusable as a sub-agent in any environment with many MCP servers. 2. **Cost increases.** The fallback is `claude-haiku-4.5`, which works but costs ~$0.005/sweep. At scale across many agents and sessions, this adds up unnecessarily. 3. **Workarounds are fragile.** Unregistering MCP servers before spawning a sub-agent is impractical — it affects the entire session and requires manual reconfiguration.

### Proposed solution

Add an optional `allowed_tools` parameter to the `task` tool that lets the caller explicitly scope which tools are passed to the sub-agent:

```json
task(
agent_type: "general-purpose",
model: "gpt-4.1",
allowed_tools: ["grep", "glob", "view", "edit", "create", "powershell"],
prompt: "..."
)
```

**Behavior:**
- If `allowed_tools` is provided → only those tools are passed to the sub-agent
- If `allowed_tools` is omitted → current behavior (full tool inheritance) is preserved
- Unknown tool names in `allowed_tools` are silently ignored (no error)
---

## Alternative Solutions

**Option A — Tool category groups**
Instead of listing individual tools, allow grouping:
```json
allowed_tool_groups: ["filesystem", "search"]
```
Where `filesystem` = `view`, `edit`, `create` and `search` = `grep`, `glob`.

**Option B — Tool exclusion list**
Instead of allowlist, provide a denylist:
```json
excluded_tools: ["ADO-MCP-*", "ATLASSIAN-MCP-*", "MSSQL-MCP-*"]
```
Useful when most tools are needed but specific MCP servers should be excluded.

**Option C — Model-aware automatic trimming**
Platform automatically trims tools to fit the target model's limit, prioritizing built-in tools over MCP tools when a cut is needed.

Of these, **Option A (allowlist)** is recommended as the primary solution — it gives the caller precise control and makes the sub-agent's capability surface explicit and auditable.

---

## Acceptance Criteria

- [ ] `task` tool accepts an optional `allowed_tools` parameter (array of tool name strings)
- [ ] Sub-agent receives only the listed tools when `allowed_tools` is specified
- [ ] Sub-agent spawning with `allowed_tools: ["grep", "glob", "view", "edit", "create"]` succeeds against `gpt-4.1` in an environment with 150+ registered tools
- [ ] Omitting `allowed_tools` preserves existing full-inheritance behavior (no breaking change)
- [ ] Documentation updated for `task` tool parameters

---

## Environment Details

- **Copilot CLI version:** 1.0.35
- **Primary model:** Claude Sonnet 4.6
- **MCP servers registered:** ADO-MCP, ATLASSIAN-MCP (Confluence), MSSQL-MCP, github-mcp-server + custom tools
- **Total tools in session:** ~151
- **Affected model:** `gpt-4.1` (128-tool limit)
- **Workaround in use:** Fall back to `claude-haiku-4.5` for all sub-agent catalog/wiki work

---

## References

- GPT-4.1 tool limit: [OpenAI API documentation — function calling limits]
- Catalog skill pattern: uses only 6 tools (`grep`, `glob`, `view`, `edit`, `create`, `powershell`) but cannot use `gpt-4.1` due to this constraint

[copilot-cli-feature-request-tool-scoping-sub-agents.md](https://github.com/user-attachments/files/27115895/copilot-cli-feature-request-tool-scoping-sub-agents.md)

### Example prompts or workflows

_No response_

### Additional context

_No response_

从 task tool 的入口点及其参数文档开始；issue 没有指出具体的实现文件或测试。跟踪启动 sub-agent 时工具的继承方式，然后为 allowlist 中的工具、省略 allowlist 以及未知名称添加覆盖。完成的标准是：列出的工具被传递下去，现有的继承保持不变，并更新 task 文档。

由索引模型根据 Issue 内容生成。