Custom agents are undiscoverable via ToolSearch when Agent tool is deferred

Resolved 💬 4 comments Opened Mar 9, 2026 by jgongo Closed Apr 6, 2026

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

  1. Define a custom agent in ~/.claude/agents/jira.md with frontmatter name: jira
  2. Start a new Claude Code conversation
  3. Ask Claude to fetch a JIRA issue (e.g., "check the status of JIRA-123")
  4. Claude searches ToolSearch for "jira" — does not find the Agent tool
  5. Claude concludes there is no JIRA integration and either falls back to curl or 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 the Agent tool when a jira subagent type exists
  • Searching "bitrise" returns the Agent tool when a bitrise subagent 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 Agent tool 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:

  1. Index subagent type names in ToolSearch — When building the search index for deferred tools, extract subagent_type names from the Agent tool description and index them as keywords. This is the minimal fix.
  2. 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.
  3. 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.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗