claude-code - 💡(How to fix) Fix Agent tool not available at runtime for plugin-defined agent types despite tools: frontmatter declaration [1 comments, 2 participants]

Description

Plugin-defined agent types that declare Agent in their tools: frontmatter do not receive the Agent tool at runtime when dispatched via subagent_type. The tool is listed in the system prompt's tool summary but is not actually available for the agent to call.

Reproduction

Plugin agent definition (agents/research-manager.md):

---
name: research-manager
tools: Read, Grep, Glob, Bash, Write, Agent, mcp__plugin_goodmem_goodmem__goodmem_memories_retrieve
model: opus
---

Dispatch from orchestrator:

Agent({
  description: "Research domain",
  subagent_type: "deep-research:research-manager",
  prompt: "..."
})

Expected behavior

The research-manager agent should have the Agent tool available and be able to dispatch sub-agents:

Agent({
  subagent_type: "deep-research:data-collector",
  model: "sonnet",
  prompt: "..."
})

Actual behavior

The agent reports: "Agent tool for data-collector dispatch was not available in my tool set"

The system prompt shows (Tools: Read, Grep, Glob, Bash, Write, Agent, ...) but the Agent tool is not callable at runtime. The agent falls back to using whatever tools it does have (goodmem, WebSearch if available) instead of dispatching sub-agents.

Evidence

Across 5+ dispatch attempts with the same plugin:

When dispatched as a general-purpose agent (no subagent_type), the Agent tool is available and works correctly. The issue is specific to plugin-defined agent types via subagent_type.

Workaround

Dispatch managers as general-purpose agents with inlined instructions instead of using subagent_type:

Agent({
  description: "Research domain",
  model: "opus",
  prompt: "<full manager instructions inlined here>"
})

This works but defeats the purpose of plugin agent definitions.

Environment

• Claude Code version: latest (April 2026)
• OS: macOS
• Plugin location: ~/Claude/plugins/deep-research/
• Agent definitions use standard .md frontmatter format in agents/ directory

Impact

This blocks any plugin architecture that relies on hierarchical agent dispatch (manager → worker pattern). The only workaround is abandoning subagent_type entirely and inlining all agent instructions in the prompt, which makes plugin agent definitions dead code.