# TASK_5: create_agent MCP Tool Implementation
**Created By**: OUTLINER | **Priority**: MEDIUM | **Duration**: 3 hours
**Technique Focus**: Contracts + Defensive Programming + Testing
**Size Constraint**: Target <250 lines/module, Max 400 if splitting awkward
## 🚦 Status & Assignment
**Status**: COMPLETE
**Assigned**: Adder_5 (COMPLETE)
**Dependencies**: TASK_4 (Agent & Session Management Core)
**Blocking**: Other MCP tool implementations
## 📖 Required Reading (Complete before starting)
- [ ] **Architecture**: `ARCHITECTURE.md` - create_agent tool specification
- [ ] **Core Management**: Results from TASK_4 - Agent and Session managers
- [ ] **FastMCP Integration**: Results from TASK_3 - Server foundation
- [ ] **Security Contracts**: Results from TASK_2 - Security validation framework
## 🎯 Objective & Context
**Goal**: Implement create_agent MCP tool with comprehensive validation, security, and error handling
**Context**: Core MCP tool enabling Claude Desktop to create new Claude Code agents with session association
<thinking>
create_agent Implementation Analysis:
1. Must validate agent naming convention (Agent_#) with uniqueness checks
2. Requires session validation and capacity checking
3. Needs iTerm2 tab creation and Claude Code process spawning
4. Must inject ADDER+ system prompt with agent name
5. Requires comprehensive error handling and rollback
6. Must integrate with health monitoring and state persistence
</thinking>
## ✅ Implementation Subtasks (Sequential completion)
### Phase 1: Input Validation & Security
- [x] **Subtask 1.1**: Implement comprehensive input validation with security checks ✅ COMPLETE
- [x] **Subtask 1.2**: Add agent naming convention validation (Agent_# format) ✅ COMPLETE
- [x] **Subtask 1.3**: Create session capacity and resource limit checking ✅ COMPLETE
- [x] **Subtask 1.4**: Implement specialization and configuration validation ✅ COMPLETE
### Phase 2: Core Implementation
- [x] **Subtask 2.1**: Integrate with OrchestrationCoordinator for agent creation ✅ COMPLETE
- [x] **Subtask 2.2**: Add iTerm2 tab creation and Claude Code process spawning ✅ COMPLETE
- [x] **Subtask 2.3**: Implement ADDER+ prompt injection with agent name ✅ COMPLETE
- [x] **Subtask 2.4**: Create comprehensive state tracking and persistence ✅ COMPLETE
### Phase 3: Error Handling & Recovery
- [x] **Subtask 3.1**: Add rollback mechanisms for failed agent creation ✅ COMPLETE
- [x] **Subtask 3.2**: Implement graceful error handling with security preservation ✅ COMPLETE
- [x] **Subtask 3.3**: Create audit logging for all creation attempts ✅ COMPLETE
- [x] **Subtask 3.4**: Add resource cleanup on failures ✅ COMPLETE
### Phase 4: Testing & Validation
- [x] **Subtask 4.1**: Property-based testing for all input combinations ✅ COMPLETE
- [x] **Subtask 4.2**: Integration testing with actual iTerm2 and Claude Code ✅ COMPLETE
- [x] **Subtask 4.3**: Error scenario testing and recovery validation ✅ COMPLETE
- [x] **Subtask 4.4**: Performance testing with concurrent agent creation ✅ COMPLETE
## 🔧 Implementation Files & Specifications
**Files to Create/Modify**:
- `src/interfaces/mcp_tools.py` - MCP tool implementations (Target: <200 lines for create_agent)
- `src/validators/agent_creation.py` - Agent creation validation (Target: <150 lines)
- `src/utils/agent_naming.py` - Agent naming convention utilities (Target: <100 lines)
- `src/utils/rollback.py` - Operation rollback mechanisms (Target: <150 lines)
- `tests/interfaces/test_create_agent.py` - Comprehensive tool testing
- `tests/properties/test_agent_creation.py` - Property-based testing scenarios
**Key Requirements**:
- FastMCP tool decorator with automatic schema generation
- Complete input validation with security-focused approach
- Integration with OrchestrationCoordinator for agent management
- Comprehensive error handling with rollback capabilities
- Audit logging for all creation attempts and outcomes
## 🏗️ Modularity Strategy
**Size Management**:
- Separate validation logic into focused utility modules
- Use composition for complex agent creation workflow
- Break error handling into reusable rollback components
- Keep MCP tool implementation minimal and declarative
**Organization Principles**:
- Single responsibility for agent creation workflow
- Clear separation between validation and execution
- Minimal coupling with other MCP tools
- Maximum reusability of validation and rollback logic
## ✅ Success Criteria & Verification
**Completion Requirements**:
- [ ] MCP tool properly registered and accessible from Claude Desktop
- [ ] Comprehensive input validation with security focus
- [ ] Successful agent creation with iTerm2 tab and Claude Code process
- [ ] ADDER+ prompt injection working with agent name
- [ ] Complete error handling with rollback mechanisms
- [ ] Audit logging for all operations
- [ ] Property-based testing covering edge cases
- [ ] Integration testing with real iTerm2 and Claude Code
**Quality Gates**:
- Functionality: Creates working Claude Code agents accessible via iTerm2
- Security: All inputs validated with security contracts
- Reliability: Graceful error handling with complete rollback
- Performance: Handles concurrent agent creation efficiently
- Auditability: Complete logging of all creation attempts
## 🔄 Handoff Information
**Next Task Dependencies**: Other MCP tools (delete_agent, send_message, etc.) follow similar patterns
**Integration Points**: Uses OrchestrationCoordinator for actual agent management
**Future Considerations**: Template for other MCP tool implementations
## 📋 Implementation Template
```python
# src/interfaces/mcp_tools.py
from fastmcp import FastMCP, Context
from src.types.agent import AgentCreationRequest, AgentCreationResult
from src.validators.agent_creation import validate_agent_creation_request
from src.contracts.security import require_session_access
from src.core.coordinator import OrchestrationCoordinator
from src.utils.rollback import AgentCreationRollback
class AgentOrchestrationTools:
"""MCP tools for agent orchestration platform."""
def __init__(self, coordinator: OrchestrationCoordinator):
self.coordinator = coordinator
@mcp.tool()
@validate_agent_creation_request
@require_session_access
async def create_agent(
self,
session_id: str,
agent_name: str,
specialization: str = "",
system_prompt_suffix: str = "",
claude_config: dict = None,
ctx: Context = None
) -> dict:
"""
Creates new Claude Code agent instance with iTerm2 tab and process.
Args:
session_id: Target session identifier
agent_name: Agent name (must follow Agent_# format)
specialization: Optional agent specialization
system_prompt_suffix: Additional system prompt content
claude_config: Claude Code configuration options
Returns:
AgentCreationResult with agent details and status
Raises:
ValidationError: Invalid input parameters
SecurityError: Security policy violations
ResourceError: Insufficient resources or capacity
OperationError: Agent creation failed
"""
rollback = AgentCreationRollback()
try:
await ctx.info(f"Creating agent {agent_name} in session {session_id}")
# Phase 1: Validation
creation_request = AgentCreationRequest(
session_id=session_id,
agent_name=agent_name,
specialization=specialization,
system_prompt_suffix=system_prompt_suffix,
claude_config=claude_config or {}
)
# Phase 2: Agent Creation
await ctx.report_progress(25, 100, "Validating session and capacity")
session_state = await self.coordinator.session_manager.get_session(session_id)
if not session_state:
raise ValidationError(f"Session {session_id} not found")
await ctx.report_progress(50, 100, "Creating iTerm2 tab and Claude Code process")
agent_result = await self.coordinator.agent_manager.create_agent(
creation_request
)
rollback.add_agent_cleanup(agent_result.agent_id)
await ctx.report_progress(75, 100, "Activating Claude Code and injecting ADDER+ prompt")
await self._activate_claude_code(agent_result.agent_id, session_state.root_path)
await self._inject_adder_prompt(agent_result.agent_id, agent_name)
await ctx.report_progress(100, 100, "Agent creation complete")
await ctx.info(f"Successfully created agent {agent_name}")
# Clear rollback on success
rollback.clear()
return {
"success": True,
"agent_id": str(agent_result.agent_id),
"agent_name": agent_name,
"iterm_tab_id": agent_result.iterm_tab_id,
"process_id": agent_result.process_id,
"session_id": session_id,
"specialization": specialization
}
except Exception as e:
await ctx.error(f"Agent creation failed: {str(e)}")
await rollback.execute()
raise
async def _activate_claude_code(self, agent_id: AgentId, session_root: Path):
"""Activate Claude Code in the session root directory."""
activation_command = f"cd {session_root} && claude"
await self.coordinator.iterm_manager.send_text_to_tab(
agent_id,
activation_command + "
"
)
# Wait for Claude Code to initialize
await asyncio.sleep(3)
async def _inject_adder_prompt(self, agent_id: AgentId, agent_name: str):
"""Inject ADDER+ system prompt with agent name."""
adder_prompt = self._build_adder_prompt(agent_name)
await self.coordinator.claude_manager.send_system_prompt(
agent_id,
adder_prompt
)
def _build_adder_prompt(self, agent_name: str) -> str:
"""Build complete ADDER+ prompt with agent name injection."""
# Load ADDER+ prompt from document and inject agent name
base_prompt = load_adder_prompt() # From documents
return base_prompt.replace("[Agent_Name]", agent_name)
```
### **Validation Module**
```python
# src/validators/agent_creation.py
from typing import Pattern
import re
from pathlib import Path
from src.types.agent import AgentCreationRequest
from src.contracts.security import ValidationError
AGENT_NAME_PATTERN: Pattern = re.compile(r'^Agent_\d+
```
This create_agent implementation provides comprehensive agent creation with security validation, error handling, and integration with the orchestration platform.
)
def validate_agent_creation_request(func):
"""Decorator for comprehensive agent creation validation."""
async def wrapper(*args, **kwargs):
# Extract parameters
session_id = kwargs.get('session_id')
agent_name = kwargs.get('agent_name')
# Validate agent name format
if not AGENT_NAME_PATTERN.match(agent_name):
raise ValidationError(
f"Agent name must follow 'Agent_#' format, got: {agent_name}"
)
# Validate session has accessible root directory for Claude Code activation
session = await get_session_by_id(session_id)
if not session or not session.root_path.exists():
raise ValidationError(
f"Session root directory not accessible for Claude Code activation"
)
# Additional validation...
return await func(*args, **kwargs)
return wrapper
```
This create_agent implementation provides comprehensive agent creation with security validation, error handling, and integration with the orchestration platform.
