claude-flow 3.47.0 → 3.48.0

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

@@ -13,6 +13,7 @@ import { createBuiltinAIDefence } from '../security/builtin-aidefence.js';
 // for both validation and the traversal-depth maps below.
 const SCAN_DEPTHS = ['quick', 'standard', 'deep'];
 const SCAN_TYPES = ['code', 'deps', 'all'];
+const SCAN_OUTPUTS = ['text', 'json', 'sarif'];
 // Real type predicates, not `as` casts. Array.includes() does not narrow a
 // string to a literal union on its own, so without these the depth-map lookups
 // below need an unchecked assertion — and an unchecked assertion would let a
@@ -23,6 +24,37 @@ const SCAN_TYPES = ['code', 'deps', 'all'];
 // is being fixed for.
 const isScanDepth = (v) => SCAN_DEPTHS.includes(v);
 const isScanType = (v) => SCAN_TYPES.includes(v);
+const isScanOutput = (v) => SCAN_OUTPUTS.includes(v);
+function scanSarif(findings) {
+    const ruleId = (type) => `RUFLO-${type.toUpperCase().replace(/[^A-Z0-9]+/g, '-')}`;
+    const level = (severity) => severity === 'critical' || severity === 'high' ? 'error' :
+        severity === 'medium' ? 'warning' : 'note';
+    const rules = [...new Map(findings.map(finding => [finding.type, {
+                id: ruleId(finding.type),
+                name: finding.type,
+                shortDescription: { text: finding.type },
+            }])).values()];
+    return {
+        version: '2.1.0',
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [{
+                tool: { driver: { name: 'Ruflo Security Scan', rules } },
+                results: findings.map(finding => {
+                    const lineMatch = /^(.*):(\d+)$/.exec(finding.location);
+                    const file = lineMatch?.[1] ?? (finding.location.startsWith('package.json:') ? 'package.json' : finding.location);
+                    return {
+                        ruleId: ruleId(finding.type),
+                        level: level(finding.severity),
+                        message: { text: finding.description },
+                        locations: [{ physicalLocation: {
+                                    artifactLocation: { uri: file.replace(/\\/g, '/') },
+                                    ...(lineMatch ? { region: { startLine: Number(lineMatch[2]) } } : {}),
+                                } }],
+                    };
+                }),
+            }],
+    };
+}
 // `full` was never a supported depth, but the CLI itself printed it — the
 // statusline insight, the announcement, the release-notes blurb, the CLAUDE.md
 // that `init` generates, and two shipped agent definitions all tell people to
@@ -62,6 +94,7 @@ const scanCommand = {
         const target = ctx.flags.target || '.';
         const requestedDepth = ctx.flags.depth || 'standard';
         const scanType = ctx.flags.type || 'all';
+        const requestedOutput = ctx.flags.output || 'text';
         const fix = ctx.flags.fix;
         // A security scanner must never silently degrade on an unrecognised enum
         // value. An unknown --depth used to fall through to the shallowest
@@ -91,6 +124,11 @@ const scanCommand = {
             output.printError(`Invalid --type '${scanType}'. Expected one of: ${SCAN_TYPES.join(', ')}.`);
             return { success: false, exitCode: 1 };
         }
+        if (!isScanOutput(requestedOutput)) {
+            output.printError(`Invalid --output '${requestedOutput}'. Expected one of: ${SCAN_OUTPUTS.join(', ')}.`);
+            return { success: false, exitCode: 1 };
+        }
+        const outputFormat = requestedOutput;
         // --target names WHAT gets scanned, and was never validated. A path that
         // does not exist (or is a file, not a directory) made every phase read
         // nothing, and the swallowed dir-read catches turned that into zero
@@ -106,11 +144,14 @@ const scanCommand = {
             output.printError(`Target is not a directory: ${resolvedTarget}`);
             return { success: false, exitCode: 1 };
         }
-        output.writeln();
-        output.writeln(output.bold('Security Scan'));
-        output.writeln(output.dim('─'.repeat(50)));
+        if (outputFormat === 'text') {
+            output.writeln();
+            output.writeln(output.bold('Security Scan'));
+            output.writeln(output.dim('─'.repeat(50)));
+        }
         const spinner = output.createSpinner({ text: `Scanning ${target}...`, spinner: 'dots' });
-        spinner.start();
+        if (outputFormat === 'text')
+            spinner.start();
         const findings = [];
         let criticalCount = 0, highCount = 0, mediumCount = 0, lowCount = 0;
         try {
@@ -151,9 +192,9 @@ const scanCommand = {
                                     else
                                         lowCount++;
                                     findings.push({
-                                        severity: sev === 'critical' ? output.error('CRITICAL') :
-                                            sev === 'high' ? output.warning('HIGH') :
-                                                sev === 'moderate' || sev === 'medium' ? output.warning('MEDIUM') : output.info('LOW'),
+                                        severity: sev === 'critical' ? 'critical' :
+                                            sev === 'high' ? 'high' :
+                                                sev === 'moderate' || sev === 'medium' ? 'medium' : 'low',
                                         type: 'Dependency CVE',
                                         location: `package.json:${pkg}`,
                                         description: title.substring(0, 35),
@@ -206,7 +247,7 @@ const scanCommand = {
                                             if (pattern.test(lines[i])) {
                                                 highCount++;
                                                 findings.push({
-                                                    severity: output.warning('HIGH'),
+                                                    severity: 'high',
                                                     type: 'Hardcoded Secret',
                                                     location: `${path.relative(target, fullPath)}:${i + 1}`,
                                                     description: type,
@@ -261,7 +302,7 @@ const scanCommand = {
                                                 else
                                                     mediumCount++;
                                                 findings.push({
-                                                    severity: severity === 'high' ? output.warning('HIGH') : output.warning('MEDIUM'),
+                                                    severity: severity === 'high' ? 'high' : 'medium',
                                                     type,
                                                     location: `${path.relative(target, fullPath)}:${i + 1}`,
                                                     description: desc,
@@ -280,35 +321,57 @@ const scanCommand = {
                 const scanDepth = CODE_SCAN_DEPTH[depth];
                 scanCodeDir(path.resolve(target), scanDepth);
             }
-            spinner.succeed('Scan complete');
+            if (outputFormat === 'text')
+                spinner.succeed('Scan complete');
             // Display results
-            output.writeln();
-            if (findings.length > 0) {
-                output.printTable({
-                    columns: [
-                        { key: 'severity', header: 'Severity', width: 12 },
-                        { key: 'type', header: 'Type', width: 18 },
-                        { key: 'location', header: 'Location', width: 25 },
-                        { key: 'description', header: 'Description', width: 35 },
-                    ],
-                    data: findings.slice(0, 20), // Show first 20
-                });
-                if (findings.length > 20) {
-                    output.writeln(output.dim(`... and ${findings.length - 20} more issues`));
+            if (outputFormat === 'text') {
+                output.writeln();
+                if (findings.length > 0) {
+                    output.printTable({
+                        columns: [
+                            { key: 'severity', header: 'Severity', width: 12 },
+                            { key: 'type', header: 'Type', width: 18 },
+                            { key: 'location', header: 'Location', width: 25 },
+                            { key: 'description', header: 'Description', width: 35 },
+                        ],
+                        data: findings.slice(0, 20).map(finding => ({
+                            ...finding,
+                            severity: finding.severity === 'critical' ? output.error('CRITICAL') :
+                                finding.severity === 'high' ? output.warning('HIGH') :
+                                    finding.severity === 'medium' ? output.warning('MEDIUM') : output.info('LOW'),
+                        })), // Show first 20
+                    });
+                    if (findings.length > 20) {
+                        output.writeln(output.dim(`... and ${findings.length - 20} more issues`));
+                    }
                 }
+                else {
+                    output.writeln(output.success('No security issues found!'));
+                }
+                output.writeln();
+                output.printBox([
+                    `Target: ${target}`,
+                    `Depth: ${depth}`,
+                    `Type: ${scanType}`,
+                    ``,
+                    `Critical: ${criticalCount}  High: ${highCount}  Medium: ${mediumCount}  Low: ${lowCount}`,
+                    `Total Issues: ${findings.length}`,
+                ].join('\n'), 'Scan Summary');
             }
-            else {
-                output.writeln(output.success('No security issues found!'));
-            }
-            output.writeln();
-            output.printBox([
-                `Target: ${target}`,
-                `Depth: ${depth}`,
-                `Type: ${scanType}`,
-                ``,
-                `Critical: ${criticalCount}  High: ${highCount}  Medium: ${mediumCount}  Low: ${lowCount}`,
-                `Total Issues: ${findings.length}`,
-            ].join('\n'), 'Scan Summary');
+            const record = {
+                timestamp: new Date().toISOString(),
+                target,
+                depth,
+                type: scanType,
+                summary: {
+                    critical: criticalCount,
+                    high: highCount,
+                    medium: mediumCount,
+                    low: lowCount,
+                    total: findings.length,
+                },
+                findings,
+            };
             // Persist the scan result so downstream consumers (the statusline's
             // getSecurityStatus in funnel/local-signals.ts, which reads
             // `.claude/security-scans/*.json`) reflect real scan state. Best-effort:
@@ -316,20 +379,6 @@ const scanCommand = {
             try {
                 const scanDirOut = path.join(path.resolve(target), '.claude', 'security-scans');
                 fs.mkdirSync(scanDirOut, { recursive: true });
-                const record = {
-                    timestamp: new Date().toISOString(),
-                    target,
-                    depth,
-                    type: scanType,
-                    summary: {
-                        critical: criticalCount,
-                        high: highCount,
-                        medium: mediumCount,
-                        low: lowCount,
-                        total: findings.length,
-                    },
-                    findings,
-                };
                 // Deterministic name keyed on scan config so repeated runs overwrite
                 // rather than accumulate stale reports.
                 const outFile = path.join(scanDirOut, `scan-${scanType}-${depth}.json`);
@@ -340,24 +389,33 @@ const scanCommand = {
             }
             // Auto-fix if requested
             if (fix && criticalCount + highCount > 0) {
-                output.writeln();
+                if (outputFormat === 'text')
+                    output.writeln();
                 const fixSpinner = output.createSpinner({ text: 'Attempting to fix vulnerabilities...', spinner: 'dots' });
-                fixSpinner.start();
+                if (outputFormat === 'text')
+                    fixSpinner.start();
                 try {
                     try {
                         execSync('npm audit fix', { cwd: path.resolve(target), encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
                     }
                     catch { /* npm audit fix may exit non-zero */ }
-                    fixSpinner.succeed('Applied available fixes (run scan again to verify)');
+                    if (outputFormat === 'text')
+                        fixSpinner.succeed('Applied available fixes (run scan again to verify)');
                 }
                 catch {
-                    fixSpinner.fail('Some fixes could not be applied automatically');
+                    if (outputFormat === 'text')
+                        fixSpinner.fail('Some fixes could not be applied automatically');
                 }
             }
+            if (outputFormat === 'json')
+                output.printJson(record);
+            else if (outputFormat === 'sarif')
+                output.printJson(scanSarif(findings));
             return { success: findings.length === 0 || (criticalCount === 0 && highCount === 0) };
         }
         catch (error) {
-            spinner.fail('Scan failed');
+            if (outputFormat === 'text')
+                spinner.fail('Scan failed');
             output.printError(`Error: ${error}`);
             return { success: false };
         }
@@ -1039,7 +1097,7 @@ const defendCommand = {
                         medium: output.info,
                         low: output.dim,
                     }[threat.severity] || output.dim;
-                    output.writeln(`  ${severityColor(`[${threat.severity.toUpperCase()}]`)} ${threat.type}`);
+                    output.writeln(`  ${severityColor.call(output, `[${threat.severity.toUpperCase()}]`)} ${threat.type}`);
                     output.writeln(`    ${output.dim(threat.description)}`);
                     output.writeln(`    Confidence: ${(threat.confidence * 100).toFixed(1)}%`);
                     output.writeln();

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

@@ -324,18 +324,18 @@ const restoreCommand = {
                 data: [
                     {
                         component: 'Memory',
-                        status: result.restored.memory ? output.success('Restored') : output.dim('Skipped'),
-                        count: result.stats.memoryEntriesRestored
+                        status: result.restoredComponents.memory ? output.success('Restored') : output.dim('Skipped'),
+                        count: result.restoredComponents.memory ? result.stats.memoryEntries : 0
                     },
                     {
                         component: 'Agents',
-                        status: result.restored.agents ? output.success('Restored') : output.dim('Skipped'),
-                        count: result.stats.agentsRestored
+                        status: result.restoredComponents.agents ? output.success('Restored') : output.dim('Skipped'),
+                        count: result.restoredComponents.agents ? result.stats.agents : 0
                     },
                     {
                         component: 'Tasks',
-                        status: result.restored.tasks ? output.success('Restored') : output.dim('Skipped'),
-                        count: result.stats.tasksRestored
+                        status: result.restoredComponents.tasks ? output.success('Restored') : output.dim('Skipped'),
+                        count: result.restoredComponents.tasks ? result.stats.tasks : 0
                     }
                 ]
             });

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

@@ -154,7 +154,7 @@ const createCommand = {
                 type: taskType,
                 description,
                 priority: priority || 'normal',
-                assignedTo: ctx.flags.assign ? [ctx.flags.assign] : undefined,
+                assignTo: ctx.flags.assign ? String(ctx.flags.assign).split(',').map(id => id.trim()).filter(Boolean) : undefined,
                 parentId: ctx.flags.parent,
                 dependencies,
                 tags,
@@ -245,14 +245,15 @@ const listCommand = {
         }
     ],
     action: async (ctx) => {
-        const status = ctx.flags.all ? 'all' : ctx.flags.status || 'pending,running';
+        const requestedStatus = ctx.flags.all ? 'all' : ctx.flags.status || 'pending,in_progress';
+        const status = requestedStatus === 'all' ? undefined : requestedStatus.replace(/\brunning\b/g, 'in_progress');
         const limit = ctx.flags.limit;
         try {
             const result = await callMCPTool('task_list', {
                 status,
                 type: ctx.flags.type,
                 priority: ctx.flags.priority,
-                agentId: ctx.flags.agent,
+                assignedTo: ctx.flags.agent,
                 limit,
                 offset: 0
             });
@@ -277,7 +278,7 @@ const listCommand = {
                     { key: 'progress', header: 'Progress', width: 10 }
                 ],
                 data: result.tasks.map(t => ({
-                    id: t.id,
+                    id: t.taskId,
                     type: t.type,
                     description: t.description.length > 27
                         ? t.description.slice(0, 27) + '...'

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js

@@ -1005,12 +1005,14 @@ export function generateAutoMemoryHook() {
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, '../..');
+const PROJECT_ROOT = process.env.CLAUDE_PROJECT_DIR
+  ? resolve(process.env.CLAUDE_PROJECT_DIR)
+  : join(__dirname, '../..');
 const DATA_DIR = join(PROJECT_ROOT, '.claude-flow', 'data');
 const STORE_PATH = join(DATA_DIR, 'auto-memory-store.json');
 

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

@@ -27,6 +27,12 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { trackRequest } from './mcp-tools/request-tracker.js';
 import { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall, } from './mcp-tools/policy-enforcer.js';
+/** A failed task can be valid data; only an explicit error denotes tool failure. */
+function hasToolError(result) {
+    return result !== null && typeof result === 'object'
+        && typeof result.error === 'string'
+        && result.error.trim().length > 0;
+}
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -666,11 +672,12 @@ export class MCPServerManager extends EventEmitter {
                     }
                     try {
                         const result = await callMCPTool(toolName, toolParams, { sessionId });
-                        trackRequest(toolName, true);
+                        const isError = hasToolError(result);
+                        trackRequest(toolName, !isError);
                         return {
                             jsonrpc: '2.0',
                             id: message.id,
-                            result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] },
+                            result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError },
                         };
                     }
                     catch (error) {
@@ -741,7 +748,7 @@ export class MCPServerManager extends EventEmitter {
             handler: async (input, context) => {
                 try {
                     const result = await callMCPTool(tool.name, input || {}, { sessionId: context?.sessionId || fallbackSessionId });
-                    trackRequest(tool.name, true);
+                    trackRequest(tool.name, !hasToolError(result));
                     return result;
                 }
                 catch (error) {

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

@@ -1,15 +1,4 @@
-/**
- * AgentDB MCP Tools — Phase 6 of ADR-053
- *
- * Exposes AgentDB v3 controller operations as MCP tools.
- * Provides direct access to ReasoningBank, CausalGraph, SkillLibrary,
- * AttestationLog, and bridge health through the MCP protocol.
- *
- * Security: All handlers validate input types, enforce length bounds,
- * and sanitize error messages before returning to MCP callers.
- *
- * @module v3/cli/mcp-tools/agentdb-tools
- */
+import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feedback-patterns.js';
 import { validateIdentifier, validateText } from './validate-input.js';
 // ===== Shared validation helpers =====
 const MAX_STRING_LENGTH = 100_000; // 100KB max for any string input
@@ -66,12 +55,6 @@ async function getBridge() {
 // Lazy-cached modules used by graph-query / graph-pathfinder dispatch.
 // Caching the resolved namespace avoids per-call dynamic-import overhead
 // in the ADR-130 hot path (smoke harness measures elapsedMs of every call).
-let graphBackendMod = null;
-async function getGraphBackend() {
-    if (!graphBackendMod)
-        graphBackendMod = await import('../ruvector/graph-backend.js');
-    return graphBackendMod;
-}
 let graphEdgeWriterMod = null;
 async function getGraphEdgeWriter() {
     if (!graphEdgeWriterMod)
@@ -396,6 +379,7 @@ export const agentdbFeedback = {
         type: 'object',
         properties: {
             taskId: { type: 'string', description: 'Task identifier' },
+            patterns: feedbackPatternsSchema,
             success: { type: 'boolean', description: 'Whether task succeeded' },
             quality: { type: 'number', description: 'Quality score (0-1)' },
             agent: { type: 'string', description: 'Agent that performed the task' },
@@ -415,9 +399,11 @@ export const agentdbFeedback = {
             const taskId = validateString(params.taskId, 'taskId', 500);
             if (!taskId)
                 return { success: false, error: 'taskId is required (non-empty string, max 500 chars)' };
+            const patterns = validateFeedbackPatterns(params.patterns);
             const bridge = await getBridge();
             const result = await bridge.bridgeRecordFeedback({
                 taskId,
+                patterns,
                 success: params.success === true,
                 quality: validateScore(params.quality, 0.85),
                 agent: validateString(params.agent, 'agent', 200) ?? undefined,
@@ -802,21 +788,18 @@ 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 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.',
+    description: 'Request memory consolidation. Use when checking whether AgentDB can consolidate retained memories; native file edits cannot perform controller consolidation. Currently returns unsupported when the installed controller is a no-op stub; no entries are promoted or compressed in that case.',
     inputSchema: {
         type: 'object',
-        properties: {
-            minAge: { type: 'number', description: 'Minimum age in hours since store (optional)' },
-            maxEntries: { type: 'number', description: 'Maximum entries to consolidate (optional)' },
-        },
+        properties: {},
     },
     handler: async (params) => {
         try {
+            if (Object.keys(params).length > 0) {
+                return { success: false, status: 'unsupported', error: 'agentdb_consolidate does not support options' };
+            }
             const bridge = await getBridge();
-            const result = await bridge.bridgeConsolidate({
-                minAge: typeof params.minAge === 'number' ? Math.max(0, params.minAge) : undefined,
-                maxEntries: validatePositiveInt(params.maxEntries, 1000, 10_000),
-            });
+            const result = await bridge.bridgeConsolidate({});
             return result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
         }
         catch (error) {
@@ -1060,7 +1043,7 @@ export const agentdbCausalNodeDelete = {
 };
 export const agentdbGraphQuery = {
     name: 'agentdb_graph-query',
-    description: 'Unified graph traversal across the knowledge graph (ADR-130). Native graph-node k-hop cannot filter by relation and returns an explicit unsupported error for that request; the SQL fallback can filter by relation. Inspect appliedDepth/truncated because SQL is bounded at 3 hops. Semantic and PageRank modes use their own backends. Use when you need structured graph traversal beyond flat memory search.',
+    description: 'Unified graph traversal across the knowledge graph (ADR-130). K-hop queries read committed graph_edges relationships through SQL; a separately populated native graph is not evidence of retained-history coverage. Inspect appliedDepth/truncated because SQL is bounded at 3 hops. maxNodesVisited bounds returned rows, not traversal work or elapsed time. Semantic and PageRank modes use their own backends. Use when you need relationship traversal beyond flat memory search.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1101,53 +1084,38 @@ export const agentdbGraphQuery = {
             }
             const budgetRaw = (params.complexityBudget ?? {});
             const budget = {
-                maxNodesVisited: budgetRaw.maxNodesVisited ?? 10_000,
-                maxDepth: budgetRaw.maxDepth ?? 5,
+                maxNodesVisited: validatePositiveInt(budgetRaw.maxNodesVisited, 10_000, 10_000),
+                maxDepth: validatePositiveInt(budgetRaw.maxDepth, 5, 5),
                 maxMillis: budgetRaw.maxMillis ?? 50,
                 maxMemoryMB: budgetRaw.maxMemoryMB ?? 32,
             };
-            const depth = Math.min(validatePositiveInt(params.depth, 2, budget.maxDepth), budget.maxDepth);
+            const requestedDepth = validatePositiveInt(params.depth, 2, 5);
+            const depth = Math.min(requestedDepth, budget.maxDepth);
             const topK = validatePositiveInt(params.topK, 10, MAX_TOP_K);
             const relation = validateString(params.relation, 'relation', 200) ?? undefined;
             // ── k-hop mode ──────────────────────────────────────────────────────────
             if (mode === 'k-hop') {
-                // graph-node's kHopNeighbors API has no relation parameter. Its graph
-                // and the SQL graph are separate stores, and SQL writes can be async;
-                // switching stores here could report a false negative. Refuse the
-                // unsupported native query instead of silently widening it.
-                try {
-                    const graphBackend = await getGraphBackend();
-                    if (await graphBackend.isGraphBackendAvailable()) {
-                        if (relation) {
-                            return { success: false, error: 'Native graph-node k-hop does not support relation filtering', unsupported: 'relation', mode, nodeId, relation, backend: 'graph-node' };
-                        }
-                        const neighbors = await graphBackend.getNeighbors(nodeId, depth);
-                        return {
-                            success: true, mode, nodeId, depth, appliedDepth: depth,
-                            results: neighbors.map(id => ({ nodeId: id })),
-                            count: neighbors.length,
-                            backend: 'graph-node',
-                            elapsedMs: Date.now() - t0,
-                        };
-                    }
-                }
-                catch { /* fall through to SQL */ }
-                // SQL CTE fallback is bounded at depth 3. Report that bound so callers
-                // cannot mistake an incomplete depth-5 cycle check for a complete one.
+                // #3315: graph-node and retained SQL are populated independently.
+                // Native availability does not establish historical coverage. Query
+                // the committed relationship source, and fail if it cannot be read.
                 try {
                     const { getBridgeDb } = await getGraphEdgeWriter();
                     const db = await getBridgeDb();
                     if (db) {
                         const appliedDepth = Math.min(depth, 3);
-                        const cteSql = buildKHopCTE(nodeId, appliedDepth, relation, budget.maxNodesVisited);
+                        const cteSql = buildKHopCTE(nodeId, appliedDepth, relation, budget.maxNodesVisited + 1);
                         // graph-edge-writer returns a better-sqlite3 Database after #2431.
                         // `db.exec(sql, params)` (sql.js style) is a runner with no result
                         // on better-sqlite3 — use `prepare(sql).raw().all(...)` to get the
                         // same array-of-arrays shape the downstream code expects.
-                        const rows = db.prepare(cteSql).raw().all();
+                        const allRows = db.prepare(cteSql).raw().all();
+                        const resultLimitReached = allRows.length > budget.maxNodesVisited;
+                        const rows = allRows.slice(0, budget.maxNodesVisited);
+                        const depthLimited = appliedDepth < requestedDepth;
                         return {
-                            success: true, mode, nodeId, depth, appliedDepth,
-                            ...(appliedDepth < depth ? { truncated: true } : {}),
+                            success: true, mode, nodeId, depth, requestedDepth, appliedDepth,
+                            depthLimited, resultLimitReached, truncated: depthLimited || resultLimitReached,
+                            resultLimit: budget.maxNodesVisited,
                             results: rows.map((r) => ({ nodeId: r[0], depth: r[1] })),
                             count: rows.length,
                             backend: 'sql-cte',
@@ -1155,11 +1123,10 @@ export const agentdbGraphQuery = {
                         };
                     }
                 }
-                catch { /* db unavailable */ }
-                if (relation) {
-                    return { success: false, error: 'Relation-filtered k-hop query requires the SQL graph_edges backend', mode, nodeId, relation };
+                catch (error) {
+                    return { success: false, error: `Retained SQL graph query failed: ${sanitizeError(error)}`, mode, nodeId };
                 }
-                return { success: false, error: 'No graph backend available for k-hop query', mode, nodeId };
+                return { success: false, error: 'Retained SQL graph_edges backend is unavailable for k-hop query', mode, nodeId };
             }
             // ── semantic mode ────────────────────────────────────────────────────────
             if (mode === 'semantic') {

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

@@ -1,7 +1,3 @@
-/**
- * Hooks MCP Tools
- * Provides intelligent hooks functionality via MCP protocol
- */
 import { type MCPTool } from './types.js';
 import { type RouterEmbedderKind } from '../ruvector/router-embedder.js';
 /**