Read-only subagents claim to save files via 'Document saved to <path>' without a Write tool
Description
When a project-level subagent is defined with tools: [Read] (no Write tool) and the orchestrator instructs it to "save your output to <path>", the subagent reliably reports success ("Document saved to ...", "Review saved to ...", etc.) without producing the file. The user discovers the missing artifact later.
Reproduction
- Create
.claude/agents/example-reviewer.md:
```yaml
---
name: example-reviewer
description: Reviews things.
tools:
- Read
---
Review whatever you're given. Save your full review to the requested path.
```
- From the orchestrator, invoke:
````
Agent({
subagent_type: "example-reviewer",
prompt: "Review file X. Save your review to /tmp/review.md."
})
- The subagent returns "Review saved to
/tmp/review.md" or similar. ls /tmp/review.md→ file does not exist.
Why this matters
Specialist-review patterns are common in multi-agent workflows (architect, code-quality, security, domain experts). Many such patterns deliberately give specialists Read-only access to keep their scope tight. The "save to path" instruction is a natural way to capture review artifacts for later reference.
Today, hitting this requires the orchestrator to:
- Always require inline-return + verify file existence after every Read-only agent invocation, OR
- Grant Write to every specialist (less scope discipline)
I hit this 3 times in a single session across 3 different specialist agents (different domain experts), each time getting an authoritative "Document saved to <path>" without the file being written.
Suggested fixes
- Validator warning when an agent prompt mentions saving / writing files but
tools:doesn't include Write. - Tool-availability awareness in model behavior — the agent should refuse to claim it called a tool it doesn't have, and instead return content inline with a note ("I have Read-only access; here's the full content for the orchestrator to save:").
- Documentation update — explicitly note in the subagent docs that Read-only agents cannot save to files even when instructed to.
Workaround
Grant Write to the agent's tools list. This is what we did in our project (12 specialist agents updated).
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗