Subagent Tools And Permissions — Claude Code Guide

Tools define actual capability

A role describes a subagent’s purpose, but its tool list defines what it can actually do. A textual prohibition such as “do not change production code” does not replace a technical limit when the agent still has Edit or Write.

Start with the minimum profile: grant only the tools required for the specific result.

Layer	What it controls	Example
L1 — session	Maximum available actions	Read-only or full permissions
L2 — subagent	Tools for one role	Reviewer has Read and Grep without Edit
L3 — project	Team rules and directories	Tester writes only in tests/

Tool risks

Tool	Value	Control
Read	Inspect files	Allowed directories and sensitive data
Grep	Search code and configuration	Search width and secret exposure
Bash	Tests, build, diagnostics	Commands, side effects, stop conditions
Edit	Change files	Write boundary and explicit permission

Role profiles

Conceptual permission matrix

reviewer:   Read, Grep, Bash(read-only checks)
tester:     Read, Grep, Bash, Edit(tests only)
documenter: Read, Grep, Edit(docs only)
db-analyst: Read, Grep

Rule: if a role does not use a tool, do not add it “just in case”.

Design the permission set

Name the expected result.
List the minimum actions needed.
Assess the consequence of misuse for each tool.
Remove unnecessary permissions.
Give Edit explicit directory or file-type boundaries.
Check whether the agent can escape the task scope.