@claude-flow/cli 3.7.0-alpha.8 → 3.7.0-alpha.81

package/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: {
@@ -1394,14 +1394,44 @@ export const hooksPretrain = {
         // (readdirSync/statSync already imported statically at the top.)
         const extCounts = {};
         let filesAnalyzed = 0;
+        // #1953: separate budget for code files. The old code gated the
+        // import-pattern extraction on `filesAnalyzed <= 50`, which counts
+        // EVERY directory entry (including .md/.yaml/.db/.log). In any
+        // markdown/docs-heavy repo, the depth-first walker burned through the
+        // 50-file budget on non-code files before reaching any source — so
+        // `patternsExtracted: 0` even when hundreds of `.ts`/`.js` files existed.
+        let codeFilesScanned = 0;
         let totalLines = 0;
         const maxDepth = depth === 'shallow' ? 2 : depth === 'deep' ? 6 : 4;
         const patterns = [];
+        // #1953: recurse into directories that typically contain code first
+        // (`src/`, `apps/`, `packages/`, `lib/`, `crates/`, `workers/`, `server/`)
+        // before docs / specs / planning dirs, so the import-extraction budget
+        // is spent on the highest-signal directories even in mixed repos.
+        const CODE_DIR_PREFIXES = new Set([
+            'src', 'apps', 'packages', 'lib', 'crates', 'workers',
+            'server', 'backend', 'frontend', 'app', 'cli', 'core',
+        ]);
+        const scoreEntry = (name) => {
+            if (CODE_DIR_PREFIXES.has(name))
+                return 0;
+            // Deprioritise common docs / output directories.
+            if (/^(docs?|specs?|_.*|examples?|samples?|out|build|target|coverage|tests?)$/.test(name))
+                return 2;
+            return 1;
+        };
         const scan = (dir, currentDepth) => {
             if (currentDepth > maxDepth)
                 return;
             try {
                 const entries = readdirSync(dir, { withFileTypes: true });
+                // Sort: code-likely dirs first, files mixed in by name, deprioritised
+                // dirs last. Stable for deterministic test behaviour.
+                entries.sort((a, b) => {
+                    const sa = a.isDirectory() ? scoreEntry(a.name) : 1;
+                    const sb = b.isDirectory() ? scoreEntry(b.name) : 1;
+                    return sa - sb;
+                });
                 for (const entry of entries) {
                     if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist')
                         continue;
@@ -1415,15 +1445,18 @@ export const hooksPretrain = {
                             extCounts[ext] = (extCounts[ext] || 0) + 1;
                         filesAnalyzed++;
                         // For code files, count lines and extract imports
-                        if (['.ts', '.js', '.py', '.go', '.rs', '.java'].includes(ext)) {
+                        if (['.ts', '.js', '.tsx', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java'].includes(ext)) {
                             try {
                                 const content = readFileSync(full, 'utf-8');
                                 const lines = content.split('\n');
                                 totalLines += lines.length;
-                                // Extract import patterns (first 50 files max for performance)
-                                if (filesAnalyzed <= 50) {
-                                    for (const line of lines.slice(0, 30)) {
-                                        if (line.startsWith('import ') || line.startsWith('from ') || line.startsWith('const ') && line.includes('require(')) {
+                                // #1953: gate on the code-file count, not every-file count.
+                                // Also widened the per-file scan window from 30 → 80 lines:
+                                // modern TS files often have license headers + JSDoc + type
+                                // imports before the first `import` statement.
+                                if (++codeFilesScanned <= 50) {
+                                    for (const line of lines.slice(0, 80)) {
+                                        if (line.startsWith('import ') || line.startsWith('from ') || (line.startsWith('const ') && line.includes('require('))) {
                                             const trimmed = line.trim();
                                             if (trimmed.length < 120 && !patterns.includes(trimmed))
                                                 patterns.push(trimmed);
@@ -1455,6 +1488,17 @@ export const hooksPretrain = {
             patternsStored = patterns.length;
         }
         catch { /* AgentDB not available */ }
+        // #1847: when the corpus contains files but no patterns were extracted
+        // (typical for Markdown vaults), make the source-code-only extraction
+        // contract explicit so users don't conclude the hook system is broken.
+        const SUPPORTED_EXTRACTION_EXTS = ['.ts', '.js', '.tsx', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java'];
+        let note;
+        if (filesAnalyzed > 0 && patterns.length === 0) {
+            const codeFileCount = SUPPORTED_EXTRACTION_EXTS.reduce((sum, ext) => sum + (extCounts[ext] ?? 0), 0);
+            note = codeFileCount === 0
+                ? `No source-code patterns found. hooks_pretrain extracts import/require lines from ${SUPPORTED_EXTRACTION_EXTS.join('/')} files only — Markdown/text/asset corpora produce zero patterns by design. This is not a hook-system failure; live trajectories and statusline are independent.`
+                : `Found ${codeFileCount} source-code file(s) but extracted zero import/require patterns. They may be empty, generated, or use non-standard module syntax.`;
+        }
         return {
             success: true,
             _real: true,
@@ -1467,14 +1511,21 @@ export const hooksPretrain = {
                 patternsExtracted: patterns.length,
                 patternsStored,
                 fileTypes: Object.entries(extCounts).sort((a, b) => b[1] - a[1]).slice(0, 15).map(([ext, count]) => ({ ext, count })),
+                // #1847: explicit extraction contract so callers can tell pretrain
+                // patterns apart from live trajectories and hook statusline state.
+                sources: {
+                    extractedFrom: SUPPORTED_EXTRACTION_EXTS,
+                    scope: 'pretrain-only (live trajectories + statusline are tracked separately)',
+                },
             },
+            ...(note ? { note } : {}),
         };
     },
 };
 // 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: {
@@ -1537,7 +1588,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: {
@@ -1619,7 +1670,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: {
@@ -1762,7 +1813,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: {
@@ -1849,7 +1900,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: {
@@ -1891,7 +1942,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: {
@@ -1930,7 +1981,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: {
@@ -1968,7 +2019,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: {
@@ -2109,7 +2160,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: {},
@@ -2176,7 +2227,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: {
@@ -2237,7 +2288,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: {
@@ -2290,7 +2341,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: {
@@ -2434,7 +2485,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: {
@@ -2516,7 +2567,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: {
@@ -2625,7 +2676,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: {
@@ -2828,7 +2879,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: {
@@ -2899,7 +2950,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: {
@@ -3311,7 +3362,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: {
@@ -3354,7 +3405,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: {
@@ -3424,16 +3475,37 @@ export const hooksWorkerDispatch = {
         activeWorkers.set(workerId, worker);
         // Determine honest status
         let reportedStatus;
-        let note;
+        let note = '';
         if (!daemonAlive) {
             reportedStatus = 'no-daemon';
             note = 'No worker daemon detected. Run `claude-flow daemon start` to enable real worker execution. The dispatch was recorded in-process but no actual work will run.';
         }
         else if (background) {
-            // Daemon is alive — record the queued worker. The daemon polls activeWorkers
-            // via its own state file, so this constitutes a real queue entry.
-            reportedStatus = 'queued';
-            note = `Worker queued for daemon (pid ${daemonPid}). Poll hooks_worker-status to track progression — do not assume completion until status === "completed".`;
+            // #1845: write a durable queue file the daemon polls every 5s. Until
+            // 3.7.0-alpha.11 the dispatch only updated a process-local Map that
+            // the daemon (separate process) could never see, so `queued` was a
+            // lie. The queue file makes it real and inspectable on disk.
+            const queueDir = join(cwd, '.claude-flow', 'daemon-queue');
+            const queuePath = join(queueDir, `${workerId}.json`);
+            let queueWritten = false;
+            try {
+                if (!existsSync(queueDir))
+                    mkdirSync(queueDir, { recursive: true });
+                writeFileSync(queuePath, JSON.stringify({ workerId, trigger, context, priority, enqueuedAt: new Date().toISOString() }, null, 2));
+                queueWritten = true;
+            }
+            catch (err) {
+                // Filesystem error — fall back to mcp-only status so we never
+                // claim queued without proof.
+                note = `Daemon detected (pid ${daemonPid}) but queue write to ${queuePath} failed: ${err.message}. Worker recorded in-process only; use \`ruflo daemon trigger -w ${trigger}\` to run synchronously.`;
+            }
+            if (queueWritten) {
+                reportedStatus = 'queued';
+                note = `Worker queued for daemon (pid ${daemonPid}) at ${queuePath}. Daemon polls every 5s; processed entries move to .claude-flow/daemon-queue/.processed/. Poll hooks_worker-status until status === "completed".`;
+            }
+            else {
+                reportedStatus = 'mcp-only';
+            }
         }
         else {
             // Synchronous mode without a runner — be honest about it
@@ -3467,7 +3539,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: {
@@ -3524,7 +3596,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: {
@@ -3603,7 +3675,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: {
@@ -3649,7 +3721,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: {
@@ -3684,7 +3756,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: {},
@@ -3721,7 +3793,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: {
@@ -3760,8 +3832,69 @@ export const hooksWorkerCancel = {
         };
     },
 };
+// #1916: the `ruflo hooks teammate-idle` / `ruflo hooks task-completed` CLI
+// subcommands (Agent Teams hooks) referenced unregistered tools. Minimal
+// acknowledgement handlers with the shapes the CLI expects — auto-assignment
+// and pattern-learning are delegated to the task-queue consumer / intelligence
+// pipeline (a tracked #1916 follow-up).
+export const hooksTeammateIdle = {
+    name: 'hooks_teammate-idle',
+    description: 'Agent Teams hook — fired when a teammate agent finishes its turn; reports whether a pending task can be auto-assigned. Use when native Task is wrong because you have a persistent multi-agent team with a shared task list and want idle workers picked up automatically rather than re-spawning subagents. For a one-shot Task, native Task is fine. (Auto-assignment is delegated to the task-queue consumer — this acknowledges the event today.)',
+    category: 'hooks',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            teammateId: { type: 'string', description: 'ID of the idle teammate' },
+            teamName: { type: 'string', description: 'Team name' },
+            autoAssign: { type: 'boolean', description: 'Auto-assign a pending task if available' },
+            checkTaskList: { type: 'boolean', description: 'Consult the shared task list' },
+            timestamp: { type: 'number', description: 'Event timestamp (ms)' },
+        },
+    },
+    handler: async (input) => {
+        const teammateId = String(input.teammateId ?? '');
+        return {
+            success: true,
+            teammateId,
+            action: 'waiting',
+            pendingTasks: 0,
+            message: 'teammate-idle acknowledged; auto-assignment requires the task-queue consumer (#1916 follow-up)',
+        };
+    },
+};
+export const hooksTaskCompleted = {
+    name: 'hooks_task-completed',
+    description: 'Agent Teams hook — fired when a task is marked complete; records completion and (eventually) trains patterns + notifies the team lead. Use when native TodoWrite is wrong because the work was a persisted, agent-assigned task whose outcome should feed cross-session learning and team coordination. For an in-session checklist tick, native TodoWrite is fine. (Pattern-learning is delegated to the intelligence pipeline — this records the completion today.)',
+    category: 'hooks',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            taskId: { type: 'string', description: 'ID of the completed task' },
+            teammateId: { type: 'string', description: 'Teammate that completed it' },
+            success: { type: 'boolean', description: 'Whether the task succeeded' },
+            quality: { type: 'number', description: 'Quality score 0-1' },
+            trainPatterns: { type: 'boolean', description: 'Feed the outcome to the learning pipeline' },
+            notifyLead: { type: 'boolean', description: 'Notify the team lead' },
+        },
+        required: ['taskId'],
+    },
+    handler: async (input) => {
+        const taskId = String(input.taskId ?? '');
+        const quality = typeof input.quality === 'number' ? input.quality : (input.success === false ? 0 : 1);
+        return {
+            success: true,
+            taskId,
+            patternsLearned: 0,
+            leadNotified: input.notifyLead === true,
+            metrics: { duration: 0, quality, learningUpdates: 0 },
+            note: 'completion recorded; pattern-learning is delegated to the intelligence pipeline (#1916 follow-up)',
+        };
+    },
+};
 // Export all hooks tools
 export const hooksTools = [
+    hooksTeammateIdle,
+    hooksTaskCompleted,
     hooksPreEdit,
     hooksPostEdit,
     hooksPreCommand,