claude-code - 💡(How to fix) Fix Named subagents in .claude/agents/*.md don't get tool access at runtime [1 comments, 2 participants]

Summary

When the orchestrator launches a named subagent via the Task tool with subagent_type: "<custom-name>", the spawned agent has no working access to the tools its frontmatter declares. The agent's system prompt tells it the tools are available, but calls don't happen — the agent narrates a fake tool interaction in text and confabulates a response from training data.

The built-in general-purpose subagent works correctly in the same session, so this isn't a permissions or environment issue.

Environment

• Claude Code: 2.1.123
• Platform: macOS (Darwin 25.4.0)
• Install path: ~/.local/share/claude/versions/2.1.123 (symlinked from ~/.local/bin/claude)

Reproduction

1. Create a custom agent at .claude/agents/voice-tone.md with frontmatter:

   ---
   name: voice-tone
   description: Reviews documentation for voice and tone.
   tools: Read, Grep, Glob
   ---

2. From the main assistant, send two Task calls with identical prompts. Use any small file as the target.

   Prompt: "Call the Read tool on <path> with limit=5. Echo lines 1–5 back exactly as the Read tool returned them. Do not analyze or add commentary."

3. Compare results.

Actual results from a real session

Probe 1 — subagent_type: "general-purpose":

LINE-1: ---
LINE-2: title: "Data Lineage"
LINE-3: description: "Using data lineage in Seqera Platform."
LINE-4: date created: "2026-05-04"
LINE-5: last updated: "2026-05-04"

usage: total_tokens: 24281, tool_uses: 1, duration_ms: 5616

Matches the file exactly.

Probe 2 — subagent_type: "voice-tone":

I'll read the file and report the lines exactly as returned.
``
[Tool: Read]

usage: total_tokens: 9079, tool_uses: 0, duration_ms: 2591

The agent typed [Tool: Read] as plain text and produced no output. tool_uses: 0 confirms no actual tool invocation.

On other runs of the same prompt, the named subagent fabricated plausible-looking YAML frontmatter that didn't match the real file — different made-up content each time.

Expected

Both subagents should call Read and return real file contents. The named agent should respect its tools: allowlist (or, if there's no tools: field, inherit available tools from the parent).

Actual

The named agent never invokes any tool. It emits text that looks like a tool call (Read(...), [Tool: Read]) but the runtime registers tool_uses: 0. With no real Read result to ground its output, the agent confabulates from training data — or, in this last run, just stalls.

Things tried, none of which fixed it

• Adding model: sonnet to the agent's frontmatter.
• Removing the tools: field entirely (to inherit all tools from the parent).
• Strengthening the agent body with explicit "call Read first" instructions and a mandatory proof-of-read protocol.

The symptom is independent of frontmatter content. Suggests the runtime is treating named subagents as zero-tool agents regardless of declaration.

Impact

This is a silent, high-stakes bug. Any project that uses custom agents in .claude/agents/ for tasks that require reading files — documentation review, code analysis, refactor planning, security review, etc. — has been producing fabricated output. Findings reference line numbers that don't exist, quote text that was never in the file, and recommend changes to code that wasn't read.

The hallucinations are plausible enough that they typically look correct on a quick scan, so users may not notice unless they spot-check findings against the actual file. In the project where I found this, there's a multi-commit history of "hallucination prevention" work attempting to fix the symptom from inside agent prompts — none of which can succeed, because the runtime never wires up the tools.

Suggested triage

• Check whether the named-subagent code path actually passes the tools: allowlist (or default tool set) into the spawned agent's runtime.
• Compare against the general-purpose code path in the same version — that one works.