claude-flow 3.7.0-alpha.21 → 3.7.0-alpha.22

package/v3/@claude-flow/cli/dist/src/mcp-tools/guidance-tools.js

@@ -46,7 +46,7 @@ const PROJECT_ROOT = findProjectRoot();
 const CAPABILITY_CATALOG = {
     'agent-management': {
         name: 'Agent Management',
-        description: 'Spawn, manage, and monitor individual AI agents with lifecycle control.',
+        description: 'Spawn, manage, and monitor individual AI agents with lifecycle control. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['agent_spawn', 'agent_list', 'agent_status', 'agent_stop', 'agent_metrics', 'agent_pool', 'agent_health', 'agent_logs'],
         commands: ['agent spawn', 'agent list', 'agent status', 'agent stop', 'agent metrics', 'agent pool', 'agent health', 'agent logs'],
         agents: ['coder', 'tester', 'reviewer', 'researcher', 'planner'],
@@ -55,7 +55,7 @@ const CAPABILITY_CATALOG = {
     },
     'swarm-orchestration': {
         name: 'Swarm Orchestration',
-        description: 'Multi-agent coordination with topology-aware communication and consensus.',
+        description: 'Multi-agent coordination with topology-aware communication and consensus. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['swarm_init', 'swarm_status', 'swarm_spawn', 'swarm_terminate', 'swarm_topology', 'swarm_metrics'],
         commands: ['swarm init', 'swarm status', 'swarm spawn', 'swarm terminate'],
         agents: ['hierarchical-coordinator', 'mesh-coordinator', 'adaptive-coordinator', 'queen-coordinator', 'collective-intelligence-coordinator'],
@@ -64,7 +64,7 @@ const CAPABILITY_CATALOG = {
     },
     'memory-knowledge': {
         name: 'Memory & Knowledge',
-        description: 'Persistent memory with HNSW vector search, AgentDB storage, and embeddings.',
+        description: 'Persistent memory with HNSW vector search, AgentDB storage, and embeddings. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['memory_store', 'memory_retrieve', 'memory_search', 'memory_list', 'memory_delete', 'memory_init', 'memory_export', 'memory_import_claude', 'memory_stats', 'memory_compact', 'memory_namespace'],
         commands: ['memory store', 'memory retrieve', 'memory search', 'memory list', 'memory delete', 'memory init'],
         agents: ['swarm-memory-manager', 'v3-memory-specialist'],
@@ -73,7 +73,7 @@ const CAPABILITY_CATALOG = {
     },
     'intelligence-learning': {
         name: 'Intelligence & Learning',
-        description: 'Neural pattern training (SONA), RL loops, Flash Attention, EWC++ consolidation.',
+        description: 'Neural pattern training (SONA), RL loops, Flash Attention, EWC++ consolidation. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['neural_train', 'neural_predict', 'neural_status', 'neural_patterns', 'neural_optimize'],
         commands: ['neural train', 'neural predict', 'neural status', 'neural patterns', 'neural optimize'],
         agents: ['sona-learning-optimizer', 'safla-neural'],
@@ -82,7 +82,7 @@ const CAPABILITY_CATALOG = {
     },
     'hooks-automation': {
         name: 'Hooks & Automation',
-        description: '17 lifecycle hooks + 12 background workers for automated learning and coordination.',
+        description: '17 lifecycle hooks + 12 background workers for automated learning and coordination. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['hooks_pre_task', 'hooks_post_task', 'hooks_pre_edit', 'hooks_post_edit', 'hooks_route', 'hooks_explain'],
         commands: [
             'hooks pre-task', 'hooks post-task', 'hooks pre-edit', 'hooks post-edit',
@@ -97,7 +97,7 @@ const CAPABILITY_CATALOG = {
     },
     'hive-mind': {
         name: 'Hive Mind Consensus',
-        description: 'Queen-led Byzantine fault-tolerant distributed consensus with multiple strategies.',
+        description: 'Queen-led Byzantine fault-tolerant distributed consensus with multiple strategies. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['hive_mind_init', 'hive_mind_status', 'hive_mind_propose', 'hive_mind_vote', 'hive_mind_consensus', 'hive_mind_metrics'],
         commands: ['hive-mind init', 'hive-mind status', 'hive-mind consensus', 'hive-mind sessions', 'hive-mind spawn', 'hive-mind stop'],
         agents: ['byzantine-coordinator', 'raft-manager', 'gossip-coordinator', 'crdt-synchronizer', 'quorum-manager'],
@@ -106,7 +106,7 @@ const CAPABILITY_CATALOG = {
     },
     'security': {
         name: 'Security & Compliance',
-        description: 'Security scanning, CVE remediation, input validation, claims-based authorization.',
+        description: 'Security scanning, CVE remediation, input validation, claims-based authorization. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['security_scan', 'security_audit', 'security_cve', 'security_threats', 'security_validate', 'security_report', 'claims_check', 'claims_grant', 'claims_revoke', 'claims_list'],
         commands: ['security scan', 'security audit', 'security cve', 'security threats', 'claims check', 'claims grant'],
         agents: ['v3-security-architect'],
@@ -115,7 +115,7 @@ const CAPABILITY_CATALOG = {
     },
     'performance': {
         name: 'Performance & Profiling',
-        description: 'Benchmarking, profiling, metrics collection, and optimization recommendations.',
+        description: 'Benchmarking, profiling, metrics collection, and optimization recommendations. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['performance_benchmark', 'performance_profile', 'performance_metrics', 'performance_optimize', 'performance_report'],
         commands: ['performance benchmark', 'performance profile', 'performance metrics', 'performance optimize', 'performance report'],
         agents: ['v3-performance-engineer'],
@@ -124,7 +124,7 @@ const CAPABILITY_CATALOG = {
     },
     'github-integration': {
         name: 'GitHub Integration',
-        description: 'PR management, code review, issue tracking, release automation, multi-repo coordination.',
+        description: 'PR management, code review, issue tracking, release automation, multi-repo coordination. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['github_pr_manage', 'github_code_review', 'github_issue_track', 'github_repo_analyze', 'github_sync_coord', 'github_metrics'],
         commands: [],
         agents: ['pr-manager', 'code-review-swarm', 'issue-tracker', 'release-manager', 'repo-architect', 'workflow-automation', 'multi-repo-swarm', 'project-board-sync', 'swarm-pr', 'swarm-issue', 'sync-coordinator', 'github-modes', 'release-swarm'],
@@ -133,7 +133,7 @@ const CAPABILITY_CATALOG = {
     },
     'session-workflow': {
         name: 'Session & Workflow',
-        description: 'Session state management, workflow execution, task lifecycle, and daemon scheduling.',
+        description: 'Session state management, workflow execution, task lifecycle, and daemon scheduling. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['session_start', 'session_end', 'session_restore', 'session_list', 'workflow_execute', 'workflow_create', 'task_create', 'task_assign', 'task_status'],
         commands: ['session start', 'session end', 'session restore', 'workflow execute', 'workflow create', 'task create', 'daemon start', 'daemon stop'],
         agents: [],
@@ -142,7 +142,7 @@ const CAPABILITY_CATALOG = {
     },
     'embeddings-vectors': {
         name: 'Embeddings & Vector Search',
-        description: 'Vector embeddings with sql.js, HNSW indexing, hyperbolic embeddings, ONNX integration.',
+        description: 'Vector embeddings with sql.js, HNSW indexing, hyperbolic embeddings, ONNX integration. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['embeddings_embed', 'embeddings_batch', 'embeddings_search', 'embeddings_init'],
         commands: ['embeddings embed', 'embeddings batch', 'embeddings search', 'embeddings init'],
         agents: [],
@@ -151,7 +151,7 @@ const CAPABILITY_CATALOG = {
     },
     'wasm-agents': {
         name: 'WASM Sandboxed Agents',
-        description: 'Sandboxed AI agents running in WebAssembly with virtual filesystem, no OS access.',
+        description: 'Sandboxed AI agents running in WebAssembly with virtual filesystem, no OS access. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['wasm_agent_create', 'wasm_agent_prompt', 'wasm_agent_tool', 'wasm_agent_list', 'wasm_agent_terminate', 'wasm_agent_files', 'wasm_agent_export', 'wasm_gallery_list', 'wasm_gallery_search', 'wasm_gallery_create'],
         commands: [],
         agents: [],
@@ -160,7 +160,7 @@ const CAPABILITY_CATALOG = {
     },
     'ruvllm-inference': {
         name: 'RuVLLM Inference',
-        description: 'WASM-based HNSW routing, SONA instant adaptation, MicroLoRA, chat formatting.',
+        description: 'WASM-based HNSW routing, SONA instant adaptation, MicroLoRA, chat formatting. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['ruvllm_status', 'ruvllm_hnsw_create', 'ruvllm_sona_create', 'ruvllm_microlora_create', 'ruvllm_chat_format', 'ruvllm_kvcache_create'],
         commands: [],
         agents: [],
@@ -169,7 +169,7 @@ const CAPABILITY_CATALOG = {
     },
     'code-analysis': {
         name: 'Code Analysis & Diff',
-        description: 'AST analysis, diff classification, coverage routing, dependency graph analysis.',
+        description: 'AST analysis, diff classification, coverage routing, dependency graph analysis. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['analyze_diff', 'analyze_coverage', 'analyze_graph'],
         commands: [],
         agents: ['code-analyzer'],
@@ -178,7 +178,7 @@ const CAPABILITY_CATALOG = {
     },
     'sparc-methodology': {
         name: 'SPARC Methodology',
-        description: 'Specification, Pseudocode, Architecture, Refinement, Completion — structured development.',
+        description: 'Specification, Pseudocode, Architecture, Refinement, Completion — structured development. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: [],
         commands: [],
         agents: ['specification', 'pseudocode', 'architecture', 'refinement'],
@@ -187,7 +187,7 @@ const CAPABILITY_CATALOG = {
     },
     'config-system': {
         name: 'Configuration & System',
-        description: 'Configuration management, provider setup, system diagnostics, shell completions.',
+        description: 'Configuration management, provider setup, system diagnostics, shell completions. Use when native Bash / file tools are wrong because this MCP tool exposes Ruflo-specific state or controllers that have no shell equivalent. For tasks that fit a one-line native command, prefer that.',
         tools: ['config_get', 'config_set', 'config_list', 'config_provider'],
         commands: ['config get', 'config set', 'config list', 'config provider', 'doctor', 'status', 'providers list', 'completions'],
         agents: [],
@@ -331,7 +331,7 @@ function discoverSkills() {
 // ── MCP Tool Definitions ────────────────────────────────────
 const guidanceCapabilities = {
     name: 'guidance_capabilities',
-    description: 'List all capability areas with their tools, commands, agents, and skills. Use this to discover what Ruflo can do.',
+    description: 'List all capability areas with their tools, commands, agents, and skills. Use this to discover what Ruflo can do. Use when generic "what tool should I use?" guessing is wrong — Ruflo\'s guidance system uses the live tool index + your workflow context to recommend. Pair with hooks_route at task start. For trivial native-only tasks, no guidance call is needed.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -379,7 +379,7 @@ const guidanceCapabilities = {
 };
 const guidanceRecommend = {
     name: 'guidance_recommend',
-    description: 'Given a task description, recommend which capability areas, tools, agents, and workflow to use.',
+    description: 'Given a task description, recommend which capability areas, tools, agents, and workflow to use. Use when generic "what tool should I use?" guessing is wrong — Ruflo\'s guidance system uses the live tool index + your workflow context to recommend. Pair with hooks_route at task start. For trivial native-only tasks, no guidance call is needed.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -462,7 +462,7 @@ const guidanceRecommend = {
 };
 const guidanceDiscover = {
     name: 'guidance_discover',
-    description: 'Discover all available agents and skills from the .claude/ directory. Returns live filesystem data.',
+    description: 'Discover all available agents and skills from the .claude/ directory. Returns live filesystem data. Use when generic "what tool should I use?" guessing is wrong — Ruflo\'s guidance system uses the live tool index + your workflow context to recommend. Pair with hooks_route at task start. For trivial native-only tasks, no guidance call is needed.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -489,7 +489,7 @@ const guidanceDiscover = {
 };
 const guidanceWorkflow = {
     name: 'guidance_workflow',
-    description: 'Get a recommended workflow template for a task type. Includes steps, agents, and topology.',
+    description: 'Get a recommended workflow template for a task type. Includes steps, agents, and topology. Use when generic "what tool should I use?" guessing is wrong — Ruflo\'s guidance system uses the live tool index + your workflow context to recommend. Pair with hooks_route at task start. For trivial native-only tasks, no guidance call is needed.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -540,7 +540,7 @@ const guidanceWorkflow = {
 };
 const guidanceQuickRef = {
     name: 'guidance_quickref',
-    description: 'Quick reference card for common operations. Returns the most useful commands for a given domain.',
+    description: 'Quick reference card for common operations. Returns the most useful commands for a given domain. Use when generic "what tool should I use?" guessing is wrong — Ruflo\'s guidance system uses the live tool index + your workflow context to recommend. Pair with hooks_route at task start. For trivial native-only tasks, no guidance call is needed.',
     inputSchema: {
         type: 'object',
         properties: {

package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -143,7 +143,7 @@ function saveAgentStore(store) {
 export const hiveMindTools = [
     {
         name: 'hive-mind_spawn',
-        description: 'Spawn workers and automatically join them to the hive-mind (combines agent/spawn + hive-mind/join)',
+        description: 'Spawn workers and automatically join them to the hive-mind (combines agent/spawn + hive-mind/join) Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -212,7 +212,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_init',
-        description: 'Initialize the hive-mind collective',
+        description: 'Initialize the hive-mind collective Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -269,7 +269,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_status',
-        description: 'Get hive-mind status',
+        description: 'Get hive-mind status Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -368,7 +368,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_join',
-        description: 'Join an agent to the hive-mind',
+        description: 'Join an agent to the hive-mind Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -404,7 +404,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_leave',
-        description: 'Remove an agent from the hive-mind',
+        description: 'Remove an agent from the hive-mind Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -437,7 +437,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_consensus',
-        description: 'Propose or vote on consensus with BFT, Raft, or Quorum strategies',
+        description: 'Propose or vote on consensus with BFT, Raft, or Quorum strategies Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -723,7 +723,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_broadcast',
-        description: 'Broadcast message to all workers',
+        description: 'Broadcast message to all workers Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -773,7 +773,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_shutdown',
-        description: 'Shutdown the hive-mind and terminate all workers',
+        description: 'Shutdown the hive-mind and terminate all workers Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -831,7 +831,7 @@ export const hiveMindTools = [
     },
     {
         name: 'hive-mind_memory',
-        description: 'Access hive shared memory',
+        description: 'Access hive shared memory Use when native Task is wrong because you need queen-led collective intelligence — Byzantine-FT consensus, broadcast across many worker agents, shared memory with bounded conflict. For a single subagent, native Task is fine. Pair with swarm_init first to set topology.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -571,7 +571,7 @@ function assessCommandRisk(command) {
 // MCP Tool implementations - return raw data for direct CLI use
 export const hooksPreEdit = {
     name: 'hooks_pre-edit',
-    description: 'Get context and agent suggestions before editing a file',
+    description: 'Get context and agent suggestions before editing a file Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -613,7 +613,7 @@ export const hooksPreEdit = {
 };
 export const hooksPostEdit = {
     name: 'hooks_post-edit',
-    description: 'Record editing outcome for learning',
+    description: 'Record editing outcome for learning Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -667,7 +667,7 @@ export const hooksPostEdit = {
 };
 export const hooksPreCommand = {
     name: 'hooks_pre-command',
-    description: 'Assess risk before executing a command',
+    description: 'Assess risk before executing a command Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -705,7 +705,7 @@ export const hooksPreCommand = {
 };
 export const hooksPostCommand = {
     name: 'hooks_post-command',
-    description: 'Record command execution outcome',
+    description: 'Record command execution outcome Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -761,7 +761,7 @@ export const hooksPostCommand = {
 };
 export const hooksRoute = {
     name: 'hooks_route',
-    description: 'Get a 3-tier routing recommendation for a task: Tier 1 (Agent Booster, 0ms / $0 — for var-to-const, add-types, etc.), Tier 2 (Haiku — simple), Tier 3 (Sonnet/Opus — complex). Use this BEFORE spawning an agent to avoid sending simple transforms to Sonnet. Native tools have no equivalent — Claude Code does not introspect its own model-selection cost. Returns the recommended model + a `[AGENT_BOOSTER_AVAILABLE]` literal when the WASM bypass applies.',
+    description: 'Get a 3-tier routing recommendation for a task: Tier 1 (Agent Booster, 0ms / $0 — for var-to-const, add-types, etc.), Tier 2 (Haiku — simple), Tier 3 (Sonnet/Opus — complex). Use this BEFORE spawning an agent to avoid sending simple transforms to Sonnet. Native tools have no equivalent — Claude Code does not introspect its own model-selection cost. Returns the recommended model + a `[AGENT_BOOSTER_AVAILABLE]` literal when the WASM bypass applies. Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -937,7 +937,7 @@ export const hooksRoute = {
 };
 export const hooksMetrics = {
     name: 'hooks_metrics',
-    description: 'View learning metrics dashboard',
+    description: 'View learning metrics dashboard Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1002,7 +1002,7 @@ export const hooksMetrics = {
 };
 export const hooksList = {
     name: 'hooks_list',
-    description: 'List all registered hooks',
+    description: 'List all registered hooks Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -1049,7 +1049,7 @@ export const hooksList = {
 };
 export const hooksPreTask = {
     name: 'hooks_pre-task',
-    description: 'Record task start and get agent suggestions with intelligent model routing (ADR-026)',
+    description: 'Record task start and get agent suggestions with intelligent model routing (ADR-026) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1147,7 +1147,7 @@ export const hooksPreTask = {
 };
 export const hooksPostTask = {
     name: 'hooks_post-task',
-    description: 'Record task completion for learning',
+    description: 'Record task completion for learning Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1299,7 +1299,7 @@ export const hooksPostTask = {
 // Explain hook - transparent routing explanation
 export const hooksExplain = {
     name: 'hooks_explain',
-    description: 'Explain routing decision with full transparency',
+    description: 'Explain routing decision with full transparency Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1377,7 +1377,7 @@ export const hooksExplain = {
 // Pretrain hook - repository analysis for intelligence bootstrap
 export const hooksPretrain = {
     name: 'hooks_pretrain',
-    description: 'Analyze repository to bootstrap intelligence (4-step pipeline)',
+    description: 'Analyze repository to bootstrap intelligence (4-step pipeline) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1492,7 +1492,7 @@ export const hooksPretrain = {
 // Build agents hook - generate optimized agent configs
 export const hooksBuildAgents = {
     name: 'hooks_build-agents',
-    description: 'Generate optimized agent configurations from pretrain data',
+    description: 'Generate optimized agent configurations from pretrain data Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1555,7 +1555,7 @@ export const hooksBuildAgents = {
 // Transfer hook - transfer patterns from another project
 export const hooksTransfer = {
     name: 'hooks_transfer',
-    description: 'Transfer learned patterns from another project',
+    description: 'Transfer learned patterns from another project Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1637,7 +1637,7 @@ export const hooksTransfer = {
 // Session start hook - auto-starts daemon
 export const hooksSessionStart = {
     name: 'hooks_session-start',
-    description: 'Initialize a new session and auto-start daemon',
+    description: 'Initialize a new session and auto-start daemon Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1780,7 +1780,7 @@ export const hooksSessionStart = {
 // Session end hook - stops daemon
 export const hooksSessionEnd = {
     name: 'hooks_session-end',
-    description: 'End current session, stop daemon, and persist state',
+    description: 'End current session, stop daemon, and persist state Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1867,7 +1867,7 @@ export const hooksSessionEnd = {
 // Session restore hook
 export const hooksSessionRestore = {
     name: 'hooks_session-restore',
-    description: 'Restore a previous session',
+    description: 'Restore a previous session Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1909,7 +1909,7 @@ export const hooksSessionRestore = {
 // Notify hook - cross-agent notifications
 export const hooksNotify = {
     name: 'hooks_notify',
-    description: 'Send cross-agent notification',
+    description: 'Send cross-agent notification Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1948,7 +1948,7 @@ export const hooksNotify = {
 // Init hook - initialize hooks in project
 export const hooksInit = {
     name: 'hooks_init',
-    description: 'Initialize hooks in project with .claude/settings.json',
+    description: 'Initialize hooks in project with .claude/settings.json Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1986,7 +1986,7 @@ export const hooksInit = {
 // Intelligence hook - RuVector intelligence system
 export const hooksIntelligence = {
     name: 'hooks_intelligence',
-    description: 'RuVector intelligence system status (shows REAL metrics from memory store)',
+    description: 'RuVector intelligence system status (shows REAL metrics from memory store) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2127,7 +2127,7 @@ export const hooksIntelligence = {
 // Intelligence reset hook
 export const hooksIntelligenceReset = {
     name: 'hooks_intelligence-reset',
-    description: 'Reset intelligence learning state',
+    description: 'Reset intelligence learning state Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -2194,7 +2194,7 @@ export const hooksIntelligenceReset = {
 // Intelligence trajectory hooks - REAL implementation using activeTrajectories
 export const hooksTrajectoryStart = {
     name: 'hooks_intelligence_trajectory-start',
-    description: 'Begin SONA trajectory for reinforcement learning',
+    description: 'Begin SONA trajectory for reinforcement learning Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2255,7 +2255,7 @@ export const hooksTrajectoryStart = {
 };
 export const hooksTrajectoryStep = {
     name: 'hooks_intelligence_trajectory-step',
-    description: 'Record step in trajectory for reinforcement learning',
+    description: 'Record step in trajectory for reinforcement learning Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2308,7 +2308,7 @@ export const hooksTrajectoryStep = {
 };
 export const hooksTrajectoryEnd = {
     name: 'hooks_intelligence_trajectory-end',
-    description: 'End trajectory and trigger SONA learning with EWC++',
+    description: 'End trajectory and trigger SONA learning with EWC++ Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2452,7 +2452,7 @@ export const hooksTrajectoryEnd = {
 // Pattern store/search hooks - REAL implementation using storeEntry
 export const hooksPatternStore = {
     name: 'hooks_intelligence_pattern-store',
-    description: 'Store pattern in ReasoningBank (HNSW-indexed)',
+    description: 'Store pattern in ReasoningBank (HNSW-indexed) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2534,7 +2534,7 @@ export const hooksPatternStore = {
 };
 export const hooksPatternSearch = {
     name: 'hooks_intelligence_pattern-search',
-    description: 'Search patterns using REAL vector search (HNSW when available, brute-force fallback)',
+    description: 'Search patterns using REAL vector search (HNSW when available, brute-force fallback) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2643,7 +2643,7 @@ export const hooksPatternSearch = {
 // Intelligence stats hook
 export const hooksIntelligenceStats = {
     name: 'hooks_intelligence_stats',
-    description: 'Get RuVector intelligence layer statistics',
+    description: 'Get RuVector intelligence layer statistics Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2846,7 +2846,7 @@ export const hooksIntelligenceStats = {
 // Intelligence learn hook
 export const hooksIntelligenceLearn = {
     name: 'hooks_intelligence_learn',
-    description: 'Force immediate SONA learning cycle with EWC++ consolidation',
+    description: 'Force immediate SONA learning cycle with EWC++ consolidation Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -2917,7 +2917,7 @@ export const hooksIntelligenceLearn = {
 // Intelligence attention hook
 export const hooksIntelligenceAttention = {
     name: 'hooks_intelligence_attention',
-    description: 'Compute attention-weighted similarity using MoE/Flash/Hyperbolic',
+    description: 'Compute attention-weighted similarity using MoE/Flash/Hyperbolic Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3329,7 +3329,7 @@ function detectWorkerTriggers(text) {
 // Worker list tool
 export const hooksWorkerList = {
     name: 'hooks_worker-list',
-    description: 'List all 12 background workers with status and capabilities',
+    description: 'List all 12 background workers with status and capabilities Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3372,7 +3372,7 @@ export const hooksWorkerList = {
 // Worker dispatch tool
 export const hooksWorkerDispatch = {
     name: 'hooks_worker-dispatch',
-    description: 'Dispatch a background worker for analysis/optimization tasks',
+    description: 'Dispatch a background worker for analysis/optimization tasks Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3506,7 +3506,7 @@ export const hooksWorkerDispatch = {
 // Worker status tool
 export const hooksWorkerStatus = {
     name: 'hooks_worker-status',
-    description: 'Get status of a specific worker or all active workers',
+    description: 'Get status of a specific worker or all active workers Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3563,7 +3563,7 @@ export const hooksWorkerStatus = {
 // Worker detect tool - detect triggers from prompt
 export const hooksWorkerDetect = {
     name: 'hooks_worker-detect',
-    description: 'Detect worker triggers from user prompt (for UserPromptSubmit hook)',
+    description: 'Detect worker triggers from user prompt (for UserPromptSubmit hook) Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3642,7 +3642,7 @@ async function getModelRouterInstance() {
 // Model route tool - intelligent model selection
 export const hooksModelRoute = {
     name: 'hooks_model-route',
-    description: 'Route task to optimal Claude model (haiku/sonnet/opus) based on complexity',
+    description: 'Route task to optimal Claude model (haiku/sonnet/opus) based on complexity Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3688,7 +3688,7 @@ export const hooksModelRoute = {
 // Model route outcome - record outcome for learning
 export const hooksModelOutcome = {
     name: 'hooks_model-outcome',
-    description: 'Record model routing outcome for learning',
+    description: 'Record model routing outcome for learning Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -3723,7 +3723,7 @@ export const hooksModelOutcome = {
 // Model router stats
 export const hooksModelStats = {
     name: 'hooks_model-stats',
-    description: 'Get model routing statistics',
+    description: 'Get model routing statistics Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -3760,7 +3760,7 @@ function analyzeComplexityFallback(task) {
 // Worker cancel tool
 export const hooksWorkerCancel = {
     name: 'hooks_worker-cancel',
-    description: 'Cancel a running worker',
+    description: 'Cancel a running worker Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because you need Ruflo-side state — pattern persistence, neural training signals, model-routing learning, cost tracking, audit chain. For one-off shell commands, plain Bash hooks are fine.',
     inputSchema: {
         type: 'object',
         properties: {