Custom agents are undiscoverable via ToolSearch when Agent tool is deferred
Bug Description
Custom agents defined in ~/.claude/agents/ are effectively undiscoverable when the Agent tool is deferred. Claude cannot find them when it needs them, causing it to fall back to raw curl calls or report that no integration exists for the target service.
Root Cause
Custom agent types (e.g., jira, bitrise, confluence) are registered as subagent_type values embedded inside the Agent tool's description. When Agent is a deferred tool, Claude must use ToolSearch to discover it before it can see those subagent types. However, ToolSearch does not index subagent type names as keywords for the Agent tool.
Reproduction — ToolSearch results
| Query | Result | Expected |
|---|---|---|
| "jira" | Returns WebFetch (matches "Jira" in its warning text). Agent tool NOT returned. | Should return Agent tool (has a jira subagent type) |
| "bitrise" | No matching tools found. | Should return Agent tool (has a bitrise subagent type) |
| "agent" | Returns Agent tool — lists all custom subagent types | ✅ Works, but only if Claude thinks to search for "agent" |
Steps to Reproduce
- Define a custom agent in
~/.claude/agents/jira.mdwith frontmattername: jira - Start a new Claude Code conversation
- Ask Claude to fetch a JIRA issue (e.g., "check the status of JIRA-123")
- Claude searches
ToolSearchfor"jira"— does not find the Agent tool - Claude concludes there is no JIRA integration and either falls back to
curlor tells the user it can't access JIRA
Expected Behavior
When custom agents are defined, their names/descriptions should be indexed by ToolSearch so that:
- Searching
"jira"returns theAgenttool when ajirasubagent type exists - Searching
"bitrise"returns theAgenttool when abitrisesubagent type exists - etc.
Alternatively, custom agent types could be surfaced as individual entries in the deferred tools list (e.g., Agent:jira, Agent:bitrise) so they're independently searchable.
Why This Matters
- Plugin/team distribution: Custom agents are meant to be distributable (via plugins or team configs). If agents aren't discoverable, every user will hit this problem — they'll need a manual workaround like adding notes to
CLAUDE.md, which defeats the purpose of the agent system. - Regression: This worked in earlier versions of Claude Code where the
Agenttool was presumably not deferred, so the full list of subagent types was always visible in context.
Environment
- Claude Code CLI 2.1.71
- macOS Darwin 25.3.0
- Custom agents defined in
~/.claude/agents/(jira, bitrise, confluence, figma)
Suggested Fix
One of:
- Index subagent type names in ToolSearch — When building the search index for deferred tools, extract
subagent_typenames from the Agent tool description and index them as keywords. This is the minimal fix. - Register custom agents as individual deferred tool entries — Each agent in
~/.claude/agents/gets its own entry in<available-deferred-tools>(e.g.,Agent:jira) with the agent's description as searchable text. - Don't defer the Agent tool — If Agent is always loaded, Claude always sees the available subagent types. This is the simplest fix but increases initial context size.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗