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_

Start at the task tool entry point and its parameter documentation; the issue does not identify specific implementation files or tests. Trace how tools are inherited when a sub-agent is spawned, then add coverage for allowlisted tools, omitted allowlists, and unknown names. Done means the listed tools are passed through, existing inheritance remains unchanged, and the task documentation is updated.

Escrita pelo modelo de indexação a partir do texto da issue.