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

package/.claude/scheduled_tasks.lock

@@ -1 +1 @@
-{"sessionId":"47380e10-1915-412b-80f1-c03ac7d0ea24","pid":59856,"acquiredAt":1778091867601}
+{"sessionId":"fd9b0530-a395-4da0-9b21-a26731cef01f","pid":91923,"procStart":"Mon May 11 02:12:51 2026","acquiredAt":1778466450635}

package/README.md

@@ -263,6 +263,8 @@ The difference: some channels are trusted, some aren't. [`@claude-flow/plugin-ag
 
 You don't configure handshakes or manage certificates. You `federation init`, `federation join`, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.
 
+> **📘 Full user guide:** [`docs/federation/`](./docs/federation/) — setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at [`docs/federation/phase7-mesh-bringup.md`](./docs/federation/phase7-mesh-bringup.md).
+
 <details>
 <summary><strong>Federation capabilities</strong></summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.21",
+  "version": "3.7.0-alpha.23",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/README.md

@@ -263,6 +263,8 @@ The difference: some channels are trusted, some aren't. [`@claude-flow/plugin-ag
 
 You don't configure handshakes or manage certificates. You `federation init`, `federation join`, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.
 
+> **📘 Full user guide:** [`docs/federation/`](./docs/federation/) — setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at [`docs/federation/phase7-mesh-bringup.md`](./docs/federation/phase7-mesh-bringup.md).
+
 <details>
 <summary><strong>Federation capabilities</strong></summary>
 

package/v3/@claude-flow/cli/dist/src/commands/task.js

@@ -179,7 +179,7 @@ const createCommand = {
                     { property: 'Priority', value: formatPriority(result.priority) },
                     { property: 'Status', value: formatStatus(result.status) },
                     { property: 'Assigned To', value: result.assignedTo?.join(', ') || 'Unassigned' },
-                    { property: 'Tags', value: result.tags.join(', ') || 'None' },
+                    { property: 'Tags', value: result.tags?.join(', ') || 'None' }, // #1863 — guard undefined array
                     { property: 'Created', value: new Date(result.createdAt).toLocaleString() }
                 ]
             });
@@ -360,11 +360,15 @@ const statusCommand = {
                     { key: 'value', header: 'Value', width: 40 }
                 ],
                 data: [
+                    // #1863 — tasks created via task_create or loaded from an older
+                    // store schema may not have these arrays populated; guard each
+                    // `.join()` so `task status` never throws "Cannot read properties
+                    // of undefined (reading 'join')".
                     { property: 'Assigned To', value: result.assignedTo?.join(', ') || 'Unassigned' },
                     { property: 'Parent Task', value: result.parentId || 'None' },
-                    { property: 'Dependencies', value: result.dependencies.join(', ') || 'None' },
-                    { property: 'Dependents', value: result.dependents.join(', ') || 'None' },
-                    { property: 'Tags', value: result.tags.join(', ') || 'None' }
+                    { property: 'Dependencies', value: result.dependencies?.join(', ') || 'None' },
+                    { property: 'Dependents', value: result.dependents?.join(', ') || 'None' },
+                    { property: 'Tags', value: result.tags?.join(', ') || 'None' }
                 ]
             });
             // Timeline

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

@@ -228,7 +228,7 @@ export const agentTools = [
         // updating the agent record with lastResult / taskCount / status.
         // No mock — actual HTTP request to api.anthropic.com.
         name: 'agent_execute',
-        description: 'Execute a task on a spawned agent — calls the Anthropic Messages API with the agent\'s configured model. Requires ANTHROPIC_API_KEY in env.',
+        description: 'Run a task on a previously-spawned agent_spawn record via the Anthropic Messages API with that agent\'s configured model. Use when native Task tool is wrong because (a) you need the spawned agent\'s persistent config (model, instructions, cost-tracking attribution) to apply to this turn, (b) the result needs to feed back into the agent\'s lifecycle (taskCount, lastResult, swarm-coordinated state), or (c) you want explicit model routing via the spawn record\'s `model` field instead of inheriting. For one-shot Claude prompts without a tracked agent, native Task is fine. Requires ANTHROPIC_API_KEY in env.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -261,7 +261,7 @@ export const agentTools = [
     },
     {
         name: 'agent_terminate',
-        description: 'Terminate an agent',
+        description: 'Remove a Ruflo-tracked agent from the registry and free its swarm slot. Use when you need to (a) clean up a spawned agent so its cost-tracking row finalizes, (b) reclaim a swarm-topology slot for another agent, or (c) end a stuck agent without restarting the whole swarm. For one-shot Task tool invocations that already self-terminate, this tool is not needed. Pair with agent_list first to confirm the agentId.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -296,7 +296,7 @@ export const agentTools = [
     },
     {
         name: 'agent_status',
-        description: 'Get agent status',
+        description: 'Read the lifecycle state of a single tracked agent: idle/running/stopped, current taskCount, lastResult, model, health score. Use when native Task tool is wrong because you need agent-level state (status across turns, accumulated taskCount, last error, swarm coordination) rather than a one-shot response. For inspecting a Task you just ran, native Task output is fine. Pair with agent_list to find the agentId first.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -333,7 +333,7 @@ export const agentTools = [
     },
     {
         name: 'agent_list',
-        description: 'List all agents',
+        description: 'List every Ruflo-tracked agent in the registry with its type, model, status, and taskCount. Use when native Task tool is wrong because you need to see the swarm-wide agent inventory across turns (which agents exist, their roles, their cost-tracking handles) rather than spawn a new one-shot Task. Filter by status/domain/agentType if needed. For starting a fresh single-shot subagent, native Task is fine.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -388,7 +388,7 @@ export const agentTools = [
     },
     {
         name: 'agent_pool',
-        description: 'Manage agent pool',
+        description: 'Manage a fixed-size warm pool of pre-spawned agents to skip cold-start cost on bursty workloads. Use when native Task is wrong because (a) you have a queue of similar tasks and want to amortize spawn latency, (b) cost-tracking wants stable agentIds across requests, or (c) swarm topology requires a known agent count at all times. For one-shot work, just call agent_spawn or native Task. Pool sizes and warm/idle thresholds are set per-pool.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -505,7 +505,7 @@ export const agentTools = [
     },
     {
         name: 'agent_health',
-        description: 'Check agent health',
+        description: 'Compute an agent\'s rolling health score (0-1) from recent task success ratio + response-latency p50/p95 + error rate. Use when native Task tool is wrong because you\'re running a long-lived agent (autonomous loop / hive-mind worker / federation peer) and need to detect degradation before the breaker trips it. For one-shot Task invocations there is no history to score. Pair with hooks_post-task so the scores stay current.',
         category: 'agent',
         inputSchema: {
             type: 'object',
@@ -580,7 +580,7 @@ export const agentTools = [
     },
     {
         name: 'agent_update',
-        description: 'Update agent status or config',
+        description: 'Mutate a tracked agent\'s config (model, instructions, status, health) without re-spawning. Use when native Task tool is wrong because the agent already has accumulated state (taskCount, swarm membership, cost-tracking attribution) and you only need to tweak one field — for example, promoting an idle agent to running on a new task, or rotating its model from haiku to sonnet mid-loop. For a brand-new subagent, agent_spawn (or native Task) is the right call.',
         category: 'agent',
         inputSchema: {
             type: 'object',

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

@@ -51,7 +51,7 @@ async function getBridge() {
 // ===== agentdb_health — Controller health check =====
 export const agentdbHealth = {
     name: 'agentdb_health',
-    description: 'Get AgentDB v3 controller health status including cache stats and attestation count',
+    description: 'Get AgentDB v3 controller health status including cache stats and attestation count Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -72,7 +72,7 @@ export const agentdbHealth = {
 // ===== agentdb_controllers — List all controllers =====
 export const agentdbControllers = {
     name: 'agentdb_controllers',
-    description: 'List all AgentDB v3 controllers and their initialization status',
+    description: 'List all AgentDB v3 controllers and their initialization status Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -98,7 +98,7 @@ export const agentdbControllers = {
 // ===== agentdb_pattern_store — Store via ReasoningBank =====
 export const agentdbPatternStore = {
     name: 'agentdb_pattern-store',
-    description: 'Store a pattern directly via ReasoningBank controller',
+    description: 'Store a pattern directly via ReasoningBank controller Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -167,7 +167,7 @@ export const agentdbPatternStore = {
 // ===== agentdb_pattern_search — Search via ReasoningBank =====
 export const agentdbPatternSearch = {
     name: 'agentdb_pattern-search',
-    description: 'Search patterns via ReasoningBank controller with BM25+semantic hybrid',
+    description: 'Search patterns via ReasoningBank controller with BM25+semantic hybrid Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -185,13 +185,90 @@ export const agentdbPatternSearch = {
             const query = validateString(params.query, 'query', 10_000);
             if (!query)
                 return { results: [], error: 'query is required (non-empty string, max 10KB)' };
+            const topK = validatePositiveInt(params.topK, 5, MAX_TOP_K);
+            const minConfidence = validateScore(params.minConfidence, 0.3);
             const bridge = await getBridge();
-            const result = await bridge.bridgeSearchPatterns({
-                query,
-                topK: validatePositiveInt(params.topK, 5, MAX_TOP_K),
-                minConfidence: validateScore(params.minConfidence, 0.3),
-            });
-            return result ?? { results: [], controller: 'unavailable' };
+            const result = await bridge.bridgeSearchPatterns({ query, topK, minConfidence });
+            if (result && Array.isArray(result.results) && result.results.length > 0) {
+                return result;
+            }
+            // #1889 — symmetric fallback. pattern-store writes to the `pattern`
+            // namespace via memory_store when ReasoningBank is unavailable; the
+            // search path used to return an empty list with `controller: 'unavailable'`
+            // even though the user's pattern was sitting in that namespace. We now
+            // tier the fallback so freshly-written entries are findable before HNSW
+            // catches up:
+            //   1. Try semantic search via searchEntries (HNSW-backed)
+            //   2. If that returns 0, list the namespace and substring-match the query
+            //      against each entry's pattern text. Deterministic; survives
+            //      embedding-index latency and threshold tuning.
+            try {
+                const { searchEntries, listEntries } = await import('../memory/memory-initializer.js');
+                const parseEntry = (e) => {
+                    const raw = typeof e.content === 'string' ? e.content : e.value;
+                    if (typeof raw !== 'string')
+                        return null;
+                    try {
+                        const parsed = JSON.parse(raw);
+                        const confidence = typeof parsed.confidence === 'number' ? parsed.confidence : 0.8;
+                        if (confidence < minConfidence)
+                            return null;
+                        return {
+                            patternId: e.key ?? e.id,
+                            pattern: parsed.pattern,
+                            type: parsed.type ?? 'general',
+                            confidence,
+                            score: typeof e.score === 'number' ? e.score : undefined,
+                        };
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                // Tier 1 — semantic
+                let results = [];
+                let tier = 'semantic';
+                try {
+                    const semantic = await searchEntries({ query, namespace: 'pattern', limit: topK });
+                    results = (semantic?.results ?? [])
+                        .map(parseEntry)
+                        .filter((r) => r !== null);
+                }
+                catch { /* fall through to tier 2 */ }
+                // Tier 2 — substring scan (catches just-written entries before HNSW indexes them)
+                if (results.length === 0) {
+                    tier = 'substring';
+                    const all = await listEntries({ namespace: 'pattern', limit: 200 });
+                    const qLower = query.toLowerCase();
+                    const matched = [];
+                    for (const e of (all?.entries ?? [])) {
+                        const parsed = parseEntry(e);
+                        if (!parsed)
+                            continue;
+                        const text = typeof parsed.pattern === 'string' ? parsed.pattern.toLowerCase() : '';
+                        if (text.includes(qLower))
+                            matched.push(parsed);
+                        if (matched.length >= topK)
+                            break;
+                    }
+                    results = matched;
+                }
+                // #1889 — controller label must match pattern-store's so the smoke
+                // round-trip sees both ends agree. The store reports
+                // `memory-store-fallback`; we use the same name + a `tier` field
+                // to expose which sub-strategy fired.
+                return {
+                    results,
+                    controller: 'memory-store-fallback',
+                    tier,
+                    note: result
+                        ? `ReasoningBank returned 0 results; tier=${tier} from pattern namespace.`
+                        : `ReasoningBank controller unavailable; tier=${tier} from pattern namespace.`,
+                };
+            }
+            catch (fallbackErr) {
+                return { results: [], controller: 'unavailable', fallbackError: sanitizeError(fallbackErr) };
+            }
         }
         catch (error) {
             return { results: [], error: sanitizeError(error) };
@@ -201,7 +278,7 @@ export const agentdbPatternSearch = {
 // ===== agentdb_feedback — Record task feedback =====
 export const agentdbFeedback = {
     name: 'agentdb_feedback',
-    description: 'Record task feedback for learning via LearningSystem + ReasoningBank controllers',
+    description: 'Record task feedback for learning via LearningSystem + ReasoningBank controllers Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -242,7 +319,7 @@ export const agentdbFeedback = {
 // ===== agentdb_causal_edge — Record causal relationships =====
 export const agentdbCausalEdge = {
     name: 'agentdb_causal-edge',
-    description: 'Record a causal edge between two memory entries via CausalMemoryGraph',
+    description: 'Record a causal edge between two memory entries via CausalMemoryGraph Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -304,7 +381,7 @@ export const agentdbCausalEdge = {
 // ===== agentdb_route — Route via SemanticRouter =====
 export const agentdbRoute = {
     name: 'agentdb_route',
-    description: 'Route a task via AgentDB SemanticRouter or LearningSystem recommendAlgorithm',
+    description: 'Route a task via AgentDB SemanticRouter or LearningSystem recommendAlgorithm Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -341,7 +418,7 @@ export const agentdbRoute = {
 // ===== agentdb_session_start — Session with ReflexionMemory =====
 export const agentdbSessionStart = {
     name: 'agentdb_session-start',
-    description: 'Start a session with ReflexionMemory episodic replay',
+    description: 'Start a session with ReflexionMemory episodic replay Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -378,7 +455,7 @@ export const agentdbSessionStart = {
 // ===== agentdb_session_end — End session + NightlyLearner =====
 export const agentdbSessionEnd = {
     name: 'agentdb_session-end',
-    description: 'End session, persist to ReflexionMemory, trigger NightlyLearner consolidation',
+    description: 'End session, persist to ReflexionMemory, trigger NightlyLearner consolidation Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -417,7 +494,7 @@ export const agentdbSessionEnd = {
 // ===== agentdb_hierarchical_store — Store to hierarchical memory =====
 export const agentdbHierarchicalStore = {
     name: 'agentdb_hierarchical-store',
-    description: 'Store to hierarchical memory with tier (working, episodic, semantic)',
+    description: 'Store to hierarchical memory with tier (working, episodic, semantic) Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -467,7 +544,7 @@ export const agentdbHierarchicalStore = {
 // ===== agentdb_hierarchical_recall — Recall from hierarchical memory =====
 export const agentdbHierarchicalRecall = {
     name: 'agentdb_hierarchical-recall',
-    description: 'Recall from hierarchical memory with optional tier filter',
+    description: 'Recall from hierarchical memory with optional tier filter Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -510,7 +587,7 @@ export const agentdbHierarchicalRecall = {
 // ===== agentdb_consolidate — Run memory consolidation =====
 export const agentdbConsolidate = {
     name: 'agentdb_consolidate',
-    description: 'Run memory consolidation to promote entries across tiers and compress old data',
+    description: 'Run memory consolidation to promote entries across tiers and compress old data Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -535,7 +612,7 @@ export const agentdbConsolidate = {
 // ===== agentdb_batch — Batch operations (insert, update, delete) =====
 export const agentdbBatch = {
     name: 'agentdb_batch',
-    description: 'Batch operations on AgentDB episodes (insert, update, delete). Note: entries are stored in the AgentDB episodes table, not the memory_search namespace. Use memory_store for entries that should be searchable via memory_search.',
+    description: 'Batch operations on AgentDB episodes (insert, update, delete). Note: entries are stored in the AgentDB episodes table, not the memory_search namespace. Use memory_store for entries that should be searchable via memory_search. Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -604,7 +681,7 @@ export const agentdbBatch = {
 // ===== agentdb_context_synthesize — Synthesize context from memories =====
 export const agentdbContextSynthesize = {
     name: 'agentdb_context-synthesize',
-    description: 'Synthesize context from stored memories for a given query',
+    description: 'Synthesize context from stored memories for a given query Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -636,7 +713,7 @@ export const agentdbContextSynthesize = {
 // ===== agentdb_semantic_route — Route via SemanticRouter =====
 export const agentdbSemanticRoute = {
     name: 'agentdb_semantic-route',
-    description: 'Route an input via AgentDB SemanticRouter for intent classification',
+    description: 'Route an input via AgentDB SemanticRouter for intent classification Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -664,7 +741,7 @@ export const agentdbSemanticRoute = {
 // ===== #1784: Delete tools — symmetry for hierarchical-store + causal-edge =====
 export const agentdbHierarchicalDelete = {
     name: 'agentdb_hierarchical-delete',
-    description: 'Delete a hierarchical-memory entry by key. Returns controller="native-unsupported" when the entry is in a backend without a public delete API.',
+    description: 'Delete a hierarchical-memory entry by key. Returns controller="native-unsupported" when the entry is in a backend without a public delete API. Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -705,7 +782,7 @@ export const agentdbHierarchicalDelete = {
 };
 export const agentdbCausalEdgeDelete = {
     name: 'agentdb_causal-edge-delete',
-    description: 'Delete a causal edge between two memory entries. Returns controller="native-unsupported" when the edge lives in graph-node native storage (no public delete API).',
+    description: 'Delete a causal edge between two memory entries. Returns controller="native-unsupported" when the edge lives in graph-node native storage (no public delete API). Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -741,7 +818,7 @@ export const agentdbCausalEdgeDelete = {
 };
 export const agentdbCausalNodeDelete = {
     name: 'agentdb_causal-node-delete',
-    description: 'Cascade-delete a causal node and all its incident edges from the SQL fallback. Native graph-node entries are unaffected (no delete API in the binding).',
+    description: 'Cascade-delete a causal node and all its incident edges from the SQL fallback. Native graph-node entries are unaffected (no delete API in the binding). Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {

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

@@ -10,7 +10,7 @@ import { analyzeDiff, assessFileRisk, assessOverallRisk, classifyDiff, suggestRe
  */
 export const analyzeDiffTool = {
     name: 'analyze_diff',
-    description: 'Analyze git diff for change risk assessment and classification',
+    description: 'Analyze git diff for change risk assessment and classification Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['diff', 'risk', 'classification', 'git'],
     inputSchema: {
@@ -85,7 +85,7 @@ export const analyzeDiffTool = {
  */
 export const diffRiskTool = {
     name: 'analyze_diff-risk',
-    description: 'Quick risk assessment for git diff',
+    description: 'Quick risk assessment for git diff Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['diff', 'risk', 'git'],
     inputSchema: {
@@ -130,7 +130,7 @@ export const diffRiskTool = {
  */
 export const diffClassifyTool = {
     name: 'analyze_diff-classify',
-    description: 'Classify git diff change type',
+    description: 'Classify git diff change type Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['diff', 'classification', 'git'],
     inputSchema: {
@@ -174,7 +174,7 @@ export const diffClassifyTool = {
  */
 export const diffReviewersTool = {
     name: 'analyze_diff-reviewers',
-    description: 'Suggest reviewers for git diff changes',
+    description: 'Suggest reviewers for git diff changes Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['diff', 'reviewers', 'git'],
     inputSchema: {
@@ -225,7 +225,7 @@ export const diffReviewersTool = {
  */
 export const fileRiskTool = {
     name: 'analyze_file-risk',
-    description: 'Assess risk for a specific file change',
+    description: 'Assess risk for a specific file change Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['file', 'risk'],
     inputSchema: {
@@ -280,7 +280,7 @@ export const fileRiskTool = {
  */
 export const diffStatsTool = {
     name: 'analyze_diff-stats',
-    description: 'Get quick statistics for git diff',
+    description: 'Get quick statistics for git diff Use when native `git diff` / `grep` / static analysis is wrong because you want LLM-graded change classification, reviewer recommendations, or risk scoring. For literal-text inspection, native tools are fine.',
     category: 'analyze',
     tags: ['diff', 'stats', 'git'],
     inputSchema: {

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

@@ -15,7 +15,7 @@ function ok(data) {
 // ── MCP Tool Definitions ──────────────────────────────────────
 const autopilotStatus = {
     name: 'autopilot_status',
-    description: 'Get autopilot state including enabled status, iteration count, task progress, and learning metrics.',
+    description: 'Get autopilot state including enabled status, iteration count, task progress, and learning metrics. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -36,7 +36,7 @@ const autopilotStatus = {
 };
 const autopilotEnable = {
     name: 'autopilot_enable',
-    description: 'Enable autopilot persistent completion. Agents will be re-engaged when tasks remain incomplete.',
+    description: 'Enable autopilot persistent completion. Agents will be re-engaged when tasks remain incomplete. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -51,7 +51,7 @@ const autopilotEnable = {
 };
 const autopilotDisable = {
     name: 'autopilot_disable',
-    description: 'Disable autopilot. Agents will be allowed to stop even if tasks remain.',
+    description: 'Disable autopilot. Agents will be allowed to stop even if tasks remain. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -64,7 +64,7 @@ const autopilotDisable = {
 };
 const autopilotConfig = {
     name: 'autopilot_config',
-    description: 'Configure autopilot limits: max iterations (1-1000), timeout in minutes (1-1440), and task sources.',
+    description: 'Configure autopilot limits: max iterations (1-1000), timeout in minutes (1-1440), and task sources. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: {
         type: 'object',
@@ -91,7 +91,7 @@ const autopilotConfig = {
 };
 const autopilotReset = {
     name: 'autopilot_reset',
-    description: 'Reset autopilot iteration counter and restart the timer.',
+    description: 'Reset autopilot iteration counter and restart the timer. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -107,7 +107,7 @@ const autopilotReset = {
 };
 const autopilotLog = {
     name: 'autopilot_log',
-    description: 'Retrieve the autopilot event log. Shows enable/disable events, re-engagements, completions.',
+    description: 'Retrieve the autopilot event log. Shows enable/disable events, re-engagements, completions. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: {
         type: 'object',
@@ -123,7 +123,7 @@ const autopilotLog = {
 };
 const autopilotProgress = {
     name: 'autopilot_progress',
-    description: 'Detailed task progress broken down by source (team-tasks, swarm-tasks, file-checklist).',
+    description: 'Detailed task progress broken down by source (team-tasks, swarm-tasks, file-checklist). Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -148,7 +148,7 @@ const autopilotProgress = {
 };
 const autopilotLearn = {
     name: 'autopilot_learn',
-    description: 'Discover success patterns from past task completions. Requires AgentDB for full functionality.',
+    description: 'Discover success patterns from past task completions. Requires AgentDB for full functionality. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -165,7 +165,7 @@ const autopilotLearn = {
 };
 const autopilotHistory = {
     name: 'autopilot_history',
-    description: 'Search past completion episodes by keyword. Requires AgentDB.',
+    description: 'Search past completion episodes by keyword. Requires AgentDB. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: {
         type: 'object',
@@ -191,7 +191,7 @@ const autopilotHistory = {
 };
 const autopilotPredict = {
     name: 'autopilot_predict',
-    description: 'Predict the optimal next action based on current state and learned patterns.',
+    description: 'Predict the optimal next action based on current state and learned patterns. Use when running long-horizon goals that should resume automatically across sessions — Claude Code has no native autonomous-loop scheduler. Pair with autopilot_enable + a goal description, then let cron fires advance the work. For interactive single-task sessions, native Task is fine.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {

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

@@ -68,7 +68,7 @@ export const browserSessionTools = [
     // ==========================================================================
     {
         name: 'browser_session_record',
-        description: 'Open a named, traced browser session: allocate an RVF cognitive container, begin a ruvector trajectory, then open the URL via agent-browser. Returns the session id and rvf path.',
+        description: 'Open a named, traced browser session: allocate an RVF cognitive container, begin a ruvector trajectory, then open the URL via agent-browser. Returns the session id and rvf path. Use when native WebFetch is wrong because you need real browser automation — JS-heavy SPA scraping, login flows with cookie reuse, replay against DOM-drifted versions, AIDefence PII gating before content reaches Claude. For static HTML pages, native WebFetch is faster and free.',
         category: 'browser-session',
         tags: ['session', 'rvf', 'trajectory', 'lifecycle'],
         inputSchema: {
@@ -134,7 +134,7 @@ export const browserSessionTools = [
     // ==========================================================================
     {
         name: 'browser_session_end',
-        description: 'End a recorded browser session: trajectory-end with verdict, rvf compact, AIDefence pre-store gate (best-effort), and AgentDB index in the browser-sessions namespace.',
+        description: 'End a recorded browser session: trajectory-end with verdict, rvf compact, AIDefence pre-store gate (best-effort), and AgentDB index in the browser-sessions namespace. Use when native WebFetch is wrong because you need real browser automation — JS-heavy SPA scraping, login flows with cookie reuse, replay against DOM-drifted versions, AIDefence PII gating before content reaches Claude. For static HTML pages, native WebFetch is faster and free.',
         category: 'browser-session',
         tags: ['session', 'rvf', 'trajectory', 'lifecycle', 'agentdb'],
         inputSchema: {
@@ -195,7 +195,7 @@ export const browserSessionTools = [
     // ==========================================================================
     {
         name: 'browser_session_replay',
-        description: 'Load a recorded session trajectory and return its steps so the caller can dispatch them through the 23 browser_* tools. Does NOT itself drive the browser — replay execution is caller-orchestrated to keep this tool a primitive (ADR-0001 §7).',
+        description: 'Load a recorded session trajectory and return its steps so the caller can dispatch them through the 23 browser_* tools. Does NOT itself drive the browser — replay execution is caller-orchestrated to keep this tool a primitive (ADR-0001 §7). Use when native WebFetch is wrong because you need real browser automation — JS-heavy SPA scraping, login flows with cookie reuse, replay against DOM-drifted versions, AIDefence PII gating before content reaches Claude. For static HTML pages, native WebFetch is faster and free.',
         category: 'browser-session',
         tags: ['session', 'replay', 'trajectory', 'lifecycle'],
         inputSchema: {
@@ -249,7 +249,7 @@ export const browserSessionTools = [
     // ==========================================================================
     {
         name: 'browser_template_apply',
-        description: 'Fetch a recipe from the browser-templates AgentDB namespace and return it for caller-level execution.',
+        description: 'Fetch a recipe from the browser-templates AgentDB namespace and return it for caller-level execution. Use when native WebFetch is wrong because you need real browser automation — JS-heavy SPA scraping, login flows with cookie reuse, replay against DOM-drifted versions, AIDefence PII gating before content reaches Claude. For static HTML pages, native WebFetch is faster and free.',
         category: 'browser-session',
         tags: ['template', 'agentdb', 'extract'],
         inputSchema: {
@@ -280,7 +280,7 @@ export const browserSessionTools = [
     // ==========================================================================
     {
         name: 'browser_cookie_use',
-        description: 'Fetch a vault handle for a host from the browser-cookies AgentDB namespace. Raw cookie values are NEVER returned — only the opaque handle plus expiry / AIDefence verdict.',
+        description: 'Fetch a vault handle for a host from the browser-cookies AgentDB namespace. Raw cookie values are NEVER returned — only the opaque handle plus expiry / AIDefence verdict. Use when native WebFetch is wrong because you need real browser automation — JS-heavy SPA scraping, login flows with cookie reuse, replay against DOM-drifted versions, AIDefence PII gating before content reaches Claude. For static HTML pages, native WebFetch is faster and free.',
         category: 'browser-session',
         tags: ['cookie', 'agentdb', 'aidefence', 'auth'],
         inputSchema: {