Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

12.4 KB
Raw Blame

V3 Hooks MCP Tools Reference

Overview

The Hooks MCP Tools provide programmatic access to the V3 hooks system through the Model Context Protocol. All tools follow ADR-005 (MCP-First API Design) conventions.

Tools

hooks/pre-edit

Get context, suggestions, and warnings before file edits.

Input Schema:

{
  "type": "object",
  "properties": {
    "filePath": {
      "type": "string",
      "description": "Absolute path to the file being edited"
    },
    "operation": {
      "type": "string",
      "enum": ["create", "modify", "delete"],
      "default": "modify"
    },
    "includeContext": {
      "type": "boolean",
      "default": true,
      "description": "Include file context and related patterns"
    },
    "includeSuggestions": {
      "type": "boolean",
      "default": true,
      "description": "Include agent suggestions"
    }
  },
  "required": ["filePath"]
}

Response:

{
  "filePath": "/path/to/file.ts",
  "operation": "modify",
  "context": {
    "fileExists": true,
    "fileType": "ts",
    "relatedFiles": ["file.test.ts", "types.ts"],
    "similarPatterns": [
      {
        "pattern": "TypeScript module implementation",
        "confidence": 0.85,
        "description": "Similar patterns found in codebase"
      }
    ]
  },
  "suggestions": [
    {
      "agent": "coder",
      "suggestion": "Use coder for this modify operation",
      "confidence": 0.87,
      "rationale": "Based on file type and operation pattern"
    }
  ],
  "warnings": []
}

hooks/post-edit

Record edit outcomes for learning. Stores trajectories in ReasoningBank.

Input Schema:

{
  "type": "object",
  "properties": {
    "filePath": {
      "type": "string",
      "description": "Absolute path to the file that was edited"
    },
    "operation": {
      "type": "string",
      "enum": ["create", "modify", "delete"],
      "default": "modify"
    },
    "success": {
      "type": "boolean",
      "description": "Whether the edit was successful"
    },
    "outcome": {
      "type": "string",
      "description": "Description of the outcome"
    },
    "metadata": {
      "type": "object",
      "description": "Additional metadata"
    }
  },
  "required": ["filePath", "success"]
}

Response:

{
  "filePath": "/path/to/file.ts",
  "operation": "modify",
  "success": true,
  "recorded": true,
  "recordedAt": "2025-01-05T12:00:00.000Z",
  "patternId": "mem_abc123"
}

hooks/pre-command

Risk assessment before command execution.

Input Schema:

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "Command to be executed"
    },
    "workingDirectory": {
      "type": "string",
      "description": "Working directory for command execution"
    },
    "includeRiskAssessment": {
      "type": "boolean",
      "default": true
    },
    "includeSuggestions": {
      "type": "boolean",
      "default": true
    }
  },
  "required": ["command"]
}

Response:

{
  "command": "rm -rf ./temp",
  "riskAssessment": {
    "riskLevel": "high",
    "concerns": [
      "Command is potentially destructive",
      "May result in data loss"
    ],
    "recommendations": [
      "Review command carefully",
      "Consider backing up data first",
      "Use --dry-run if available"
    ]
  },
  "suggestions": [
    {
      "type": "safety",
      "suggestion": "Add error handling with try-catch",
      "rationale": "Previous similar commands benefited from error handling"
    }
  ],
  "shouldProceed": false,
  "warnings": ["HIGH RISK: This command may be destructive"]
}

hooks/post-command

Record command execution outcomes for learning.

Input Schema:

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string"
    },
    "exitCode": {
      "type": "number",
      "default": 0
    },
    "success": {
      "type": "boolean"
    },
    "output": {
      "type": "string"
    },
    "error": {
      "type": "string"
    },
    "executionTime": {
      "type": "number",
      "minimum": 0,
      "description": "Execution time in milliseconds"
    },
    "metadata": {
      "type": "object"
    }
  },
  "required": ["command", "success"]
}

Response:

{
  "command": "npm test",
  "success": true,
  "recorded": true,
  "recordedAt": "2025-01-05T12:00:00.000Z",
  "patternId": "mem_def456",
  "executionTime": 5230
}

hooks/route

Route a task to the optimal agent based on learned patterns.

Input Schema:

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "description": "Task description to route"
    },
    "context": {
      "type": "string",
      "description": "Additional context about the task"
    },
    "preferredAgents": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of preferred agent types"
    },
    "constraints": {
      "type": "object",
      "description": "Routing constraints"
    },
    "includeExplanation": {
      "type": "boolean",
      "default": true
    }
  },
  "required": ["task"]
}

Response:

{
  "task": "Implement user authentication",
  "recommendedAgent": "security-auditor",
  "confidence": 0.92,
  "alternativeAgents": [
    { "agent": "coder", "confidence": 0.78 },
    { "agent": "backend-dev", "confidence": 0.75 }
  ],
  "explanation": "Based on task analysis and 15 similar historical tasks, 'security-auditor' is recommended with 92% confidence.",
  "reasoning": {
    "factors": [
      { "factor": "Task keywords match", "weight": 0.4, "value": 0.95 },
      { "factor": "Historical performance", "weight": 0.3, "value": 0.90 },
      { "factor": "Agent specialization", "weight": 0.2, "value": 0.95 },
      { "factor": "Current availability", "weight": 0.1, "value": 1.0 }
    ],
    "historicalPerformance": [
      { "agent": "security-auditor", "successRate": 0.94, "avgQuality": 0.91, "tasksSimilar": 12 }
    ]
  }
}

hooks/explain

Explain routing decision with transparency.

Input Schema:

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "description": "Task description to explain routing for"
    },
    "context": {
      "type": "string"
    },
    "verbose": {
      "type": "boolean",
      "default": false,
      "description": "Include detailed reasoning"
    }
  },
  "required": ["task"]
}

Response:

{
  "task": "Fix authentication bug in login flow",
  "recommendedAgent": "debugger",
  "explanation": "Based on task analysis and 8 similar historical tasks, 'debugger' is recommended with 88% confidence.",
  "reasoning": {
    "primaryFactors": [
      "Task keyword analysis",
      "Historical performance data",
      "Agent specialization match"
    ],
    "historicalData": {
      "similarTasksCount": 8,
      "avgSuccessRate": 0.87,
      "topPerformingAgents": [
        { "agent": "debugger", "performance": 0.91 },
        { "agent": "coder", "performance": 0.82 }
      ]
    },
    "patternMatching": {
      "matchedPatterns": 5,
      "relevantPatterns": [
        { "pattern": "Bug fix workflow", "relevance": 0.89 },
        { "pattern": "Authentication handling", "relevance": 0.85 }
      ]
    }
  },
  "alternatives": [
    { "agent": "coder", "whyNotBest": "Lower confidence (78%) and less historical success on similar tasks" }
  ]
}

hooks/pretrain

Bootstrap intelligence from repository analysis.

Input Schema:

{
  "type": "object",
  "properties": {
    "repositoryPath": {
      "type": "string",
      "description": "Path to repository (defaults to current directory)"
    },
    "includeGitHistory": {
      "type": "boolean",
      "default": true
    },
    "includeDependencies": {
      "type": "boolean",
      "default": true
    },
    "maxPatterns": {
      "type": "number",
      "minimum": 1,
      "maximum": 10000,
      "default": 1000
    },
    "force": {
      "type": "boolean",
      "default": false,
      "description": "Force retraining even if data exists"
    }
  }
}

Response:

{
  "success": true,
  "repositoryPath": "/workspaces/claude-flow",
  "statistics": {
    "filesAnalyzed": 247,
    "patternsExtracted": 156,
    "commitsAnalyzed": 1523,
    "dependenciesAnalyzed": 42,
    "executionTime": 3450.5
  },
  "patterns": {
    "byCategory": {
      "code-implementation": 89,
      "testing": 34,
      "documentation": 12,
      "refactoring": 15,
      "bug-fixes": 6
    },
    "byAgent": {
      "coder": 95,
      "tester": 28,
      "reviewer": 18,
      "researcher": 10,
      "planner": 5
    }
  },
  "recommendations": [
    "Strong TypeScript patterns detected - recommend coder agent for TS tasks",
    "High test coverage patterns - tester agent performs well",
    "Consistent code review practices - reviewer agent recommended for quality checks"
  ]
}

hooks/metrics

Get learning metrics and statistics.

Input Schema:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["all", "routing", "edits", "commands", "patterns"],
      "default": "all"
    },
    "timeRange": {
      "type": "string",
      "enum": ["hour", "day", "week", "month", "all"],
      "default": "all"
    },
    "includeDetailedStats": {
      "type": "boolean",
      "default": false
    },
    "format": {
      "type": "string",
      "enum": ["json", "summary"],
      "default": "summary"
    }
  }
}

Response:

{
  "category": "all",
  "timeRange": "all",
  "summary": {
    "totalOperations": 1547,
    "successRate": 0.89,
    "avgQuality": 0.85,
    "patternsLearned": 156
  },
  "routing": {
    "totalRoutes": 423,
    "avgConfidence": 0.84,
    "topAgents": [
      { "agent": "coder", "count": 189, "successRate": 0.91 },
      { "agent": "tester", "count": 87, "successRate": 0.88 },
      { "agent": "reviewer", "count": 65, "successRate": 0.92 }
    ]
  },
  "edits": {
    "totalEdits": 756,
    "successRate": 0.93,
    "commonPatterns": ["TypeScript modification", "Test file creation"]
  },
  "commands": {
    "totalCommands": 368,
    "successRate": 0.82,
    "avgExecutionTime": 2340,
    "commonCommands": ["npm test", "npm run build", "git status"]
  }
}

hooks/list

List registered hooks with filtering.

Input Schema:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["all", "pre-edit", "post-edit", "pre-command", "post-command", "routing"],
      "default": "all"
    },
    "includeDisabled": {
      "type": "boolean",
      "default": false
    },
    "includeMetadata": {
      "type": "boolean",
      "default": true
    }
  }
}

Response:

{
  "hooks": [
    {
      "name": "pre-edit-validation",
      "category": "pre-edit",
      "enabled": true,
      "priority": 100,
      "executionCount": 1523,
      "lastExecuted": "2025-01-05T11:55:00.000Z",
      "metadata": {
        "version": "1.0.0",
        "reasoningBankEnabled": true
      }
    },
    {
      "name": "intelligent-routing",
      "category": "routing",
      "enabled": true,
      "priority": 100,
      "executionCount": 423,
      "lastExecuted": "2025-01-05T11:58:00.000Z",
      "metadata": {
        "version": "1.0.0",
        "reasoningBankEnabled": true,
        "agentdbEnabled": true
      }
    }
  ],
  "total": 5,
  "byCategory": {
    "pre-edit": 1,
    "post-edit": 1,
    "pre-command": 1,
    "post-command": 1,
    "routing": 1
  }
}

Tool Categories and Tags

All hooks tools are categorized and tagged for discovery:

Tool Category Tags
hooks/pre-edit hooks hooks, pre-edit, learning, reasoningbank
hooks/post-edit hooks hooks, post-edit, learning, reasoningbank
hooks/pre-command hooks hooks, pre-command, safety, risk-assessment
hooks/post-command hooks hooks, post-command, learning, reasoningbank
hooks/route hooks hooks, routing, ai, reasoningbank, learning
hooks/explain hooks hooks, routing, explanation, transparency
hooks/pretrain hooks hooks, pretraining, intelligence, reasoningbank
hooks/metrics hooks hooks, metrics, analytics, performance
hooks/list hooks hooks, list, registry

Caching

Some tools support caching for improved performance:

Tool Cacheable Cache TTL
hooks/route Yes 5000ms
hooks/explain Yes 5000ms
hooks/metrics Yes 10000ms
hooks/list Yes 5000ms