feat: Dynamic Agent Discovery for Agent Validation System

[jerfowler]

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_task tool in src/tools/create-task.ts accepts 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.ts line 291: Only basic string validation via validateRequiredString()
• 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_task accepts '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:

• /comm contains task storage, not agent availability
• An agent can exist without having any tasks yet
• Agent availability should come from Claude Code's agent system (/agents command 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:

1. Bug docs: add Git Feature Branch Workflow section to README #1: Progress calculation - ✅ FIXED (checkbox parsing working)
2. Bug feat: implement comprehensive Git Feature Branch Workflow #2: Agent validation - ❌ MISSING (this issue addresses this)
3. Bug feat: implement comprehensive GitHub issue workflow automation #3: Step validation - ❌ MISSING (separate issue needed)
4. 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 /agents command implementation
• Identify proper API for agent availability (not /comm scanning)
• 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.

[github-actions]

🔗 Linked Pull Request

PR #62 has been created to address this issue.

PR Title: feat: Issue #59 - Enhanced Agent Validation with Dynamic Discovery
Author: @jerfowler
Branch: issue-59-enhanced-agent-validation

View Pull Request →

[github-actions]

🔗 Linked Pull Request

PR #62 has been created to address this issue.

PR Title: feat: Issue #59 - Enhanced Agent Validation with Dynamic Discovery
Author: @jerfowler
Branch: issue-59-enhanced-agent-validation

View Pull Request →

[github-actions]

🎉 Resolved by PR #62

This issue has been automatically closed because the linked pull request has been merged.

PR Title: feat: Issue #59 - Enhanced Agent Validation with Dynamic Discovery
Merged by: @jerfowler
Commit: fea1326

View merged PR →

Thank you for the contribution! 🚀

[github-actions]

🎉 Resolved by PR #62

This issue has been automatically closed because the linked pull request has been merged.

PR Title: feat: Issue #59 - Enhanced Agent Validation with Dynamic Discovery
Merged by: @jerfowler
Commit: fea1326

View merged PR →

Thank you for the contribution! 🚀