🌊 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
checkpoint: File edit:
rUv8cf7eb41f836
diff --git a/v3/@claude-flow/cli/src/commands/index.ts b/v3/@claude-flow/cli/src/commands/index.tsindex 8cdf8b367b..102abcbce7 100644--- a/v3/@claude-flow/cli/src/commands/index.ts+++ b/v3/@claude-flow/cli/src/commands/index.ts@@ -10,6 +10,7 @@ import { memoryCommand } from './memory.js';import { mcpCommand } from './mcp.js';import { configCommand } from './config.js';import { migrateCommand } from './migrate.js';+import { hooksCommand } from './hooks.js';// Export all commandsexport { agentCommand } from './agent.js';@@ -18,6 +19,7 @@ export { memoryCommand } from './memory.js';export { mcpCommand } from './mcp.js';export { configCommand } from './config.js';export { migrateCommand } from './migrate.js';+export { hooksCommand } from './hooks.js';/*** All available commands@@ -28,7 +30,8 @@ export const commands: Command[] = [memoryCommand,mcpCommand,configCommand,- migrateCommand+ migrateCommand,+ hooksCommand];/**diff --git a/v3/@claude-flow/shared/src/hooks/hooks.test.ts b/v3/@claude-flow/shared/src/hooks/hooks.test.tsnew file mode 100644index 0000000000..ddf2e91fcb--- /dev/null+++ b/v3/@claude-flow/shared/src/hooks/hooks.test.ts@@ -0,0 +1,421 @@+/**+ * V3 Hooks System - Tests+ *+ * Comprehensive tests for hook registry and executor.+ *+ * @module v3/shared/hooks/hooks.test+ */++import { describe, it, expect, beforeEach, vi } from 'vitest';+import { HookRegistry, createHookRegistry } from './registry.js';+import { HookExecutor, createHookExecutor } from './executor.js';+import { HookEvent, HookPriority, HookContext, HookResult } from './types.js';+import { createEventBus } from '../core/event-bus.js';++describe('HookRegistry', () => {+ let registry: HookRegistry;++ beforeEach(() => {+ registry = createHookRegistry();+ });++ it('should register a hook', () => {+ const handler = vi.fn();+ const id = registry.register(HookEvent.PreToolUse, handler);++ expect(id).toBeDefined();+ expect(registry.has(id)).toBe(true);+ expect(registry.count()).toBe(1);+ });++ it('should unregister a hook', () => {+ const handler = vi.fn();+ const id = registry.register(HookEvent.PreToolUse, handler);++ const result = registry.unregister(id);++ expect(result).toBe(true);+ expect(registry.has(id)).toBe(false);+ expect(registry.count()).toBe(0);+ });++ it('should return false when unregistering non-existent hook', () => {+ const result = registry.unregister('non-existent');+ expect(result).toBe(false);+ });++ it('should get handlers sorted by priority', () => {+ const handler1 = vi.fn();+ const handler2 = vi.fn();+ const handler3 = vi.fn();++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.Normal);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler3, HookPriority.Low);++ const handlers = registry.getHandlers(HookEvent.PreToolUse);++ expect(handlers).toHaveLength(3);+ expect(handlers[0].handler).toBe(handler2); // High priority first+ expect(handlers[1].handler).toBe(handler1); // Normal priority second+ expect(handlers[2].handler).toBe(handler3); // Low priority last+ });++ it('should filter disabled hooks', () => {+ const handler = vi.fn();+ const id = registry.register(HookEvent.PreToolUse, handler, HookPriority.Normal, {+ enabled: false,+ });++ const handlers = registry.getHandlers(HookEvent.PreToolUse);+ const allHandlers = registry.getHandlers(HookEvent.PreToolUse, true);++ expect(handlers).toHaveLength(0);+ expect(allHandlers).toHaveLength(1);+ });++ it('should enable and disable hooks', () => {+ const handler = vi.fn();+ const id = registry.register(HookEvent.PreToolUse, handler);++ registry.disable(id);+ expect(registry.getHandlers(HookEvent.PreToolUse)).toHaveLength(0);++ registry.enable(id);+ expect(registry.getHandlers(HookEvent.PreToolUse)).toHaveLength(1);+ });++ it('should list hooks with filters', () => {+ registry.register(HookEvent.PreToolUse, vi.fn(), HookPriority.High);+ registry.register(HookEvent.PostToolUse, vi.fn(), HookPriority.Normal);+ registry.register(HookEvent.PreEdit, vi.fn(), HookPriority.Low);++ const allHooks = registry.listHooks();+ expect(allHooks).toHaveLength(3);++ const preToolHooks = registry.listHooks({ event: HookEvent.PreToolUse });+ expect(preToolHooks).toHaveLength(1);++ const highPriorityHooks = registry.listHooks({ minPriority: HookPriority.Normal });+ expect(highPriorityHooks).toHaveLength(2);+ });++ it('should get event types', () => {+ registry.register(HookEvent.PreToolUse, vi.fn());+ registry.register(HookEvent.PostToolUse, vi.fn());+ registry.register(HookEvent.PreEdit, vi.fn());++ const eventTypes = registry.getEventTypes();+ expect(eventTypes).toContain(HookEvent.PreToolUse);+ expect(eventTypes).toContain(HookEvent.PostToolUse);+ expect(eventTypes).toContain(HookEvent.PreEdit);+ });++ it('should track statistics', () => {+ registry.register(HookEvent.PreToolUse, vi.fn());+ registry.register(HookEvent.PostToolUse, vi.fn());++ registry.recordExecution(true, 10);+ registry.recordExecution(true, 20);+ registry.recordExecution(false, 5);++ const stats = registry.getStats();+ expect(stats.totalHooks).toBe(2);+ expect(stats.totalExecutions).toBe(3);+ expect(stats.totalFailures).toBe(1);+ expect(stats.avgExecutionTime).toBe((10 + 20 + 5) / 3);+ });++ it('should reset statistics', () => {+ registry.recordExecution(true, 10);+ registry.resetStats();++ const stats = registry.getStats();+ expect(stats.totalExecutions).toBe(0);+ expect(stats.totalFailures).toBe(0);+ });++ it('should clear all hooks', () => {+ registry.register(HookEvent.PreToolUse, vi.fn());+ registry.register(HookEvent.PostToolUse, vi.fn());++ registry.clear();++ expect(registry.count()).toBe(0);+ expect(registry.getEventTypes()).toHaveLength(0);+ });+});++describe('HookExecutor', () => {+ let registry: HookRegistry;+ let executor: HookExecutor;+ let eventBus: any;++ beforeEach(() => {+ registry = createHookRegistry();+ eventBus = createEventBus();+ executor = createHookExecutor(registry, eventBus);+ });++ it('should execute single hook successfully', async () => {+ const handler = vi.fn(async () => ({ success: true }));+ registry.register(HookEvent.PreToolUse, handler);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ tool: { name: 'Read', parameters: { path: 'file.ts' } },+ };++ const result = await executor.execute(HookEvent.PreToolUse, context);++ expect(result.success).toBe(true);+ expect(result.hooksExecuted).toBe(1);+ expect(result.hooksFailed).toBe(0);+ expect(handler).toHaveBeenCalledWith(context);+ });++ it('should execute multiple hooks in priority order', async () => {+ const executionOrder: number[] = [];++ const handler1 = vi.fn(async () => {+ executionOrder.push(1);+ return { success: true };+ });+ const handler2 = vi.fn(async () => {+ executionOrder.push(2);+ return { success: true };+ });+ const handler3 = vi.fn(async () => {+ executionOrder.push(3);+ return { success: true };+ });++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.Normal);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler3, HookPriority.Low);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ await executor.execute(HookEvent.PreToolUse, context);++ expect(executionOrder).toEqual([2, 1, 3]); // High, Normal, Low+ });++ it('should handle hook errors gracefully', async () => {+ const handler1 = vi.fn(async () => ({ success: true }));+ const handler2 = vi.fn(async () => {+ throw new Error('Hook failed');+ });+ const handler3 = vi.fn(async () => ({ success: true }));++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.Normal);+ registry.register(HookEvent.PreToolUse, handler3, HookPriority.Low);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.execute(HookEvent.PreToolUse, context, {+ continueOnError: true,+ });++ expect(result.hooksExecuted).toBe(3);+ expect(result.hooksFailed).toBe(1);+ expect(handler3).toHaveBeenCalled(); // Should continue despite error+ });++ it('should abort on error when continueOnError is false', async () => {+ const handler1 = vi.fn(async () => ({ success: true }));+ const handler2 = vi.fn(async () => {+ throw new Error('Hook failed');+ });+ const handler3 = vi.fn(async () => ({ success: true }));++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.Normal);+ registry.register(HookEvent.PreToolUse, handler3, HookPriority.Low);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.execute(HookEvent.PreToolUse, context);++ expect(result.aborted).toBe(true);+ expect(result.hooksExecuted).toBe(2);+ expect(handler3).not.toHaveBeenCalled(); // Should not execute after error+ });++ it('should abort when hook returns abort flag', async () => {+ const handler1 = vi.fn(async () => ({ success: true }));+ const handler2 = vi.fn(async () => ({ success: true, abort: true }));+ const handler3 = vi.fn(async () => ({ success: true }));++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.Normal);+ registry.register(HookEvent.PreToolUse, handler3, HookPriority.Low);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.execute(HookEvent.PreToolUse, context);++ expect(result.aborted).toBe(true);+ expect(result.hooksExecuted).toBe(2);+ expect(handler3).not.toHaveBeenCalled();+ });++ it('should merge context modifications', async () => {+ const handler1 = vi.fn(async () => ({+ success: true,+ data: { metadata: { modified: true } },+ }));+ const handler2 = vi.fn(async (context: HookContext) => {+ expect(context.metadata?.modified).toBe(true);+ return { success: true };+ });++ registry.register(HookEvent.PreToolUse, handler1, HookPriority.High);+ registry.register(HookEvent.PreToolUse, handler2, HookPriority.Normal);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.execute(HookEvent.PreToolUse, context);++ expect(result.finalContext?.metadata).toEqual({ modified: true });+ });++ it('should handle timeout', async () => {+ const handler = vi.fn(async () => {+ await new Promise(resolve => setTimeout(resolve, 200));+ return { success: true };+ });++ registry.register(HookEvent.PreToolUse, handler);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.executeWithTimeout(HookEvent.PreToolUse, context, 100);++ expect(result.success).toBe(false);+ expect(result.hooksFailed).toBe(1);+ });++ it('should execute hooks in parallel', async () => {+ const handler1 = vi.fn(async () => ({ success: true }));+ const handler2 = vi.fn(async () => ({ success: true }));++ registry.register(HookEvent.PreToolUse, handler1);+ registry.register(HookEvent.PostToolUse, handler2);++ const contexts: HookContext[] = [+ { event: HookEvent.PreToolUse, timestamp: new Date() },+ { event: HookEvent.PostToolUse, timestamp: new Date() },+ ];++ const results = await executor.executeParallel(+ [HookEvent.PreToolUse, HookEvent.PostToolUse],+ contexts+ );++ expect(results).toHaveLength(2);+ expect(results[0].success).toBe(true);+ expect(results[1].success).toBe(true);+ });++ it('should execute hooks sequentially with context chaining', async () => {+ const handler1 = vi.fn(async () => ({+ success: true,+ data: { metadata: { step: 1 } },+ }));+ const handler2 = vi.fn(async () => ({+ success: true,+ data: { metadata: { step: 2 } },+ }));++ registry.register(HookEvent.PreToolUse, handler1);+ registry.register(HookEvent.PostToolUse, handler2);++ const initialContext: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.executeSequential(+ [HookEvent.PreToolUse, HookEvent.PostToolUse],+ initialContext+ );++ expect(result.success).toBe(true);+ expect(result.hooksExecuted).toBe(2);+ });++ it('should emit events to event bus', async () => {+ const preExecuteHandler = vi.fn();+ const postExecuteHandler = vi.fn();++ eventBus.on('hooks:pre-execute', preExecuteHandler);+ eventBus.on('hooks:post-execute', postExecuteHandler);++ const handler = vi.fn(async () => ({ success: true }));+ registry.register(HookEvent.PreToolUse, handler);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ await executor.execute(HookEvent.PreToolUse, context);++ expect(preExecuteHandler).toHaveBeenCalled();+ expect(postExecuteHandler).toHaveBeenCalled();+ });++ it('should skip disabled hooks', async () => {+ const handler = vi.fn(async () => ({ success: true }));+ const id = registry.register(HookEvent.PreToolUse, handler, HookPriority.Normal, {+ enabled: false,+ });++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ const result = await executor.execute(HookEvent.PreToolUse, context);++ expect(result.hooksExecuted).toBe(0);+ expect(handler).not.toHaveBeenCalled();+ });++ it('should record execution statistics', async () => {+ const handler = vi.fn(async () => ({ success: true }));+ registry.register(HookEvent.PreToolUse, handler);++ const context: HookContext = {+ event: HookEvent.PreToolUse,+ timestamp: new Date(),+ };++ await executor.execute(HookEvent.PreToolUse, context);++ const stats = registry.getStats();+ expect(stats.totalExecutions).toBe(1);+ expect(stats.totalFailures).toBe(0);+ });+});diff --git a/v3/@claude-flow/shared/src/hooks/index.ts b/v3/@claude-flow/shared/src/hooks/index.tsnew file mode 100644index 0000000000..308e4e9238--- /dev/null+++ b/v3/@claude-flow/shared/src/hooks/index.ts@@ -0,0 +1,79 @@+/**+ * V3 Hooks System - Main Export+ *+ * Provides extensible hook points for tool execution, file operations,+ * and session lifecycle events. Integrates with event bus for coordination.+ *+ * Example usage:+ *+ * ```typescript+ * import { createHookRegistry, createHookExecutor, HookEvent, HookPriority } from '@claude-flow/shared/hooks';+ *+ * const registry = createHookRegistry();+ * const executor = createHookExecutor(registry, eventBus);+ *+ * // Register a hook+ * const hookId = registry.register(+ * HookEvent.PreToolUse,+ * async (context) => {+ * console.log('Before tool use:', context.tool?.name);+ * return { success: true };+ * },+ * HookPriority.High+ * );+ *+ * // Execute hooks+ * const result = await executor.execute(+ * HookEvent.PreToolUse,+ * {+ * event: HookEvent.PreToolUse,+ * timestamp: new Date(),+ * tool: { name: 'Read', parameters: { path: 'file.ts' } }+ * }+ * );+ *+ * // Unregister hook+ * registry.unregister(hookId);+ * ```+ *+ * @module v3/shared/hooks+ */++// Export types+export type {+ HookContext,+ HookResult,+ HookHandler,+ HookDefinition,+ HookStats,+ HookExecutionOptions,+ ToolInfo,+ CommandInfo,+ FileOperationInfo,+ SessionInfo,+ AgentInfo,+ TaskInfo,+ MemoryInfo,+ ErrorInfo,+} from './types.js';++export {+ HookEvent,+ HookPriority,+} from './types.js';++// Export registry+export {+ HookRegistry,+ createHookRegistry,+} from './registry.js';++// Export executor+export type {+ AggregatedHookResult,+} from './executor.js';++export {+ HookExecutor,+ createHookExecutor,+} from './executor.js';