Subagent Tool Restrictions - Claude Code

Tool restrictions let you cap what a subagent is allowed to do. A "read-only researcher" literally can't write to disk if you don't include Edit or Write.

What it does

In the subagent's frontmatter, you list the exact set of tools the agent may use. Every other tool call from that agent fails immediately. This is the cleanest way to build roles with least-privilege guarantees - the safety is structural, not based on hoping Claude doesn't reach for a forbidden tool.

When to use it

• Researcher and auditor roles that should never write code.
• Tightly scoped agents for sensitive tasks (compliance checks, logs).
• Shared team agents where different contributors will invoke them.
• Defense in depth alongside permission rules.

Gotchas

• Over-restricted agents fail tasks in confusing ways. Err toward inclusion for genuine needs.
• Tool restrictions don't limit what the subagent can read - they limit what it can call.
• Adding tools later is easy; taking them back is harder once workflows depend on them.

Official docs: https://code.claude.com/docs/en/sub-agents.md#control-subagent-capabilities