feat: Dynamic Agent Discovery for Agent Validation System #59
Description
Summary
Enhancement Request: Implement dynamic agent discovery for agent validation system to replace the need for static agent registries and integrate with Claude Code's actual available agents.
This issue addresses Bug #2 from Issue #56: Missing Agent Name Validation
Current State (Accurate Assessment)
NO Agent Validation Currently Exists
- The
create_tasktool insrc/tools/create-task.tsaccepts ANY agent name without validation - Users can create tasks for non-existent agents (e.g., 'nonexistent-agent', 'hacker-agent')
- No protection against invalid or malicious agent names
- This was identified as Bug feat: implement comprehensive Git Feature Branch Workflow #2 in Issue bug: Multiple critical bugs found in comprehensive MCP server testing #56 Critical Bugs investigation
Current Code State:
src/tools/create-task.tsline 291: Only basic string validation viavalidateRequiredString()- No agent existence checking
- No integration with agent discovery systems
- No static registry or dynamic validation
Problem Identified in Issue #56
Bug #2 Analysis:
// Current problematic code in create-task.ts
const agent = validateRequiredString(options.agent, 'agent');
// No further agent validation - accepts any string!Test Evidence:
create_taskaccepts 'nonexistent-agent' without error- No validation against available Claude Code agents
- Security risk: path traversal and injection vulnerabilities possible
Proposed Solution
Goal: Dynamic Agent Discovery System
Implement agent validation that discovers truly available agents from Claude Code environment, NOT from static lists or /comm directories.
Key Insight: getAllAgents() Problem
Current getAllAgents() in src/utils/task-manager.ts scans /comm directories for agent folders - this is WRONG because:
/commcontains task storage, not agent availability- An agent can exist without having any tasks yet
- Agent availability should come from Claude Code's agent system (
/agentscommand equivalent)
Technical Requirements
1. Real Agent Discovery
// Need to discover agents from Claude Code system, not filesystem
function discoverAvailableAgents(): string[] {
// Integration with Claude Code's agent discovery
// NOT scanning /comm directories
// Possibly via /agents command equivalent or MCP integration
}2. Non-Breaking Implementation
// Add validation without breaking existing API
export function validateAgent(agent: string): void {
// Basic security checks (path traversal, injection)
// Dynamic agent existence validation
// Helpful suggestions from actual available agents
}3. Performance & Reliability
- Synchronous API to avoid breaking changes
- Caching with TTL for performance
- Graceful fallback if discovery fails
- Sub-100ms validation response time
Investigation Findings
From Issue #56 Bug Analysis:
- Bug docs: add Git Feature Branch Workflow section to README #1: Progress calculation - ✅ FIXED (checkbox parsing working)
- Bug feat: implement comprehensive Git Feature Branch Workflow #2: Agent validation - ❌ MISSING (this issue addresses this)
- Bug feat: implement comprehensive GitHub issue workflow automation #3: Step validation - ❌ MISSING (separate issue needed)
- Bug bug: Test GitHub issue workflow automation #4: Error logging - ❌ MISSING (separate issue needed)
Current Working Evidence:
tests/unit/tools/create-task.test.ts- Tests pass with any agent name- No validation errors for invalid agents
- System accepts 'test-agent', 'nonexistent-agent', etc.
Implementation Strategy
Phase 1: Research Agent Discovery
- Investigate how Claude Code discovers available agents
- Research
/agentscommand implementation - Identify proper API for agent availability (not
/commscanning) - Understand MCP integration possibilities for agent lists
Phase 2: Security-First Validation
- Implement basic security validation (path traversal, injection protection)
- Add agent format validation (alphanumeric, hyphens, length limits)
- Create meaningful error messages with suggestions
Phase 3: Dynamic Discovery Integration
- Implement agent discovery service (research-dependent)
- Add caching layer for performance
- Create fallback mechanisms for discovery failures
- Maintain synchronous API for compatibility
Phase 4: Testing & Documentation
- Comprehensive test coverage for all scenarios
- Security testing for injection/traversal attempts
- Performance testing with caching
- Update PROTOCOL.md with validation behavior
Technical Considerations
Security Requirements
- Path Traversal Protection: Reject '../', '/', '' characters
- Injection Protection: Sanitize special characters
- Length Limits: Reasonable agent name length restrictions
- Format Validation: Alphanumeric + hyphens/underscores only
Performance Requirements
- Synchronous API: No breaking changes to existing
validateAgent()signature - Fast Validation: <100ms response time with caching
- Cache Strategy: Memory-based with configurable TTL
- Fallback Performance: Graceful degradation under 200ms
Discovery Research Needed
- Claude Code Integration: How does Claude Code know available agents?
- MCP Protocol: Can agent lists be exposed via MCP resources?
- Runtime Discovery: Dynamic detection of agent availability
- Environment Adaptation: Different setups, different available agents
Success Criteria
Functional Goals
- ✅ Security: Block invalid/malicious agent names
- ✅ Accuracy: Validate against truly available agents
- ✅ Performance: Fast validation with caching
- ✅ Reliability: Graceful fallback on discovery failures
User Experience Goals
- ✅ Helpful Errors: Suggestions from actual available agents
- ✅ Environment Adaptive: Works across different Claude Code setups
- ✅ Non-Breaking: Existing code continues working
Technical Goals
- ✅ Test Coverage: Maintain 95%+ requirement
- ✅ Zero Breaking Changes: Synchronous API preserved
- ✅ Comprehensive Security: All attack vectors protected
- ✅ Performance: <100ms validation, <50ms cached
Related Context
- Issue bug: Multiple critical bugs found in comprehensive MCP server testing #56: Critical Bugs in MCP Server Testing (Bug feat: implement comprehensive Git Feature Branch Workflow #2 specifically)
- CONTRIBUTING.md: Conventional commit requirements
- Current State: No agent validation exists (Bug feat: implement comprehensive Git Feature Branch Workflow #2)
- Dependencies: Research into Claude Code agent discovery mechanisms
Implementation Notes
This enhancement addresses Bug #2 from Issue #56: Missing Agent Name Validation. Currently, the MCP server accepts any agent name without validation, creating both security risks and poor user experience when invalid agents are used.