SuperClaude/Framework-Hooks/docs/Hooks/pre_tool_use.md

Pre-Tool-Use Hook Technical Documentation

Intelligent Tool Routing and MCP Server Selection Hook

---

Purpose

The pre_tool_use hook implements intelligent tool routing and MCP server selection for the SuperClaude framework. It runs before every tool execution in Claude Code, providing optimal tool configuration, MCP server coordination, and performance optimization within a strict 200ms execution target.

Core Value Proposition:

• Intelligent Routing: Matches tool requests to optimal execution strategies using pattern detection
• MCP Server Orchestration: Coordinates multiple specialized servers (Context7, Sequential, Magic, Playwright, Morphllm, Serena)
• Performance Optimization: Parallel execution planning, caching strategies, and resource management
• Adaptive Intelligence: Learning-based routing improvements over time
• Fallback Resilience: Graceful degradation when preferred tools are unavailable

---

Execution Context

Trigger Event

The hook executes before every tool use in Claude Code, intercepting tool requests to enhance them with SuperClaude intelligence.

Execution Flow

Tool Request → pre_tool_use Hook → Enhanced Tool Configuration → Tool Execution

Input Context

{
  "tool_name": "Read|Write|Edit|Analyze|Build|Test|...",
  "parameters": {...},
  "user_intent": "natural language description",
  "session_context": {...},
  "previous_tools": [...],
  "operation_sequence": [...],
  "resource_state": {...}
}

Output Enhancement

{
  "tool_name": "original_tool",
  "enhanced_mode": true,
  "mcp_integration": {
    "enabled": true,
    "servers": ["serena", "sequential"],
    "coordination_strategy": "collaborative"
  },
  "performance_optimization": {
    "parallel_execution": true,
    "caching_enabled": true,
    "optimizations": ["parallel_file_processing"]
  },
  "execution_metadata": {
    "estimated_time_ms": 1200,
    "complexity_score": 0.65,
    "intelligence_level": "medium"
  }
}

---

Performance Target

Primary Target: <200ms Execution Time

• Requirement: Complete routing analysis and configuration within 200ms
• Measurement: End-to-end hook execution time from input to enhanced configuration
• Validation: Real-time performance tracking with target compliance reporting
• Optimization: Cached pattern recognition, pre-computed routing tables, intelligent fallbacks

Performance Architecture

Performance Zones:
  green_zone: 0-150ms     # Optimal performance with full intelligence
  yellow_zone: 150-200ms  # Target compliance with efficiency mode
  red_zone: 200ms+        # Performance fallback with reduced intelligence

Efficiency Calculation

efficiency_score = (
    time_efficiency * 0.4 +      # Execution speed relative to target
    complexity_efficiency * 0.3 + # Handling complexity appropriately  
    resource_efficiency * 0.3     # Resource utilization optimization
)

---

Core Features

1. Intelligent Tool Routing

Pattern-Based Tool Analysis:

• Analyzes tool name, parameters, and context to determine optimal execution strategy
• Detects operation complexity (0.0-1.0 scale) based on file count, operation type, and requirements
• Identifies parallelization opportunities for multi-file operations
• Determines intelligence requirements for analysis and generation tasks

Operation Categorization:

Operation Types:
- READ: File reading, search, navigation
- WRITE: File creation, editing, updates  
- BUILD: Implementation, generation, creation
- TEST: Validation, testing, verification
- ANALYZE: Analysis, debugging, investigation

Complexity Scoring Algorithm:

base_complexity = {
    'READ': 0.0,
    'WRITE': 0.2, 
    'BUILD': 0.4,
    'TEST': 0.1,
    'ANALYZE': 0.3
}

file_multiplier = (file_count - 1) * 0.1
directory_multiplier = (directory_count - 1) * 0.05
intelligence_bonus = 0.2 if requires_intelligence else 0.0

complexity_score = base_complexity + file_multiplier + directory_multiplier + intelligence_bonus

2. Context-Aware Configuration

Session Context Integration:

• Tracks tool usage patterns across session for optimization opportunities
• Analyzes tool chain patterns (Read→Edit, Multi-file operations, Analysis chains)
• Applies session-specific optimizations based on detected patterns
• Maintains resource state awareness for performance tuning

Operation Chain Analysis:

Pattern Detection:
- read_edit_pattern: Read followed by Edit operations
- multi_file_pattern: Multiple file operations in sequence
- analysis_chain: Sequential analysis operations with caching opportunities

3. Real-Time Adaptation

Learning Engine Integration:

• Records tool usage effectiveness for routing optimization
• Adapts routing decisions based on historical performance
• Applies user-specific and project-specific routing preferences
• Continuous improvement through effectiveness measurement

Adaptation Scopes:

• User Level: Personal routing preferences and patterns
• Project Level: Project-specific tool effectiveness patterns
• Session Level: Real-time adaptation within current session

---

MCP Server Routing Logic

Server Capability Matching

The hook implements sophisticated capability matching to select optimal MCP servers:

Server Capabilities Map:
context7:    [documentation_access, framework_patterns, best_practices]
sequential:  [complex_reasoning, systematic_analysis, hypothesis_testing]
magic:       [ui_generation, design_systems, component_patterns]
playwright:  [browser_automation, testing_frameworks, performance_testing]
morphllm:    [pattern_application, fast_apply, intelligent_editing]
serena:      [semantic_understanding, project_context, memory_management]

Routing Decision Matrix

Single Server Selection

Context7 Triggers:
  - Library/framework keywords in user intent
  - Documentation-related operations
  - API reference needs
  - Best practices queries

Sequential Triggers:
  - Complexity score > 0.6
  - Multi-step analysis required
  - Debugging complex issues
  - System architecture analysis

Magic Triggers:
  - UI/component keywords
  - Frontend development operations
  - Design system integration
  - Component generation requests

Playwright Triggers:
  - Testing operations
  - Browser automation needs
  - Performance testing requirements
  - E2E validation requests

Morphllm Triggers:
  - Pattern-based editing
  - Fast apply suitable operations
  - Token optimization critical
  - Simple to moderate complexity

Serena Triggers:
  - File count > 5
  - Symbol-level operations
  - Project-wide analysis
  - Memory operations

Multi-Server Coordination

Coordination Strategies:
- single_server: One MCP server handles the operation
- collaborative: Multiple servers work together
- sequential_handoff: Primary server → Secondary server
- parallel_coordination: Servers work on different aspects simultaneously

Server Selection Algorithm

def select_mcp_servers(context, requirements):
    servers = []
    
    # Primary capability matching
    for server, capabilities in server_capabilities.items():
        if any(cap in requirements['capabilities_needed'] for cap in capabilities):
            servers.append(server)
    
    # Context-specific routing
    if context['complexity_score'] > 0.6:
        servers.append('sequential')
    
    if context['file_count'] > 5:
        servers.append('serena')
    
    # User intent analysis
    intent_lower = context.get('user_intent', '').lower()
    if any(word in intent_lower for word in ['component', 'ui', 'frontend']):
        servers.append('magic')
    
    # Deduplication and prioritization
    return list(dict.fromkeys(servers))  # Preserve order, remove duplicates

---

Fallback Strategies

Hierarchy of Fallback Options

Level 1: Preferred MCP Server Unavailable

Strategy: Alternative Server Selection
- Sequential unavailable → Use Morphllm for analysis
- Serena unavailable → Use native tools with manual coordination
- Magic unavailable → Generate basic components with Context7 patterns

Level 2: Multiple MCP Servers Unavailable

Strategy: Capability Degradation
- Disable enhanced intelligence features
- Fall back to native Claude Code tools
- Maintain basic functionality with warnings
- Preserve user context and intent

Level 3: All MCP Servers Unavailable

Strategy: Native Tool Execution
- Execute original tool request without enhancement
- Log degradation for performance analysis
- Provide clear feedback about reduced capabilities
- Maintain operational continuity

Fallback Configuration Generation

def create_fallback_tool_config(tool_request, error):
    return {
        'tool_name': tool_request.get('tool_name'),
        'enhanced_mode': False,
        'fallback_mode': True,
        'error': error,
        'mcp_integration': {
            'enabled': False,
            'servers': [],
            'coordination_strategy': 'none'
        },
        'performance_optimization': {
            'parallel_execution': False,
            'caching_enabled': False,
            'optimizations': []
        },
        'performance_metrics': {
            'routing_time_ms': 0,
            'target_met': False,
            'error_occurred': True
        }
    }

Error Recovery Mechanisms

• Graceful Degradation: Reduce capability rather than failing completely
• Context Preservation: Maintain user intent and session context during fallback
• Performance Continuity: Ensure operations continue with acceptable performance
• Learning Integration: Record fallback events for routing improvement

---

Configuration

Hook-Specific Configuration (superclaude-config.json)

{
  "pre_tool_use": {
    "enabled": true,
    "description": "ORCHESTRATOR + MCP routing intelligence for optimal tool selection",
    "performance_target_ms": 200,
    "features": [
      "intelligent_tool_routing",
      "mcp_server_selection", 
      "performance_optimization",
      "context_aware_configuration",
      "fallback_strategy_implementation",
      "real_time_adaptation"
    ],
    "configuration": {
      "mcp_intelligence": true,
      "pattern_detection": true,
      "learning_adaptations": true,
      "performance_optimization": true,
      "fallback_strategies": true
    },
    "integration": {
      "mcp_servers": ["context7", "sequential", "magic", "playwright", "morphllm", "serena"],
      "quality_gates": true,
      "learning_engine": true
    }
  }
}

MCP Server Integration Configuration

{
  "mcp_server_integration": {
    "enabled": true,
    "servers": {
      "context7": {
        "description": "Library documentation and framework patterns",
        "capabilities": ["documentation_access", "framework_patterns", "best_practices"],
        "performance_profile": "standard"
      },
      "sequential": {
        "description": "Multi-step reasoning and complex analysis", 
        "capabilities": ["complex_reasoning", "systematic_analysis", "hypothesis_testing"],
        "performance_profile": "intensive"
      },
      "serena": {
        "description": "Semantic analysis and memory management",
        "capabilities": ["semantic_understanding", "project_context", "memory_management"],
        "performance_profile": "standard"
      }
    },
    "coordination": {
      "intelligent_routing": true,
      "fallback_strategies": true,
      "performance_optimization": true,
      "learning_adaptation": true
    }
  }
}

Runtime Configuration Loading

class PreToolUseHook:
    def __init__(self):
        # Load hook-specific configuration
        self.hook_config = config_loader.get_hook_config('pre_tool_use')
        
        # Load orchestrator configuration (YAML or fallback)
        try:
            self.orchestrator_config = config_loader.load_config('orchestrator')
        except FileNotFoundError:
            self.orchestrator_config = self.hook_config.get('configuration', {})
        
        # Performance targets from configuration
        self.performance_target_ms = config_loader.get_hook_config(
            'pre_tool_use', 'performance_target_ms', 200
        )

---

Learning Integration

Learning Data Collection

Operation Pattern Recording:

def record_tool_learning(context, tool_config):
    self.learning_engine.record_learning_event(
        LearningType.OPERATION_PATTERN,
        AdaptationScope.USER,
        context,
        {
            'tool_name': context['tool_name'],
            'mcp_servers_used': tool_config.get('mcp_integration', {}).get('servers', []),
            'execution_strategy': tool_config.get('execution_metadata', {}).get('intelligence_level'),
            'optimizations_applied': tool_config.get('performance_optimization', {}).get('optimizations', [])
        },
        effectiveness_score=0.8,  # Updated after execution
        confidence_score=0.7,
        metadata={'hook': 'pre_tool_use', 'version': '1.0'}
    )

Adaptive Routing Enhancement

Learning-Based Routing Improvements:

• User Preferences: Learn individual user's tool and server preferences
• Project Patterns: Adapt to project-specific optimal routing strategies
• Performance Optimization: Route based on historical performance data
• Error Pattern Recognition: Avoid routing strategies that historically failed

Learning Scope Hierarchy

Learning Scopes:
1. Session Level: Real-time adaptation within current session
2. User Level: Personal routing preferences across sessions
3. Project Level: Project-specific optimization patterns
4. Global Level: Framework-wide routing intelligence

Effectiveness Measurement

Effectiveness Metrics:
- execution_time: Actual vs estimated execution time
- success_rate: Successful operation completion rate
- quality_score: Output quality assessment
- user_satisfaction: Implicit feedback from continued usage
- resource_efficiency: Resource utilization optimization

---

Performance Optimization

Caching Strategies

Pattern Recognition Cache

Cache Structure:
- Key: hash(user_intent + tool_name + context_hash)
- Value: routing_decision + confidence_score
- TTL: 60 minutes for pattern stability
- Size: 1000 entries with LRU eviction

MCP Server Response Cache

Cache Strategy:
- Documentation lookups: 30 minutes TTL
- Analysis results: Session-scoped cache
- Pattern templates: 1 hour TTL
- Server availability: 5 minutes TTL

Performance Optimizations

Optimization Techniques:
1. Pre-computed Routing Tables: Common patterns pre-calculated
2. Lazy Loading: Load components only when needed
3. Parallel Analysis: Run pattern detection and MCP planning concurrently
4. Result Reuse: Cache and reuse analysis results within session
5. Intelligent Fallbacks: Fast fallback paths for common failure modes

Resource Management

Resource Optimization:
- Memory: Bounded caches with intelligent eviction
- CPU: Parallel processing for independent operations
- I/O: Batch operations where possible
- Network: Connection pooling for MCP servers

Execution Time Optimization

Time Budget Allocation:
- Pattern Detection: 50ms (25%)
- MCP Server Selection: 30ms (15%)
- Configuration Generation: 40ms (20%)
- Learning Integration: 20ms (10%)
- Buffer/Safety Margin: 60ms (30%)
Total Target: 200ms

---

Integration with ORCHESTRATOR.md

Pattern Matching Implementation

The hook implements the ORCHESTRATOR.md pattern matching system:

# Quick Pattern Matching from ORCHESTRATOR.md
pattern_mappings = {
    'ui_component': {
        'keywords': ['component', 'design', 'frontend', 'UI'],
        'mcp_server': 'magic',
        'persona': 'frontend'
    },
    'deep_analysis': {
        'keywords': ['architecture', 'complex', 'system-wide'],
        'mcp_server': 'sequential',
        'thinking_mode': 'think_hard'
    },
    'large_scope': {
        'keywords': ['many files', 'entire codebase'],
        'mcp_server': 'serena',
        'delegation': True
    },
    'symbol_operations': {
        'keywords': ['rename', 'refactor', 'extract', 'move'],
        'mcp_server': 'serena',
        'precision': 'lsp'
    },
    'pattern_edits': {
        'keywords': ['framework', 'style', 'cleanup'],
        'mcp_server': 'morphllm',
        'optimization': 'token'
    }
}

Resource Zone Implementation

def get_resource_zone(resource_usage):
    if resource_usage <= 0.75:
        return 'green_zone'    # Full capabilities
    elif resource_usage <= 0.85:
        return 'yellow_zone'   # Efficiency mode
    else:
        return 'red_zone'      # Essential operations only

Tool Selection Guide Integration

The hook implements the ORCHESTRATOR.md tool selection guide:

def apply_orchestrator_routing(context, user_intent):
    """Apply ORCHESTRATOR.md routing patterns"""
    
    # MCP Server selection based on ORCHESTRATOR.md
    if any(word in user_intent.lower() for word in ['library', 'docs', 'framework']):
        return ['context7']
    
    if any(word in user_intent.lower() for word in ['complex', 'analysis', 'debug']):
        return ['sequential']
    
    if any(word in user_intent.lower() for word in ['component', 'ui', 'design']):
        return ['magic']
    
    if context.get('file_count', 1) > 5:
        return ['serena']
    
    # Default to native tools for simple operations
    return []

Quality Gate Integration

Quality Gates Applied:
- Step 1 (Syntax Validation): Tool parameter validation
- Step 2 (Type Analysis): Context type checking and compatibility
- Performance Monitoring: Real-time execution time tracking
- Fallback Validation: Ensure fallback strategies maintain functionality

Auto-Activation Rules Implementation

The hook implements ORCHESTRATOR.md auto-activation rules:

def apply_auto_activation_rules(context):
    """Apply ORCHESTRATOR.md auto-activation patterns"""
    
    activations = []
    
    # Enable Sequential for complex operations
    if (context.get('complexity_score', 0) > 0.6 or 
        context.get('requires_intelligence')):
        activations.append('sequential')
    
    # Enable Serena for multi-file operations
    if (context.get('file_count', 1) > 5 or 
        any(op in context.get('operation_sequence', []) for op in ['rename', 'extract'])):
        activations.append('serena')
    
    # Enable delegation for large operations
    if (context.get('file_count', 1) > 3 or 
        context.get('directory_count', 1) > 2):
        activations.append('delegation')
    
    return activations

---

Technical Implementation Details

Core Architecture Components

1. Framework Logic Integration

from framework_logic import FrameworkLogic, OperationContext, OperationType, RiskLevel

# Provides SuperClaude framework intelligence
self.framework_logic = FrameworkLogic()

2. Pattern Detection Engine

from pattern_detection import PatternDetector, PatternMatch

# Analyzes patterns for routing decisions
detection_result = self.pattern_detector.detect_patterns(
    user_intent, context, operation_data
)

3. MCP Intelligence Coordination

from mcp_intelligence import MCPIntelligence, MCPActivationPlan

# Creates optimal MCP server activation plans
mcp_plan = self.mcp_intelligence.create_activation_plan(
    user_intent, context, operation_data
)

4. Learning Engine Integration

from learning_engine import LearningEngine

# Applies learned adaptations and records new patterns
enhanced_routing = self.learning_engine.apply_adaptations(context, base_routing)

Error Handling Architecture

Exception Handling Strategy:
1. Catch all exceptions during routing analysis
2. Log error with context for debugging
3. Generate fallback configuration
4. Preserve user intent and operation continuity
5. Record error for learning and improvement

Performance Monitoring

Performance Tracking:
- Initialization time measurement
- Per-operation execution time tracking
- Target compliance validation (<200ms)
- Efficiency score calculation
- Resource utilization monitoring

---

Usage Examples

Example 1: Simple File Read

Input Request:
{
  "tool_name": "Read",
  "parameters": {"file_path": "/src/components/Button.tsx"},
  "user_intent": "read button component"
}

Hook Enhancement:
{
  "tool_name": "Read",
  "enhanced_mode": false,
  "mcp_integration": {"enabled": false},
  "execution_metadata": {
    "complexity_score": 0.0,
    "intelligence_level": "low"
  }
}

Example 2: Complex Multi-File Analysis

Input Request:
{
  "tool_name": "Analyze", 
  "parameters": {"directory": "/src/**/*.ts"},
  "user_intent": "analyze typescript architecture patterns"
}

Hook Enhancement:
{
  "tool_name": "Analyze",
  "enhanced_mode": true,
  "mcp_integration": {
    "enabled": true,
    "servers": ["sequential", "serena"],
    "coordination_strategy": "collaborative"
  },
  "performance_optimization": {
    "parallel_execution": true,
    "optimizations": ["parallel_file_processing"]
  },
  "execution_metadata": {
    "complexity_score": 0.75,
    "intelligence_level": "high"
  }
}

Example 3: UI Component Generation

Input Request:
{
  "tool_name": "Generate",
  "parameters": {"component_type": "form"},
  "user_intent": "create login form component"
}

Hook Enhancement:
{
  "tool_name": "Generate",
  "enhanced_mode": true,
  "mcp_integration": {
    "enabled": true,
    "servers": ["magic", "context7"],
    "coordination_strategy": "sequential_handoff"
  },
  "build_operations": {
    "framework_integration": true,
    "component_generation": true,
    "quality_validation": true
  }
}

---

Monitoring and Debugging

Performance Metrics

Tracked Metrics:
- routing_time_ms: Time spent in routing analysis
- target_met: Boolean indicating <200ms compliance
- efficiency_score: Overall routing effectiveness (0.0-1.0)
- mcp_servers_activated: Count of MCP servers coordinated
- optimizations_applied: List of performance optimizations
- fallback_triggered: Boolean indicating fallback usage

Logging Integration

Log Events:
- Hook start: Tool name and parameters
- Routing decisions: MCP server selection rationale
- Execution strategy: Chosen execution approach
- Performance metrics: Timing and efficiency data
- Error events: Failures and fallback triggers
- Hook completion: Success/failure status

Debug Information

Debug Output:
- Pattern detection results with confidence scores
- MCP server capability matching analysis
- Optimization opportunity identification
- Learning adaptation application
- Configuration generation process
- Performance target validation

---

Related Documentation

• ORCHESTRATOR.md: Core routing patterns and coordination strategies
• Framework Integration: Quality gates and mode coordination
• MCP Server Documentation: Individual server capabilities and integration
• Learning Engine: Adaptive intelligence and pattern recognition
• Performance Monitoring: System-wide performance tracking and optimization

---

The pre_tool_use hook serves as the intelligent routing engine for the SuperClaude framework, ensuring optimal tool selection, MCP server coordination, and performance optimization for every operation within Claude Code.