Summary
When custom agents defined in a plugin (via .github/agents/*.agent.md) are invoked as sub-agents through the task tool, the CLI runtime provisions a restricted tool set that ignores the tools: frontmatter declared in the agent file.
This means sub-agents that are designed to create files (e.g. writing review reports, creating proposal documents) cannot do their job when running in the CLI — even though they work fine in VS Code where the tools: frontmatter is respected.
Current behaviour
| Agent declaration |
Tools in VS Code |
Tools in CLI (sub-agent) |
tools: [read, search, edit, execute/sendToTerminal, agent, web] |
All declared tools |
view, task, apply_patch |
tools: [read, search, web, edit/editFiles, agent] |
All declared tools |
view only |
tools: [read, search, web, edit/editFiles] |
All declared tools |
view, edit (existing files only) |
The CLI appears to assign tools based on internal logic rather than respecting the plugin agent's declared requirements.
Proposed solution
Allow plugins to declare tool requirements for their agents that the CLI respects when spawning them as sub-agents. For example, in the agent frontmatter or in plugin.json:
---
tools: [read, search, edit, execute/sendToTerminal, agent, web]
cli-tools: [view, edit, create, bash, apply_patch, task] # tools required in CLI runtime
---
Or in plugin.json:
{
"agents": {
"review": {
"path": ".github/agents/review.agent.md",
"tools": ["view", "edit", "create", "bash", "apply_patch", "task"]
}
}
}
Why this matters
Framework authors building multi-agent workflows (e.g. execute → review → architecture-review → security-review) need sub-agents to persist artifacts (review reports, proposal files). Without write tools, sub-agents must return content in their response text and rely on the calling agent to persist it — adding fragility, complexity, and token overhead to the workflow.
Tested on
- Copilot CLI v1.0.53
- macOS (darwin-arm64)
- Plugin-based custom agents invoked via the
task tool
Workaround
Sub-agents detect whether write tools are available. If not, they return file content and intended paths in their response. The nearest parent agent with write capability persists the artifacts on their behalf.
Summary
When custom agents defined in a plugin (via
.github/agents/*.agent.md) are invoked as sub-agents through thetasktool, the CLI runtime provisions a restricted tool set that ignores thetools:frontmatter declared in the agent file.This means sub-agents that are designed to create files (e.g. writing review reports, creating proposal documents) cannot do their job when running in the CLI — even though they work fine in VS Code where the
tools:frontmatter is respected.Current behaviour
tools: [read, search, edit, execute/sendToTerminal, agent, web]view,task,apply_patchtools: [read, search, web, edit/editFiles, agent]viewonlytools: [read, search, web, edit/editFiles]view,edit(existing files only)The CLI appears to assign tools based on internal logic rather than respecting the plugin agent's declared requirements.
Proposed solution
Allow plugins to declare tool requirements for their agents that the CLI respects when spawning them as sub-agents. For example, in the agent frontmatter or in
plugin.json:Or in
plugin.json:{ "agents": { "review": { "path": ".github/agents/review.agent.md", "tools": ["view", "edit", "create", "bash", "apply_patch", "task"] } } }Why this matters
Framework authors building multi-agent workflows (e.g. execute → review → architecture-review → security-review) need sub-agents to persist artifacts (review reports, proposal files). Without write tools, sub-agents must return content in their response text and rely on the calling agent to persist it — adding fragility, complexity, and token overhead to the workflow.
Tested on
tasktoolWorkaround
Sub-agents detect whether write tools are available. If not, they return file content and intended paths in their response. The nearest parent agent with write capability persists the artifacts on their behalf.