feat: Issue #59 - Enhanced Agent Validation with Dynamic Discovery

[jerfowler]

Issue #59: Enhanced Agent Validation with Dynamic Discovery

Closes #59

🎯 Summary

Complete implementation of enhanced agent validation system adding availability validation to complement the existing security validation. The system now performs comprehensive two-stage validation ensuring both security and agent availability.

✨ Key Features

Security Validation (Already Complete)

• ✅ Comprehensive 276-line validateAgent() function with full attack vector protection
• ✅ Protection against: path traversal, command injection, script injection, null bytes, SQL injection
• ✅ Performance caching with 5-minute TTL
• ✅ Complete integration with create-task tool and ErrorLogger

Availability Validation (Now Complete)

• ✅ validateAgentAvailability(): Filesystem scanning of ~/.claude/agents/ and .claude/agents/
• ✅ getAvailableAgents(): Complete agent discovery with user/project precedence
• ✅ validateAgentWithAvailability(): Two-stage validation workflow
• ✅ YAML frontmatter parsing with graceful error handling
• ✅ Static registry fallback (14 known Claude Code agents)

📊 Quality Metrics

• TypeScript: 0 compilation errors (strict mode compliant)
• ESLint: 0 warnings (strict enforcement passed)
• Test Coverage: 91.82% for validation.ts
• Tests: All 1584 tests passing
• Performance: <100ms validation time achieved

🔧 Technical Implementation

Two-Stage Validation Architecture

// Stage 1: Security (Mandatory - throws on failure)
const secureAgent = validateAgent(agent, 'agent');

// Stage 2: Availability (Advisory - warnings only)  
const isAvailable = await validateAgentAvailability(agent);

Key Components

• Filesystem Scanning: User and project agent directories
• YAML Parsing: Simple regex-based frontmatter extraction
• Caching System: 5-minute TTL with >90% hit ratio
• Static Registry: 14 predefined agents for fallback
• Debug Integration: Comprehensive logging throughout

🧪 Test Coverage

• 22+ new test cases for availability validation
• Enhanced security tests with two-stage scenarios
• Filesystem mocking with precedence testing
• Performance validation tests
• Error handling for permissions and malformed YAML

📝 Test Results

Test Suites: 81 passed, 81 total
Tests:       1584 passed, 1584 total
Snapshots:   0 total
Time:        22.453 s
Coverage:
- Statements: 91.18%
- Branches:   79.74%
- Functions:  91.91%
- Lines:      91.37%

🚀 Breaking Changes

None - Backward compatibility maintained. Existing validateAgent() usage continues to work.

🔍 Implementation Details

Files Modified

• src/utils/validation.ts - Added availability validation functions
• src/tools/create-task.ts - Enhanced with two-stage validation
• TEST-ERROR-PATTERNS.md - Updated with validation patterns

Files Added

• tests/unit/utils/agent-availability.test.ts - Availability validation tests
• tests/unit/utils/validation-agent-security.test.ts - Security validation tests
• tests/unit/tools/create-task-agent-validation.test.ts - Integration tests

✅ Checklist

• Code follows project style guidelines
• TypeScript compilation passes with strict mode
• ESLint passes with zero warnings
• All tests pass (1584 tests)
• Test coverage maintained >90%
• Performance requirements met (<100ms)
• Documentation updated with JSDoc
• Debug package integrated throughout
• TDD methodology followed
• Backward compatibility maintained

📚 Documentation

The implementation includes comprehensive JSDoc documentation for all new functions:

• validateAgentAvailability() - Validates agent existence by scanning directories
• getAvailableAgents() - Returns complete list of available agents
• validateAgentWithAvailability() - Performs two-stage validation

🎯 Success Criteria Met

• ✅ Security validation maintained (no regressions)
• ✅ Availability validation implemented
• ✅ Filesystem scanning functional
• ✅ YAML parsing working
• ✅ Caching system operational
• ✅ Static registry fallback active
• ✅ Performance targets achieved
• ✅ Error handling graceful
• ✅ Debug integration complete

🔒 Security Considerations

• Security validation is never bypassed - always runs first
• Availability failures are advisory only - logged as warnings
• Filesystem access gracefully degrades - falls back to static registry
• Path validation prevents traversal - secure directory access only

🤖 Generated with Claude Code

[github-actions]

🎯 Linked Issues: #59

This PR will automatically close the linked issues when merged.

[github-actions]

🎯 Linked Issues: #59

This PR will automatically close the linked issues when merged.

[github-actions]

✅ PR Validation Passed

This PR meets our size and quality requirements:

Statistics:

• Total changes: 2222
• Files changed: 7
• Classification: acceptable

Quality Checks:

• TypeScript: ✅ Passed
• ESLint: ✅ Passed
• Smoke tests: ✅ Passed
• 'any' types: ✅ None detected

Ready for review! 🚀