How to Restrict the Tools a Subagent Can Use

By default a subagent inherits the same tools the main session has, including Bash and file editing. For a read-only analyst or a planner you almost never want that. Restricting the tools list reduces blast radius and makes the subagent more predictable. This guide shows how the tools field works and how to verify it.

• An existing subagent file in .claude/agents
• A clear idea of which tools the job truly needs
• Claude Code open in the project

Step 1: Decide the minimum tool set

Start from nothing and add back only what the job requires. A documentation summarizer needs to read and search but should never edit or run shell commands. Leaving out Bash and Edit removes whole categories of mistakes.

Step 2: Set the tools field

List the allowed tools as a comma-separated value in the frontmatter. If you omit the field entirely, the subagent inherits all tools, so being explicit is the safer default.

---
name: doc-summarizer
description: Summarizes documentation files on request. Read only.
tools: Read, Grep, Glob
---

You summarize documentation. You never edit files and never run shell commands.
Return a short bullet summary plus the source file path for each point.

Step 3: Verify in the agents manager

Open the agents command and inspect the subagent. The manager shows the resolved tool list so you can confirm the restriction took effect before you rely on it.

Result: the doc-summarizer subagent can read and search but has no path to edit files or run commands, so you can hand it untrusted documents without worrying about side effects.