[BUG] Agents cannot discover plugin-scoped slash commands - namespace resolution fails

[BUG] Agents cannot discover plugin-scoped slash commands - namespace resolution fails

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (not multiple features)
• [x] I am using the latest version of Claude Code

Environment

• Claude Code Version: 2.0.31+
• Platform: macOS (Darwin 24.6.0)
• OS: macOS
• Plugin System: Using plugin marketplace with custom plugins

Problem Statement

When agents (launched via @mention or Task tool) attempt to use slash commands from plugins, they cannot discover the plugin-scoped command names. Agents try to use short names like /docs, /task, /commit but these commands are actually namespaced as /general:docs, /general:task, /general:commit when they come from a plugin.

This creates a fundamental disconnect between:

• User experience: Commands work fine when typed directly (/general:docs)
• Agent experience: Agents fail when trying to use the same commands

What's Wrong?

Current Behavior

When an agent's documentation says:

Use /docs to search documentation
Use /task to plan implementation

The agent tries to execute:

/docs fastmcp validation

Result: Error: Unknown slash command: docs

Root Cause

Slash commands from plugins are namespaced with the plugin name:

• Plugin: general@personal
• Command file: commands/docs.md
• Actual command name: /general:docs (not /docs)

Agents don't have access to:

1. The plugin command registry
2. Namespace resolution mechanism
3. Available command discovery

This is similar to issue #7152 but specific to the plugin namespace problem.

What Should Happen?

Agents should be able to:

1. Discover plugin-scoped commands - know that /general:docs exists
2. Resolve short names - understand that /docs in context means /general:docs
3. Access command registry - see all available commands with their full names

OR

The SlashCommand tool should accept both:

• Full names: /general:docs (currently works)
• Short names: /docs (resolve to /general:docs if unambiguous)

Steps to Reproduce

1. Create a plugin with slash commands:

``
marketplaces/personal/general/
├── .claude-plugin/plugin.json
└── commands/
├── docs.md
├── task.md
└── commit.md
``

1. Install the plugin: claude plugin install general@personal

1. Create an agent that references commands:

```markdown
---
name: offload
---

## How to Use

Execute commands like:

• /docs to search documentation
• /task to plan work

```

1. Launch the agent: @offload /docs fastmcp

1. Expected: Agent uses /general:docs fastmcp
2. Actual: Agent tries /docs and fails with "Unknown slash command"

Impact

This breaks agent workflows that rely on slash commands from plugins:

Affected Use Cases

1. Documentation research agents - can't use /general:docs
2. Task planning agents - can't use /general:task
3. Commit automation - can't use /general:commit
4. Any agent in a plugin referencing other plugin commands

Current Workarounds

Option 1: Manually specify full names in agent documentation

Use /general:docs to search documentation  # Not /docs
Use /general:task to plan implementation   # Not /task

Problem: This is error-prone and non-obvious to plugin developers

Option 2: Use direct tool calls instead

Use mcp__context7__get-library-docs instead of /general:docs

Problem: Bypasses the slash command abstraction, couples to implementation

Option 3: Don't use agents with plugin commands
Problem: Severely limits plugin utility

Expected Behavior

Solution 1: Command Registry Exposure

Expose available commands to agents via context or tool:

// Agent has access to:
{
  "available_commands": [
    { "name": "/general:docs", "short_name": "docs", "plugin": "general@personal" },
    { "name": "/general:task", "short_name": "task", "plugin": "general@personal" },
    // ...
  ]
}

Agents can then intelligently resolve /docs → /general:docs.

Solution 2: Namespace Resolution in SlashCommand Tool

The SlashCommand tool could resolve short names:

# User types: /docs fastmcp
# SlashCommand tool resolves to: /general:docs fastmcp
# If multiple matches exist, ask for clarification

Solution 3: Plugin Context Inheritance

Agents launched from plugin context inherit the plugin's namespace:

# In general@personal plugin
# Agent can use /docs (implicitly means /general:docs)

Related Issues

• #7152 - Agents try to use Bash() for slash commands, need Command() tool
• #11290 - Slash command agent lifecycle (exit notifications)
• #10294 - Slash commands not loading (different issue, but related to discovery)

Additional Context

This issue becomes critical when:

• Building modular plugin architectures
• Creating reusable agent libraries
• Sharing plugins across teams

Plugin developers currently must choose between:

1. Not using slash commands in agents (lose functionality)
2. Hardcoding full namespace in docs (fragile, unclear)
3. Avoiding agent-to-agent command delegation (limits composition)

Proposed Priority

High - Blocks effective use of plugin marketplace for agent-driven workflows

Test Scenarios

1. Agent in general@personal uses /docs → resolves to /general:docs ✓
2. Agent uses /docs when two plugins provide it → asks for clarification ✓
3. Agent lists available commands → sees all plugin commands with namespaces ✓
4. SlashCommand tool with short name → resolves unambiguous matches ✓
5. Plugin disabled → its commands not available to agents ✓

Environment Details

Plugin Structure:

~/.claude/marketplaces/personal/general/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── docs.md          # Creates /general:docs
│   ├── task.md          # Creates /general:task
│   └── commit.md        # Creates /general:commit
├── agents/
│   └── offload.md       # Tries to use /docs, /task
└── .mcp.json

Settings:

{
  "enabledPlugins": {
    "general@personal": true
  }
}

Commands work when typed directly:

• /general:docs fastmcp ✓ Works
• /docs fastmcp ✗ "Unknown slash command"

Same command in agent fails:

• @offload /docs fastmcp → Agent tries /docs → Fails