Tool constraints define what actions an agent can perform. Use whitelists (tools) or blacklists (disallowedTools) to enforce read-only access, prevent shell execution, or block file creation.
Read files from the filesystem. Line ranges and offsets supported.
Pattern-based file search. Example: **/*.ts.
Content search with regex. Fast full-text search.
Edit existing files with string replacement. Requires prior Read.
Create new files or overwrite existing ones.
Execute shell commands. Can read/write files, install packages, run tests.
Delegate to subagents or specialized tools.
Fetch web content (documentation, APIs, etc.).
Invoke user-defined skills.
Use tools to explicitly allow specific tools:
Read-Only
Edit-Only
Documentation
--- name : planner tools : [ "Read" , "Glob" , "Grep" ] --- Agent can explore code but not make changes.
When tools is specified, only those tools are available. All others are blocked.
Use disallowedTools to block specific tools:
No Shell Access
No File Creation
Read-Only (via Blacklist)
--- name : safe-explorer disallowedTools : [ "Bash" ] --- Agent can use all tools except shell execution.
disallowedTools overrides tools. If a tool is in both lists, it’s blocked.
Exploration Agents --- name : explorer tools : [ "Read" , "Glob" , "Grep" , "WebFetch" ] model : haiku permissionMode : auto --- Fast exploration without modifying code.
Use for: Understanding codebases, finding patterns, generating reports.Planning Agents --- name : planner tools : [ "Read" , "Glob" , "Grep" ] model : opus --- Deep analysis and plan generation without code changes.
Use for: Architecture decisions, task breakdowns, risk assessment.Review Agents --- name : reviewer tools : [ "Read" , "Glob" , "Grep" , "Bash" ] --- Code review with test execution but no modifications.
Use for: PR reviews, security audits, quality checks.Implementation Agents --- name : implementer tools : [ "Read" , "Glob" , "Grep" , "Edit" , "Bash" ] --- Implementation with editing and testing. No new file creation.
Use for: Refactoring, bug fixes, incremental features.Full-Access Agents --- name : orchestrator tools : [ "Read" , "Glob" , "Grep" , "Bash" , "Edit" , "Write" ] model : opus memory : project --- Complete tool access for complex features.
Use for: Multi-phase development, new features, major refactors.Read + Edit (No Create) --- name : safe-refactor tools : [ "Read" , "Edit" ] ---
Allows:
Read existing files
Edit existing files
Blocks:
Create new files (no Write)
Run shell commands (no Bash)
Search files (no Glob/Grep)
Read + Grep + Edit (Pattern-Based Editing) --- name : pattern-refactor tools : [ "Read" , "Grep" , "Edit" ] ---
Allows:
Search for patterns
Read matching files
Edit matching files
Blocks:
Create new files
Run tests
File system traversal (no Glob)
Read + Bash (Validation) --- name : validator tools : [ "Read" , "Bash" ] ---
Allows:
Read files
Run lint, typecheck, tests
Blocks:
Edit files
Create files
Search (must know file paths)
Security Considerations Bash has full shell access:
Can read/write any file
Can install packages
Can delete files
Can make network requests
Only grant Bash to trusted agents. Use permissionMode: ask for human oversight.
Safe Alternative: Read + Edit For code modifications without shell access:
--- name : safe-implementer tools : [ "Read" , "Glob" , "Grep" , "Edit" ] --- Agent can modify code but not run arbitrary shell commands.
Write can:
Overwrite critical files (e.g., package.json, .env)
Create files outside project directory
Bypass git tracking
Use Edit instead of Write when possible. Edit requires reading the file first, providing a safety check.
Permission Modes Control approval flow with permissionMode:
ask (Default)
auto
dangerous-only
--- name : careful-agent permissionMode : ask --- Ask before every tool use.
--- name : auto-agent tools : [ "Read" , "Glob" , "Grep" ] permissionMode : auto --- Auto-approve all tool uses (safe with read-only tools).
--- name : smart-agent permissionMode : dangerous-only --- Ask only for Bash, Write, and destructive operations.
Combine tools constraints with permissionMode: auto for fully autonomous read-only agents.
Examples by Use Case
--- name : explorer description : Fast read-only codebase exploration tools : [ "Read" , "Glob" , "Grep" ] model : haiku permissionMode : auto background : true --- Explore codebase in background without blocking main session. Workflow : 1. Glob for file patterns 2. Grep for content matches 3. Read relevant files 4. Summarize findings
--- name : refactor description : Apply safe refactorings to existing code tools : [ "Read" , "Glob" , "Grep" , "Edit" ] permissionMode : dangerous-only --- Refactor code without creating new files or running shell commands. Workflow : 1. Grep for pattern to refactor 2. Read each matching file 3. Edit with transformation 4. Present summary for review
--- name : quality-gate description : Run quality checks without modifying code tools : [ "Read" , "Bash" ] permissionMode : auto --- Run lint, typecheck, and tests. Workflow : 1. npm run lint 2. npm run typecheck 3. npm test -- --related 4. Report results
--- name : doc-gen description : Generate documentation from source code tools : [ "Read" , "Glob" , "Write" , "WebFetch" ] --- Generate docs from code. Workflow : 1. Glob for source files 2. Read each file 3. Extract types, interfaces, functions 4. WebFetch for external API docs 5. Write markdown documentation
Tool Speed Context Cost Glob Fast (<10ms) Low (paths only) Grep Fast (<50ms) Low (matches only) Read Medium (10-100ms) High (full file) Edit Medium (50-200ms) Medium (diff only) Write Fast (<50ms) Medium (new content) Bash Variable Variable
Use Glob/Grep for discovery, then Read only the files you need. Avoid reading entire codebases.
If an agent can’t use a tool:
# Check agent configuration cat .claude/agents/my-agent.md | grep -A 5 'tools:' # Verify tool name (case-sensitive) echo "Tools: Read, Glob, Grep, Bash, Edit, Write" # Test with minimal agent cat > .claude/agents/test.md << EOF --- name: test tools: ["Read"] --- Test agent with only Read tool. EOF
Next Steps
Agent Frontmatter Complete agent configuration
Agent Skills Preload domain knowledge
Agent Memory Configure memory scope
Security Guide Agent security best practices