Agent Tools and Permissions

Overview

In the previous lesson, you learned how to define an agent's identity and behavior through its markdown file with YAML frontmatter. But system prompt instructions are ultimately guidance -- the agent might follow them, or it might decide that "helping" means ignoring a constraint. This lesson introduces the mechanism that turns guidance into enforced boundaries: the tools frontmatter field. By controlling which tools each agent can access, you create agents that literally cannot overstep their role, regardless of what they are asked to do.

The Tool Landscape

Before you can control permissions, you need to understand the tools available to an AI coding agent. Each tool represents a capability -- a specific action the agent can perform.

Agent tools organized by category: Read Tools (Read, Glob, Grep, WebSearch, WebFetch), Write Tools (Edit, Write), Execute Tools (Bash), and External Tools (MCP integrations). Categories range from safe observation to powerful execution.

Here is what each core tool does:

• Read -- Opens and reads file contents from the filesystem. This is the most basic tool and is safe in nearly all contexts.
• Glob -- Finds files matching a pattern (e.g., src/**/*.ts). Essential for navigation.
• Grep -- Searches file contents for text or patterns. Used for code discovery.
• Edit -- Modifies existing files by replacing specific content. This is a precision tool -- it changes known content in known files.
• Write -- Creates new files or completely overwrites existing ones. More powerful than Edit because it can create files from scratch.
• Bash -- Executes shell commands in the terminal. This is the most powerful and most dangerous tool -- it can do anything the operating system allows.
• WebSearch -- Searches the web for information. Useful for agents that need to look up documentation or current best practices.
• WebFetch -- Fetches content from a specific URL. Complements WebSearch for retrieving detailed information.
• MCP Tools -- Connections to external services via the Model Context Protocol. These could include Jira, GitHub, databases, or any custom integration.

Controlling Tools with Frontmatter

The tools frontmatter field is the primary mechanism for restricting an agent's capabilities. When you specify tools, the agent can only use those listed tools -- everything else is denied.

This agent can read files, find files, and search content. It cannot edit files, write files, or run commands -- even if a user asks it to "just quickly fix that bug." The tools field makes this an enforced boundary, not a suggestion.

Two Approaches: Allowlist vs Denylist

There are two ways to control an agent's tools:

tools (allowlist) -- List only the tools the agent needs. Everything else is denied. This is the recommended approach for most agents because it follows the principle of least privilege.

disallowedTools (denylist) -- The agent inherits all tools from the main conversation, minus the ones you list. Use this when the agent needs most tools but should be blocked from a few specific ones.

When both are set, disallowedTools is applied first, then tools is resolved against the remaining pool. For most agents, use tools alone -- it is clearer and safer.

Permission Levels: A Spectrum of Trust

Different agent roles need different levels of trust. You can think of tool access as a spectrum from observation to full autonomy:

Permission levels as a spectrum of trust: Observe (Read, Glob, Grep), Suggest (adds WebSearch and WebFetch), Edit (adds Edit and Write), Execute (adds Bash), Full Access (adds MCP Tools). Each level adds more powerful capabilities.

Most custom agents should operate at the lowest level that lets them complete their task.

Defense in Depth: Prompts Plus Tool Restrictions

You might wonder: if tool restrictions are enforced, why also mention constraints in the system prompt? The answer is defense in depth -- multiple layers of protection that complement each other.

Defense in depth flow: when an agent is told not to edit files by its system prompt, it may respect the prompt and produce read-only output. If it tries to edit anyway, the tools frontmatter check either blocks the action (if Edit is not in the tools list) or allows the undesired modification (if Edit is listed).

The system prompt acts as the first line of defense -- most of the time, the agent will respect its instructions. The tools frontmatter acts as the safety net -- even when the agent tries to overstep, the platform prevents it. Together, they create agents that are both well-behaved by default and constrained by design.

The system prompt tells the agent what it should do. The tools frontmatter controls what it can do. Use both.

Session-Wide Settings vs Per-Agent Tools

It is important to understand the distinction between per-agent tool controls and session-wide settings:

Per-agent controls (tools and disallowedTools in frontmatter) apply only to that specific agent. A code reviewer with tools: Read, Glob, Grep cannot edit files, even though the main conversation and other agents can.

Session-wide settings (.claude/settings.json permissions) apply to the entire session, including all agents. If .claude/settings.json denies Bash(rm -rf*), that denial applies everywhere -- the main conversation, every agent, every subagent.

These settings are not a per-agent restriction mechanism. They define session-wide policy: what commands are pre-approved and what commands are always blocked. Use tools frontmatter for per-agent restrictions.

Permission Patterns for Common Agents

Here are proven configurations for the most common agent types:

The Observer -- for code review, security audit, and architecture analysis:

The Writer -- for test writing, documentation, and code generation:

The Executor -- for build verification and integration testing (use sparingly):

Scoping Bash Access

The Bash tool deserves special attention because it is the most powerful and most dangerous tool in the agent's toolkit. With Bash access, an agent can:

• Read and write any file the user has access to
• Install or remove packages
• Start or stop processes
• Access the network
• Modify environment variables
• Delete files and directories

When you grant Bash access, scope it as tightly as possible in the system prompt. Enumerate the specific commands the agent may run rather than granting blanket access:

The system prompt scoping is behavioral guidance -- the agent will usually respect it but is not technically prevented from running other commands. For hard enforcement beyond the tools field, use hooks. A PreToolUse hook on the Bash tool can validate every command before execution and block anything outside the allowlist. Module 7 covers hooks in detail.

MCP Tool Permissions

If your project uses MCP (Model Context Protocol) integrations -- connections to Jira, GitHub, Slack, databases, or other services -- you can control access per agent. Use disallowedTools with MCP server patterns to block entire integrations:

You can also scope MCP servers to specific agents using the mcpServers frontmatter field, which connects servers only when that agent is active. See Module 6 for details.

Testing Your Permission Configuration

After defining an agent's permissions, verify that they work as intended:

1. Invoke the agent and ask it to perform its intended task -- it should succeed
2. Ask it to overstep -- request an action outside its tools list and verify it is blocked
3. Check the boundaries -- try edge cases like asking the agent to "just quickly fix" something when it should be read-only

This testing cycle confirms that your agent behaves as expected both within and outside its designated role.

Summary

Tool permissions in YAML frontmatter transform your agent definitions from well-intentioned guidelines into enforced boundaries. The tools field (allowlist) is the primary mechanism: list only the tools the agent needs, and everything else is denied. The disallowedTools field (denylist) is an alternative when the agent needs most tools but should be blocked from a few. Combine frontmatter tool controls with system prompt instructions for defense in depth: the prompt guides behavior, the tools field enforces it. Session-wide .claude/settings.json permissions are a separate mechanism that applies across the entire session, not per-agent. In the next lesson, you will put all of this together by building a complete custom agent from scratch.