claude-flow 3.48.0 → 3.50.0

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

@@ -2,15 +2,12 @@
 
 [![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)](https://cognitum.one/agentic-engineering)
 
-<!-- Try Ruflo — the 4 badges first-time visitors actually act on -->
-[![Try the UI Beta — flo.ruv.io](https://img.shields.io/badge/_Try_the_UI_Beta-flo.ruv.io-6366f1?style=for-the-badge&logoColor=white&logo=svelte)](https://flo.ruv.io/)
+<!-- Try Ruflo — the 3 badges first-time visitors actually act on -->
 [![npm version (ruflo)](https://img.shields.io/npm/v/ruflo?label=npx%20ruflo&style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/ruflo)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
 [![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
 
 <!-- Ecosystem strip (collapsed visually with flat-square) -->
-[![Goal Planner](https://img.shields.io/badge/_Goal_Planner-goal.ruv.io-8b5cf6?style=flat-square&logoColor=white&logo=react)](https://goal.ruv.io/)
-[![Live Agents](https://img.shields.io/badge/_Live_Agents-goal.ruv.io%2Fagents-10b981?style=flat-square&logoColor=white&logo=react)](https://goal.ruv.io/agents)
 [![🕸️ RuVector Agentic DB](https://img.shields.io/badge/RuVector_Agentic-DB-06b6d4?style=flat-square&logoColor=white&logo=graphql)](https://github.com/ruvnet/ruvector)
 [![Ecosystem downloads](https://img.shields.io/badge/ecosystem%20downloads-8.1M%2B-blue?style=flat-square&logo=npm)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.proof.json)
 [![Git clones (14d)](https://img.shields.io/badge/git%20clones%2014d-106k-blueviolet?style=flat-square&logo=github)](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.ledger.json)
@@ -19,6 +16,8 @@
 
 # Ruflo
 
+[English](README.md) · [简体中文](README.zh-CN.md)
+
 **An agent meta-harness for Claude Code and Codex.**
 
 [![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)
@@ -213,55 +212,6 @@ claude mcp add claude-flow -- npx ruflo@latest mcp start
 | 🛡️ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
 | 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
 | 🔬 **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
-| 💬 **[Web UI Beta](https://flo.ruv.io/)** | Multi-model chat at flo.ruv.io with parallel MCP tool calling and an in-browser WASM tool gallery |
-| 🎯 **[RuFlo Research](https://goal.ruv.io/)** | GOAP A\* planner at goal.ruv.io — plain-English goals → executable agent plans, with a live agent dashboard at [/agents](https://goal.ruv.io/agents) |
-
-<p align="center">
-  <a href="https://flo.ruv.io/">
-    <img src="v3/docs/assets/ruVocal.png" alt="RuFlo Web UI executing parallel MCP tool calls at flo.ruv.io — ruflo__memory_store and ruflo__memory_search firing in a single model turn with the 'Step 1 — 2 tools completed' parallel-execution indicator, thinking process panel visible, Qwen 3.6 Max as the active model. Multi-agent AI chat with Model Context Protocol (MCP) tool calling, persistent vector memory via AgentDB + HNSW, swarm coordination, and 6 frontier models including Claude Sonnet 4.6, Gemini 2.5 Pro, and OpenAI through OpenRouter." width="100%" />
-  </a>
-</p>
-
-### Web UI (Beta) — self-hostable, hosted demo at [flo.ruv.io](https://flo.ruv.io/)
-
-**RuFlo's web UI is a multi-model AI chat with built-in Model Context Protocol (MCP) tool calling.** Talk to Qwen, Claude, Gemini, or OpenAI while RuFlo invokes the same MCP tools the CLI uses — agent orchestration, persistent memory, swarm coordination, code review, GitHub ops — directly from chat. No install, no API key needed to try it.
-
-| | What it is | Why it matters |
-|---|------------|----------------|
-| 🧠 | **Any model, local or remote** | 6 curated frontier models out-of-the-box — Qwen 3.6 Max (default), Claude Sonnet 4.6, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash, OpenAI — via OpenRouter. Add your own: any OpenAI-compatible endpoint (vLLM, Ollama, LM Studio, Together, Groq, self-hosted). |
-| 🦾 | **ruvLLM self-learning AI** | Native support for [ruvLLM](https://github.com/ruvnet/RuVector/tree/main/examples/ruvLLM) (lives in `ruvnet/RuVector/examples/ruvLLM`) — RuFlo's self-improving local model layer. Routes to MicroLoRA adapters, learns from your trajectories via SONA, and stays on your machine. Pair with the cloud models or run fully offline. |
-| 🛠️ | **~210 tools, ready to call** | 5 server groups (Core, Intelligence, Agents, Memory, DevTools) plus an 18-tool gallery that runs entirely in your browser — works offline. |
-| 🔌 | **Bring your own MCP servers** | Click the **MCP (n)** pill in the chat input → *Add Server* and paste any MCP endpoint (HTTP, SSE, or stdio). Your tools join RuFlo's native ones in the same parallel-execution flow. Run a local MCP server on `localhost:3000` and it just works. |
-| ⚡ | **Tools run in parallel** | One model response can fire 4–6+ tools at the same time. The UI shows them as cards with a *Step 1 — 2 tools completed* badge so you can see exactly what ran. |
-| 💾 | **Memory that sticks** | Say *"remember my favorite color is indigo"* and ask weeks later — RuFlo recalls it. Backed by AgentDB + HNSW vector search (measured ~1.9x–4.7x faster than brute force above the crossover, recall@10 ~0.99). |
-| 📘 | **Built-in capabilities tour** | Click the question-mark icon in the sidebar — a "RuFlo Capabilities" modal opens with the full tool list, model strengths, architecture, and keyboard shortcuts. |
-| 🏠 | **Self-hostable** | Web UI is shipped as Docker (`ruflo/src/ruvocal/Dockerfile`) with embedded Mongo. Deploy to your own Cloud Run / Fly / Kubernetes / docker-compose. The hosted [flo.ruv.io](https://flo.ruv.io/) demo is one option; running your own is fully supported. |
-| 🚀 | **Zero install to try** | Open the hosted URL, pick a model, type a question. That's the whole onboarding. |
-
-**Try the hosted demo:** [https://flo.ruv.io/](https://flo.ruv.io/) — no account, no API key. **Run your own:** the source lives in [`ruflo/src/ruvocal/`](ruflo/src/ruvocal/) with a multi-stage Dockerfile (`INCLUDE_DB=true` builds in MongoDB) and a `cloudbuild.yaml` for Google Cloud Run. See [ADR-033](ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md) for the architecture and [issue #1689](https://github.com/ruvnet/ruflo/issues/1689) for the roadmap.
-
-<p align="center">
-  <a href="https://goal.ruv.io/agents">
-    <img src="v3/docs/assets/goal.png" alt="goal.ruv.io/agents — RuFlo Goal-Oriented Action Planning (GOAP) UI for autonomous AI agents. Visual goal decomposition, A* search through state spaces, multi-agent task assignment, and live agent telemetry." width="100%" />
-  </a>
-</p>
-
-### Goal Planner UI — autonomous agents at [goal.ruv.io](https://goal.ruv.io/)
-
-**Turn high-level goals into executable agent plans.** `goal.ruv.io` is RuFlo's hosted Goal-Oriented Action Planning (GOAP) front-end — describe an outcome in plain English and watch RuFlo decompose it into preconditions, actions, and an A* path through state space, then dispatch the work to live agents at [`/agents`](https://goal.ruv.io/agents).
-
-| | What it is | Why it matters |
-|---|------------|----------------|
-| 🎯 | **Plain-English goals** | Type *"ship the auth refactor with tests and a PR"* — RuFlo extracts the success criteria, the constraints, and the implicit preconditions. No JSON, no DSL. |
-| 🧭 | **GOAP A\* planner** | Classic gaming-AI planning ported to software work: state-space search through actions with preconditions/effects to find the shortest viable path. Replans on the fly when state changes. |
-| 🤖 | **Live agent dashboard** | [goal.ruv.io/agents](https://goal.ruv.io/agents) shows every spawned agent — role, current step, memory namespace, token budget, status. Click in to inspect trajectories, kill runaway workers, or reassign. |
-| 🌳 | **Visual plan tree** | Goals render as collapsible action trees with progress, blocked branches, and rollbacks highlighted. See *exactly* why an agent picked a path — no opaque chain-of-thought. |
-| ♻️ | **Adaptive replanning** | When an action fails or new info arrives, the planner re-runs A\* from the current state instead of restarting. Failures become learning, not loops. |
-| 🧠 | **Shared memory + SONA** | Plans, trajectories, and outcomes flow into AgentDB. Future plans retrieve past solutions via HNSW — the planner gets smarter with every run. |
-| 🔗 | **Wired to MCP tools** | Every action node maps to a tool call (RuFlo's ~210 MCP tools, your custom servers, or shell). The planner schedules them in parallel where the dependency graph allows. |
-| 🚀 | **Zero install to try** | Open [goal.ruv.io](https://goal.ruv.io/), describe a goal, watch it run. Source lives in [`v3/goal_ui/`](v3/goal_ui/) — Vite + Supabase, self-hostable. |
-
-**Try it:** [https://goal.ruv.io/](https://goal.ruv.io/) for goals · [https://goal.ruv.io/agents](https://goal.ruv.io/agents) for live agents. **Run your own:** clone the `goal` branch and `cd v3/goal_ui && npm install && npm run dev`.
 
 ### Agent Federation — Slack for Agents
 

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 1,
-  "generation": 6,
-  "generatedAt": "2026-09-17T21:28:47.530Z",
-  "gitSha": "702d1461",
+  "generation": 7,
+  "generatedAt": "2026-10-02T00:19:27.102Z",
+  "gitSha": "27982983",
   "catalog": {
-    "agents": 167,
+    "agents": 176,
     "tools": 418,
     "skills": 34
   },

package/v3/@claude-flow/cli/dist/src/commands/doctor.d.ts

@@ -14,7 +14,25 @@ interface HealthCheck {
 /** ADR-122 Phase 0: probe only the CLI version, without launching a browser. */
 export declare function evaluateAgentBrowserVersion(rawOutput: string): HealthCheck;
 export declare function checkAgentBrowserVersion(probe?: () => Promise<string>): Promise<HealthCheck>;
-export declare function checkMemoryPersistenceDriver(): Promise<HealthCheck>;
+/**
+ * #3565: report signed critical helpers whose on-disk content no longer
+ * matches the signed manifest. CLI startup heals such files, so this matters
+ * for the paths startup does not heal: `.LOCKED` or `RUFLO_HELPERS_LOCKED`
+ * (auto-restore skipped by design), an unverifiable package manifest, and an
+ * unresolvable package source.
+ */
+export declare function checkHelperIntegrity(opts?: {
+    cwd?: string;
+    homeDir?: string;
+    sourceDirOverride?: string | null;
+    pubkeyPemOverride?: string;
+}): Promise<HealthCheck>;
+export type MemoryPersistenceDriverDeps = {
+    loadBetterSqlite3?: () => Promise<{
+        default: any;
+    }>;
+};
+export declare function checkMemoryPersistenceDriver(deps?: MemoryPersistenceDriverDeps): Promise<HealthCheck>;
 /**
  * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy
  * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx

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

@@ -233,6 +233,69 @@ async function checkStaleSettingsNpx() {
         fix: 'Re-run `npx ruflo init` to migrate (the v3.13.3+ init migrator regenerates these to local-helper form). On macOS this prevents the process-storm / kernel-panic class reported in #2448.',
     };
 }
+/**
+ * #3565: report signed critical helpers whose on-disk content no longer
+ * matches the signed manifest. CLI startup heals such files, so this matters
+ * for the paths startup does not heal: `.LOCKED` or `RUFLO_HELPERS_LOCKED`
+ * (auto-restore skipped by design), an unverifiable package manifest, and an
+ * unresolvable package source.
+ */
+export async function checkHelperIntegrity(opts = {}) {
+    const name = 'Helper Integrity (#3565)';
+    const { verifyInstalledCriticalHelpers } = await import('../init/helper-integrity.js');
+    const { CRITICAL_HELPERS, findPackageHelpersDir } = await import('../init/helper-refresh.js');
+    const envLocked = /^(1|true|on|yes)$/i.test(String(process.env.RUFLO_HELPERS_LOCKED || ''));
+    const home = opts.homeDir ?? process.env.HOME ?? '';
+    const dirs = [
+        join(opts.cwd ?? process.cwd(), '.claude', 'helpers'),
+        ...(home ? [join(home, '.claude', 'helpers')] : []),
+    ].filter((d, i, a) => a.indexOf(d) === i && existsSync(join(d, 'hook-handler.cjs')));
+    if (dirs.length === 0) {
+        return { name, status: 'pass', message: 'no installed ruflo helpers to verify' };
+    }
+    const source = opts.sourceDirOverride === undefined ? findPackageHelpersDir() : opts.sourceDirOverride;
+    if (!source) {
+        return {
+            name, status: 'warn',
+            message: 'cannot verify installed helpers: the package helper source was not found',
+            fix: 'Reinstall @claude-flow/cli',
+        };
+    }
+    const tamperedLines = [];
+    const lockedLines = [];
+    for (const dir of dirs) {
+        const r = verifyInstalledCriticalHelpers(dir, source, CRITICAL_HELPERS, opts.pubkeyPemOverride);
+        if (r.blocked) {
+            return {
+                name, status: 'fail',
+                message: `cannot verify installed helpers: ${r.blocked}`,
+                fix: 'Reinstall @claude-flow/cli from a trusted source',
+            };
+        }
+        if (r.tampered.length === 0)
+            continue;
+        const line = `${dir}: ${r.tampered.join(', ')}`;
+        if (envLocked || existsSync(join(dir, '.LOCKED')))
+            lockedLines.push(line);
+        else
+            tamperedLines.push(line);
+    }
+    if (tamperedLines.length > 0) {
+        return {
+            name, status: 'fail',
+            message: `critical helpers do not match the signed manifest — ${tamperedLines.join('; ')}`,
+            fix: 'Run any ruflo command to restore verified copies (startup heals them), or `npx ruflo init --force`; then find out what modified them',
+        };
+    }
+    if (lockedLines.length > 0) {
+        return {
+            name, status: 'warn',
+            message: `locally modified helpers (auto-restore disabled by .LOCKED / RUFLO_HELPERS_LOCKED) — ${lockedLines.join('; ')}`,
+            fix: 'Expected if you edit helpers deliberately; otherwise remove .LOCKED and run any ruflo command to restore them',
+        };
+    }
+    return { name, status: 'pass', message: `${dirs.length} helper dir(s) match the signed manifest` };
+}
 async function checkDaemonStatus() {
     try {
         const pidFile = '.claude-flow/daemon.pid';
@@ -630,13 +693,9 @@ async function checkNativeAgentDbStructuralIntegrity(dbPath) {
         catch { /* best-effort */ }
     }
 }
-// #2968/#3321 — read-only native SQLite capability probe. A skipped
-// postinstall can leave the wrapper importable but its binding unavailable.
-// Schema size cannot identify the runtime driver or the database's history:
-// memory init creates its schema with sql.js even when native is available.
-// This probe does not verify schema compatibility or cross-process writes;
-// integrity checks and memory store's persistWarning retain their own roles.
-export async function checkMemoryPersistenceDriver() {
+export async function checkMemoryPersistenceDriver(deps = {}) {
+    const loadBetterSqlite3 = deps.loadBetterSqlite3
+        ?? (() => import('better-sqlite3'));
     const NAME = 'Memory Persistence Driver';
     const dbPath = await resolveMemoryDbPath();
     if (!dbPath) {
@@ -655,7 +714,7 @@ export async function checkMemoryPersistenceDriver() {
     }
     let Database;
     try {
-        Database = (await import('better-sqlite3')).default;
+        Database = (await loadBetterSqlite3()).default;
     }
     catch {
         Database = null;
@@ -2247,6 +2306,22 @@ async function checkMetaharness() {
         };
     }
 }
+// ADR-404 — ruflo as a Claude Code mod (function hooks, early access). One
+// line in a bare `doctor`: whether the mod is enabled, can load (function
+// hooks on, not refused by allowManagedModsOnly) and has started; never a
+// failure, since the classic hooks are the default and the fallback.
+// `ruflo mods doctor` prints every finding.
+async function checkMods() {
+    const { probeMods } = await import('../mods/probe.js');
+    const findings = probeMods({ projectRoot: process.cwd() });
+    const enabled = findings.find((f) => f.name === 'ruflo-mods plugin')?.status === 'pass';
+    if (!enabled)
+        return { name: 'ruflo mods (ADR-404)', status: 'pass', message: 'not enabled; classic hooks handle every event' };
+    const warnings = findings.filter((f) => f.status !== 'pass');
+    return warnings.length === 0
+        ? { name: 'ruflo mods (ADR-404)', status: 'pass', message: findings.find((f) => f.name === 'last mod start')?.message ?? 'enabled' }
+        : { name: 'ruflo mods (ADR-404)', status: 'warn', message: warnings.map((f) => `${f.name}: ${f.message}`).join('; '), fix: 'ruflo mods doctor' };
+}
 // Opt-in @ruvector/typesafe task router (optional peer). `--component typesafe` only.
 async function checkTypesafeRouter() {
     const name = '@ruvector/typesafe router';
@@ -2460,7 +2535,7 @@ export const doctorCommand = {
         {
             name: 'component',
             short: 'c',
-            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, browser, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, browser, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, mods, metaharness)',
             type: 'string'
         },
         {
@@ -2579,6 +2654,7 @@ export const doctorCommand = {
             checkGitRepo,
             checkConfigFile,
             checkStaleSettingsNpx, // #2448/#2677 — runaway `npx @latest` in settings
+            () => checkHelperIntegrity(), // #3565 — installed signed helpers vs manifest
             checkDaemonStatus,
             checkMemoryDatabase,
             checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run
@@ -2601,6 +2677,7 @@ export const doctorCommand = {
             checkFunnel, // ADR-305 — effective funnel state + deciding precedence source
             checkProxySponsoredConsent, // ADR-313 — Meta LLM Proxy sponsored-downtime health
             checkAuth, // ADR-306 — Cognitum identity (warn-only; never fails bare `ruflo doctor`)
+            checkMods, // ADR-404 — Claude Code mod path (warn-only)
         ];
         // #2677: `--component memory` now runs the whole memory-health suite,
         // not just the existence check. Values can be a single check or an
@@ -2619,6 +2696,7 @@ export const doctorCommand = {
             'browser': checkAgentBrowserVersion,
             'config': checkConfigFile,
             'stale-settings': checkStaleSettingsNpx, // #2448
+            'helpers': () => checkHelperIntegrity(), // #3565
             'daemon': checkDaemonStatus,
             'memory': [
                 checkMemoryDatabase, // existing: exists + statable (unchanged)
@@ -2653,6 +2731,7 @@ export const doctorCommand = {
             'proxy': [checkProxySponsoredConsent, checkProxyBinary, checkProxyProcess, checkProxyBindAddress],
             'auth': checkAuth, // ADR-306
             'typesafe': checkTypesafeRouter, // opt-in @ruvector/typesafe task router
+            'mods': checkMods, // ADR-404 — ruflo as a Claude Code mod
         };
         let checksToRun = allChecks;
         if (component && componentMap[component]) {

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

@@ -713,7 +713,7 @@ const routeCommand = {
             ?? 3;
         const parallel = Math.max(2, parallelRaw);
         const consensus = ctx.flags.consensus || 'majority-vote';
-        if (!task) {
+        if (!task || !task.trim()) {
             output.printError('Task description is required. Use --task or -t flag.');
             return { success: false, exitCode: 1 };
         }
@@ -782,11 +782,12 @@ const routeCommand = {
                 }
             }
             output.writeln();
+            const noMatch = result.matched === false;
             output.printBox([
                 `Agent: ${output.highlight(result.primaryAgent.type)}`,
-                `Confidence: ${(result.primaryAgent.confidence * 100).toFixed(1)}%`,
+                `Confidence: ${(result.primaryAgent.confidence * 100).toFixed(1)}%${noMatch ? ' (no match: default only)' : ''}`,
                 `Reason: ${result.primaryAgent.reason}`
-            ].join('\n'), 'Primary Recommendation');
+            ].join('\n'), noMatch ? 'Default Suggestion (nothing matched)' : 'Primary Recommendation');
             if (result.alternativeAgents.length > 0) {
                 output.writeln();
                 output.writeln(output.bold('Alternative Agents'));
@@ -803,7 +804,9 @@ const routeCommand = {
                 output.writeln();
                 output.writeln(output.bold('Estimated Metrics'));
                 output.printList([
-                    `Success Probability: ${(result.estimatedMetrics.successProbability * 100).toFixed(1)}%`,
+                    `Success Probability: ${result.estimatedMetrics.successProbability === null
+                        ? 'unknown (nothing matched)'
+                        : `${(result.estimatedMetrics.successProbability * 100).toFixed(1)}%`}`,
                     `Estimated Duration: ${result.estimatedMetrics.estimatedDuration}`,
                     `Complexity: ${result.estimatedMetrics.complexity.toUpperCase()}`
                 ]);

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

@@ -88,6 +88,8 @@ const commandLoaders = {
     advisor: () => import('./advisor.js'),
     // Ruflo verbs in Claude Code's spinnerVerbs rotation (ADR-318)
     spinner: () => import('./spinner.js'),
+    // ruflo as a Claude Code mod: function hooks, early access (ADR-404)
+    mods: () => import('./mods.js'),
     // Ruflo entries in Claude Code's companyAnnouncements startup rotation (ADR-319)
     announcements: () => import('./announcements.js'),
     // AGNTCY/Outshift runtime transport selection (ADR-324 §2) — optional,

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

@@ -775,6 +775,19 @@ const initClaudeAction = async (ctx) => {
                 output.writeln(output.warning('  Embedding initialization skipped (run manually)'));
             }
         }
+        // ADR-404 — opt into the Claude Code mod path. Additive: the classic
+        // hooks just written stay the default and the fallback.
+        if (ctx.flags.mods === true) {
+            output.writeln();
+            try {
+                const { installMod } = await import('../mods/install.js');
+                const installed = installMod(ctx.cwd, 'local');
+                output.writeln(output.success(`  ✓ ruflo-mods enabled in ${installed.settingsFile} (early access; run "ruflo mods doctor")`));
+            }
+            catch (err) {
+                output.writeln(output.warning(`  ruflo-mods not enabled: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
         if (!startDaemon && !startAll) {
             const bin = (process.argv[1] || '').includes('ruflo') ? 'ruflo' : 'claude-flow';
             output.writeln(output.bold('Next steps:'));
@@ -1500,6 +1513,13 @@ export const initCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            // ADR-404 — Claude Code function hooks are early access; opt-in only.
+            name: 'mods',
+            description: 'Also enable the ruflo Claude Code mod (function hooks, early access); classic hooks stay as fallback',
+            type: 'boolean',
+            default: false,
+        },
         {
             name: 'with-embeddings',
             description: 'Initialize ONNX embedding subsystem with hyperbolic support',

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

@@ -11,6 +11,8 @@ import { countSiblingStoreRows } from '../memory/sibling-store.js';
 import { resolveDbPath } from '../memory/memory-initializer.js';
 import { existsSync } from 'node:fs';
 import { siblingAgentDbPath } from '../memory/memory-bridge.js';
+import { validateIdentifier } from '../mcp-tools/validate-input.js';
+import { memoryKeyError } from '../mcp-tools/memory-tools.js';
 /**
  * #3228: a miss in one store is not a miss in the memory.
  *
@@ -21,10 +23,15 @@ import { siblingAgentDbPath } from '../memory/memory-bridge.js';
  * `found:false`. A confident negative is worse than an error, because nothing
  * prompts anyone to look further.
  */
-async function warnIfSiblingHasRows(pathFlag) {
+async function warnIfSiblingHasRows(pathFlag, hits) {
     const unread = await countSiblingStoreRows(resolveDbPath(pathFlag));
     if (unread && unread.rows > 0) {
-        output.printWarning(`This read covered one store. ${unread.rows} entries are in ${unread.path} and were not searched. ` +
+        // #3566: disclose on hits too. A partial positive ("Found 1 results") invites
+        // no second look, so it is the more dangerous case, not the safer one.
+        const lead = hits === undefined
+            ? 'This read covered one store.'
+            : `Partial result: ${hits} ${hits === 1 ? 'match' : 'matches'} came from the store read here.`;
+        output.printWarning(`${lead} ${unread.rows} entries are in ${unread.path} and were not searched. ` +
             `That store is written by the MCP/AgentDB path; read it with --path ${unread.path}.`);
     }
 }
@@ -48,7 +55,7 @@ function removalDbTargets(pathFlag) {
 }
 // Memory backends
 const BACKENDS = [
-    { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
+    { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing' },
     { value: 'sqlite', label: 'SQLite', hint: 'Lightweight local storage' },
     { value: 'hybrid', label: 'Hybrid', hint: 'SQLite + AgentDB (recommended)' },
     { value: 'memory', label: 'In-Memory', hint: 'Fast but non-persistent' }
@@ -182,6 +189,18 @@ const storeCommand = {
             output.printError('Value is required. Use --value');
             return { success: false, exitCode: 1 };
         }
+        // #3570: reject a traversal namespace before persisting, as export/purge do.
+        const vNs = validateIdentifier(namespace, 'namespace');
+        if (!vNs.valid) {
+            output.printError(vNs.error);
+            return { success: false, exitCode: 1 };
+        }
+        // #3570 follow-up: the same key rule MCP memory_store enforces.
+        const keyError = memoryKeyError(key);
+        if (keyError) {
+            output.printError(keyError);
+            return { success: false, exitCode: 1 };
+        }
         // #2752 MemPoison gate — scan before persist when opted in.
         // CLI flag ctx.flags.scanContent takes precedence over RUFLO_MEMORY_SCAN_ON_WRITE env var
         // (ADR-125 §"CLI flag wins" / ADR-130 §env-var-config-precedence — fix for #2794).
@@ -328,6 +347,9 @@ const retrieveCommand = {
                 return { success: false, exitCode: 1, data: { key, found: false } };
             }
             const entry = result.entry;
+            // #3566: the same key may also live in the sibling store. Goes to stderr,
+            // so --value-only / --format json stdout stays parseable.
+            await warnIfSiblingHasRows(ctx.flags.path, 1);
             // #2073: --value-only emits just the raw value (no decoration) for
             // piping into JSON.parse / jq / other downstream parsers without
             // any cleanup.
@@ -411,7 +433,7 @@ const searchCommand = {
         },
         {
             name: 'build-hnsw',
-            description: 'Build/rebuild HNSW index before searching (enables 150x-12,500x speedup)',
+            description: 'Build/rebuild HNSW index before searching',
             type: 'boolean',
             default: false
         },
@@ -512,7 +534,6 @@ const searchCommand = {
                     const status = getHNSWStatus();
                     output.printSuccess(`HNSW index built (${status.entryCount} vectors, ${buildTime}ms)`);
                     output.writeln(output.dim(`  Dimensions: ${status.dimensions}, Metric: cosine`));
-                    output.writeln(output.dim(`  Search speedup: ${status.entryCount > 10000 ? '12,500x' : status.entryCount > 1000 ? '150x' : '10x'}`));
                 }
                 else {
                     output.printWarning('HNSW index not available (install @ruvector/core for acceleration)');
@@ -576,6 +597,7 @@ const searchCommand = {
                     // Pure-keyword mode returns directly; skip the semantic path entirely.
                     if (ctx.flags.format === 'json') {
                         output.printJson({ query, searchType, results: keywordResults, searchTime: '0ms' });
+                        await warnIfSiblingHasRows(ctx.flags.path, keywordResults.length);
                         return { success: true, data: keywordResults };
                     }
                     output.writeln();
@@ -583,6 +605,7 @@ const searchCommand = {
                     for (const r of keywordResults) {
                         output.writeln(`  ${r.key} (${r.namespace}, score=${r.score.toFixed(2)}) — ${r.preview.slice(0, 80)}${r.preview.length > 80 ? '…' : ''}`);
                     }
+                    await warnIfSiblingHasRows(ctx.flags.path, keywordResults.length);
                     return { success: true, data: keywordResults };
                 }
                 // Hybrid mode: keyword hits will be MERGED after semantic runs below.
@@ -694,6 +717,7 @@ const searchCommand = {
             }
             if (ctx.flags.format === 'json') {
                 output.printJson({ query, searchType, results, searchTime: `${searchTimeMs}ms`, ...(smartStats ? { stats: smartStats } : {}) });
+                await warnIfSiblingHasRows(ctx.flags.path, results.length);
                 return { success: true, data: results };
             }
             // Performance stats
@@ -720,6 +744,7 @@ const searchCommand = {
             });
             output.writeln();
             output.printInfo(`Found ${results.length} results`);
+            await warnIfSiblingHasRows(ctx.flags.path, results.length);
             return { success: true, data: results };
         }
         catch (error) {
@@ -1160,8 +1185,6 @@ const statsCommand = {
                 output.writeln(output.bold('Embedding'));
                 output.printInfo(`Provider info unavailable: ${e instanceof Error ? e.message : String(e)}`);
             }
-            output.writeln();
-            output.printInfo('V3 Performance: 150x-12,500x faster search with HNSW indexing');
             return { success: true, data: stats };
         }
         catch (error) {

package/v3/@claude-flow/cli/dist/src/commands/mods.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ruflo mods` — opt into running ruflo as a Claude Code mod (ADR-404,
+ * Claude Code function hooks, early access).
+ *
+ * install/uninstall edit one settings file and record what they added;
+ * status/doctor report what can be known from outside a session; sync-policy
+ * rewrites the policy projection the mod's tool check reads. Classic hooks
+ * are never removed: they stay the default and the fallback.
+ */
+import type { Command } from '../types.js';
+export declare const modsCommand: Command;
+export default modsCommand;
+//# sourceMappingURL=mods.d.ts.map

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

@@ -0,0 +1,126 @@
+/**
+ * `ruflo mods` — opt into running ruflo as a Claude Code mod (ADR-404,
+ * Claude Code function hooks, early access).
+ *
+ * install/uninstall edit one settings file and record what they added;
+ * status/doctor report what can be known from outside a session; sync-policy
+ * rewrites the policy projection the mod's tool check reads. Classic hooks
+ * are never removed: they stay the default and the fallback.
+ */
+import { output } from '../output.js';
+import { installMod, uninstallMod } from '../mods/install.js';
+import { probeMods } from '../mods/probe.js';
+function projectRoot(ctx) {
+    return ctx.flags.projectRoot ?? ctx.flags['project-root'] ?? ctx.cwd ?? process.cwd();
+}
+function printFindings(findings) {
+    for (const f of findings) {
+        const mark = f.status === 'pass' ? output.success('✓') : f.status === 'warn' ? output.warning('!') : output.error('✗');
+        output.writeln(`${mark} ${f.name}: ${f.message}`);
+        if (f.fix && f.status !== 'pass')
+            output.writeln(output.dim(`    fix: ${f.fix}`));
+    }
+}
+const rootOption = { name: 'project-root', description: 'Project root (default: current directory)', type: 'string' };
+const installSub = {
+    name: 'install',
+    description: 'Enable the ruflo-mods plugin for this project (opt-in; classic hooks stay as fallback)',
+    options: [
+        rootOption,
+        { name: 'scope', description: 'local (.claude/settings.local.json, default) | project (.claude/settings.json)', type: 'string', default: 'local' },
+        { name: 'dry-run', description: 'Show the settings that would be written', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const scope = ctx.flags.scope ?? 'local';
+        if (scope !== 'local' && scope !== 'project') {
+            output.printError(`--scope must be local or project, got ${scope}`);
+            return { success: false, exitCode: 1 };
+        }
+        const root = projectRoot(ctx);
+        const result = installMod(root, scope, (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
+        if (result.dryRun) {
+            output.writeln(`Would write ${result.settingsFile}:`);
+            output.printJson(result.next);
+            return { success: true, data: result };
+        }
+        await syncPolicy(root, true);
+        output.printSuccess(`ruflo-mods enabled in ${result.settingsFile}${result.backup ? ` (backup: ${result.backup})` : ''}`);
+        output.writeln('Restart Claude Code, then run /ruflo-mods in a session to see what the mod owns.');
+        output.writeln(output.dim('Early access: Claude Code loads it only where function hooks are on. Run `ruflo mods doctor`.'));
+        return { success: true, data: result };
+    },
+};
+const uninstallSub = {
+    name: 'uninstall',
+    description: 'Remove what `ruflo mods install` added (classic hooks take every event back)',
+    options: [rootOption, { name: 'dry-run', description: 'Show what would be removed', type: 'boolean', default: false }],
+    action: async (ctx) => {
+        const result = uninstallMod(projectRoot(ctx), (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
+        if (!result.removed) {
+            output.printWarning('No install record (.claude-flow/mods/install.json): nothing ruflo added to remove.');
+            return { success: true, data: result };
+        }
+        output.printSuccess(`${result.dryRun ? 'Would remove' : 'Removed'} ruflo-mods from ${result.settingsFile}`);
+        return { success: true, data: result };
+    },
+};
+function findingsCommand(name, description) {
+    return {
+        name,
+        description,
+        options: [rootOption, { name: 'json', description: 'Output as JSON', type: 'boolean', default: false }],
+        action: async (ctx) => {
+            const findings = probeMods({ projectRoot: projectRoot(ctx) });
+            if (ctx.flags.json)
+                output.printJson(findings);
+            else
+                printFindings(findings);
+            const failed = findings.some((f) => f.status === 'fail');
+            // status reports; doctor gates (warnings are expected while early access is off).
+            return { success: !failed, exitCode: name === 'doctor' && failed ? 1 : 0, data: findings };
+        },
+    };
+}
+async function syncPolicy(root, quiet) {
+    try {
+        const { loadPolicyState } = await import('../services/policy-runtime.js');
+        const { syncPolicyProjection } = await import('../mods/policy-projection.js');
+        const result = syncPolicyProjection(root, loadPolicyState(root));
+        if (!quiet || result.action !== 'unchanged')
+            output.writeln(`policy projection: ${result.action} (${result.path})`);
+        return true;
+    }
+    catch (error) {
+        output.printWarning(`policy projection not synced: ${error.message}`);
+        return false;
+    }
+}
+const syncPolicySub = {
+    name: 'sync-policy',
+    description: 'Rewrite the Claude Code policy projection from .claude-flow/policy/state.json',
+    options: [rootOption],
+    action: async (ctx) => {
+        const ok = await syncPolicy(projectRoot(ctx), false);
+        return { success: ok, exitCode: ok ? 0 : 1 };
+    },
+};
+const statusSub = findingsCommand('status', 'Show whether the mod is enabled, can load, and what it owns');
+export const modsCommand = {
+    name: 'mods',
+    description: 'Run ruflo as a Claude Code mod (function hooks, early access, ADR-404)',
+    subcommands: [
+        installSub,
+        uninstallSub,
+        statusSub,
+        findingsCommand('doctor', 'Check the mod path; exits 1 only on a failure'),
+        syncPolicySub,
+    ],
+    examples: [
+        { command: 'ruflo mods install', description: 'Enable for this project (settings.local.json)' },
+        { command: 'ruflo mods doctor', description: 'Function hooks on? Refused by policy? Handshake supported?' },
+        { command: 'ruflo mods uninstall', description: 'Remove only what install added' },
+    ],
+    action: statusSub.action,
+};
+export default modsCommand;
+//# sourceMappingURL=mods.js.map