claude-code - 💡(How to fix) Fix Read-only subagents claim to save files via 'Document saved to <path>' without a Write tool [1 comments, 2 participants]

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

1. Create .claude/agents/example-reviewer.md:

   ---
   name: example-reviewer
   description: Reviews things.
   tools:
     - Read
   ---
   Review whatever you're given. Save your full review to the requested path.

2. From the orchestrator, invoke:

   Agent({
     subagent_type: "example-reviewer",
     prompt: "Review file X. Save your review to /tmp/review.md."
   })

3. The subagent returns "Review saved to /tmp/review.md" or similar.
4. 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:

1. Always require inline-return + verify file existence after every Read-only agent invocation, OR
2. 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

1. Validator warning when an agent prompt mentions saving / writing files but tools: doesn't include Write.
2. 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:").
3. 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).