[BUG] Custom agents with Edit tool don't receive Read access unless full tool list specified

[dominiceloe]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Environment

• Claude Code Version: 2.0.45 (latest as of 2025-11-18)
• OS: macOS (Darwin 24.6.0)
• Installation: Global npm install
• Agent Location: .claude/agents/

Summary

Custom agents that include Edit in their tool list but don't have the complete tool set fail to receive Read tool access, even though Read is explicitly listed in their frontmatter. This causes agents to report "Read tool not available" and fail to perform their intended functions.

What Should Happen?

Expected Fix

Agents should receive all tools listed in their frontmatter tools: field, regardless of which specific tools are included or the total number of tools specified.

Error Messages/Logs

Steps to Reproduce

Reproduction Steps

Step 1: Create a custom agent with partial tool list including Edit

Create .claude/agents/test-agent.md:

---
name: test-agent
description: Test agent for reproducing tool access bug
color: blue
tools: [Read, Edit, Grep, Bash]
---

# Test Agent
Read a file and report how many lines it has.

Step 2: Invoke the agent

# Start fresh Claude Code terminal
claude

# Invoke agent via Task tool
Task(
  subagent_type="test-agent",
  prompt="Read /path/to/file.txt and tell me how many lines it has"
)

Step 3: Observe agent response

Agent reports: "I don't have a Read tool available in my toolset. I only have [Grep, Edit] available."

Expected Behavior

Agent should have access to all tools listed in frontmatter: [Read, Edit, Grep, Bash]

Actual Behavior

Agent only receives subset of tools: [Grep, Edit] - Read tool is missing despite being listed

Tool List Behavior Matrix

Tool List Configuration	Read Access	Edit Access	Works?
[Read, Edit, Grep, Bash]	❌ NO	✅ YES	❌ BROKEN
[Read, Write, Edit, Grep, Glob, Bash]	❌ NO	✅ YES	❌ BROKEN
[Read, Grep, Glob] (no Edit)	✅ YES	N/A	✅ WORKS
[Read, Write, Edit, MultiEdit, Grep, Glob, Bash, TodoWrite] (full set)	✅ YES	✅ YES	✅ WORKS
[Bash, Read] (no Edit)	✅ YES	N/A	✅ WORKS

Pattern Discovered

• ✅ Agents without Edit in their tool list → Get Read access as expected
• ❌ Agents with Edit but not full tool list → Don't get Read access
• ✅ Agents with full tool list → Get Read access as expected

Hypothesis: There's a hidden requirement that agents with Edit must have the complete tool set to receive Read access.

Impact

Severity: High

• Custom agents silently fail with 0 tool uses
• Agents report success but perform no actual work
• Difficult to diagnose (agents claim success but tools aren't invoked)
• Affects test automation workflows significantly

Affected Agent Types

• Test fixers (need Read + Edit)
• Code generators (need Read + Write + Edit)
• Any agent that needs to read files before editing them

Workaround

Add the complete tool list to any agent that needs Edit:

tools: [Read, Write, Edit, MultiEdit, Grep, Glob, Bash, TodoWrite]

Even if the agent doesn't use Write, MultiEdit, Glob, or TodoWrite, including them grants proper Read access.

Validation

Created two identical agents differing only in tool list:

Agent A (Broken):

tools: [Read, Edit, Grep, Bash]

Result: Reports "no Read tool", makes 0 tool uses, fails task

Agent B (Fixed):

tools: [Read, Write, Edit, MultiEdit, Grep, Glob, Bash, TodoWrite]

Result: Successfully uses Read and Edit, completes task (12 tool uses)

Evidence

Agent transcript excerpt showing the issue:

Agent: "The Edit tool requires a prior 'Read' operation, but the Read tool
isn't listed in my available functions. I can see from my available tools
that I only have:
- Grep (for searching/viewing content)
- Edit (for making edits)

The system documentation mentions a 'Read' tool, but it's not in my actual
function list."

So I'm not sure if its a combo of tools that is needed or what, I just found that adding the full list seems to be a workaround.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.0.45 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

Additional Context

• This issue was discovered while debugging why my custom test-writing and test-fixing agents were reporting success with 0 tool uses
• The tools: frontmatter field appears to be honored inconsistently
• Read-only agents (reviewers, planners) work correctly with partial tool lists as long as they don't include Edit
• The full tool list workaround is reliable but requires agents to declare tools they never use

---

Note: This bug appears unreported - searched existing issues for "agent tool access", "Read Edit", "custom agent tools" and found no matches for this specific behavior.

---

[cruftyoldsysadmin]

Subagents seem to have broken around 2.0.30, but @anthropics doesn't really seem to care to fix it, or put any fixes in their documentation.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.