@claude-flow/cli 3.71.2 → 3.71.3

package/.claude/helpers/auto-memory-hook.mjs

@@ -9,6 +9,10 @@
  *   node auto-memory-hook.mjs import   # SessionStart: import auto memory files into backend
  *   node auto-memory-hook.mjs sync     # SessionEnd: sync insights back to MEMORY.md
  *   node auto-memory-hook.mjs status   # Show bridge status
+ *   node auto-memory-hook.mjs read <namespace> <key>   # Read-only exact lookup, prints JSON
+ *
+ * import and sync exit 1 when they fail (never 2, which Claude Code treats as
+ * "block"), so a failed write is visible without stopping the session.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, rmdirSync, rmSync, statSync } from 'fs';
@@ -57,6 +61,9 @@ function warnMemoryUnavailable() {
 
 const DEBUG = !!(process.env.RUFLO_DEBUG || process.env.DEBUG);
 
+/** A command failure whose message is already complete; main prints it and exits 1. */
+class HookFailure extends Error {}
+
 // ── Graceful shutdown (FIX 3) ───────────────────────────────────────────────
 // Track the backend in use so a SIGTERM/SIGINT mid-run can still flush it
 // (the JSON backend persists; a SQLite-backed one closes/flushes WAL) instead
@@ -76,8 +83,9 @@ async function gracefulExit(signal) {
 process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });
 process.on('SIGINT', () => { gracefulExit('SIGINT'); });
 
-// Ensure data dir
-if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+// The data directory is created lazily by import and sync only, so the
+// read-only `read` subcommand never creates directories (#4685).
+function ensureDataDir() { if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true }); }
 
 // ============================================================================
 // Store write safety (#4058): intelligence.cjs read-modify-writes the same
@@ -118,6 +126,83 @@ function writeFileAtomic(filePath, text) {
   }
 }
 
+// ============================================================================
+// Strict store reads (#4685): only ENOENT means "no store yet". A read or
+// parse failure, a non-array document, or an entry without a unique string id
+// is an error, and the file is never rewritten, so its bytes stay intact.
+// ============================================================================
+
+class StoreError extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = 'StoreError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function parseStoreText(text, filePath) {
+  let data;
+  try { data = JSON.parse(text); } catch (e) {
+    throw new StoreError('STORE_PARSE_FAILED', `${filePath} is not valid JSON (${e.message}); left unchanged`, e);
+  }
+  if (!Array.isArray(data)) {
+    throw new StoreError('STORE_NOT_ARRAY', `${filePath} does not hold a JSON array; left unchanged`);
+  }
+  const seen = new Set();
+  for (let i = 0; i < data.length; i++) {
+    const e = data[i];
+    if (!e || typeof e !== 'object' || Array.isArray(e)) {
+      throw new StoreError('STORE_BAD_ENTRY', `${filePath} entry ${i} is not an object; left unchanged`);
+    }
+    if (typeof e.id !== 'string' || e.id.length === 0) {
+      throw new StoreError('STORE_BAD_ID', `${filePath} entry ${i} has no string id; left unchanged`);
+    }
+    if (seen.has(e.id)) {
+      // intelligence.cjs de-duplicates the store by id when it consolidates,
+      // which repairs a duplicate an older writer left behind.
+      throw new StoreError('STORE_DUPLICATE_ID', `${filePath} holds duplicate id ${JSON.stringify(e.id)}; left unchanged`);
+    }
+    seen.add(e.id);
+  }
+  return data;
+}
+
+/** The parsed entries, or null when the file does not exist. Anything else throws a StoreError. */
+function readStoreFile(filePath) {
+  let text;
+  try { text = readFileSync(filePath, 'utf-8'); } catch (e) {
+    if (e && e.code === 'ENOENT') return null;
+    const why = (e && (e.code || e.message)) || String(e);
+    throw new StoreError('STORE_READ_FAILED', `cannot read ${filePath} (${why}); left unchanged`, e);
+  }
+  return parseStoreText(text, filePath);
+}
+
+/**
+ * Re-read the store and check that every expected entry is present and equal
+ * under `same`, and that every deleted id is gone. Throws on any mismatch.
+ */
+function verifyStoreFile(filePath, expected, deletedIds, same) {
+  const onDisk = readStoreFile(filePath);
+  if (onDisk === null) throw new StoreError('STORE_READBACK_MISMATCH', `${filePath} is missing after the write`);
+  const byId = new Map(onDisk.map((e) => [e.id, e]));
+  for (const [id, want] of expected) {
+    const got = byId.get(id);
+    if (!got) throw new StoreError('STORE_READBACK_MISMATCH', `${filePath} readback is missing entry ${JSON.stringify(id)}`);
+    if (!same(got, want)) throw new StoreError('STORE_READBACK_MISMATCH', `${filePath} readback differs for entry ${JSON.stringify(id)}`);
+  }
+  for (const id of deletedIds) {
+    if (!expected.has(id) && byId.has(id)) {
+      throw new StoreError('STORE_READBACK_MISMATCH', `${filePath} readback still holds deleted entry ${JSON.stringify(id)}`);
+    }
+  }
+  return onDisk;
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const sameRecord = (a, b) => a.namespace === b.namespace && a.key === b.key && a.content === b.content;
+
 // Claude Code shares one auto-memory directory across every worktree of a
 // repository, but findGitRoot() in the memory package stops at a worktree's
 // `.git` FILE and keys the directory by the worktree path (#4058). Resolve the
@@ -149,21 +234,36 @@ class JsonFileBackend {
     this.entries = new Map();
     this.loadedIds = new Set();
     this.deletedIds = new Set();
+    // Entries this instance wrote (or deleted), so a caller can confirm them on disk.
+    this.written = new Map();
+    this.storePresent = false;
   }
 
   async initialize() {
-    if (existsSync(this.filePath)) {
-      try {
-        const data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
-        if (Array.isArray(data)) {
-          for (const entry of data) { this.entries.set(entry.id, entry); this.loadedIds.add(entry.id); }
-        }
-      } catch { /* start fresh */ }
+    // Throws on anything but a missing file, so a damaged store is never
+    // mistaken for an empty one and later overwritten (#4685).
+    const data = readStoreFile(this.filePath);
+    this.storePresent = data !== null;
+    for (const entry of data || []) { this.entries.set(entry.id, entry); this.loadedIds.add(entry.id); }
+  }
+
+  _track(entry) {
+    if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) {
+      throw new StoreError('STORE_BAD_ID', 'refusing to store an entry without a string id');
     }
+    this.entries.set(entry.id, entry);
+    this.written.set(entry.id, entry);
+    this.deletedIds.delete(entry.id);
+  }
+
+  _forget(id) {
+    this.deletedIds.add(id);
+    this.written.delete(id);
+    return this.entries.delete(id);
   }
 
   async shutdown() { this._persist(); }
-  async store(entry) { this.entries.set(entry.id, entry); this._persist(); }
+  async store(entry) { this._track(entry); this._persist(); }
   async get(id) { return this.entries.get(id) ?? null; }
   async getByKey(key, ns) {
     for (const e of this.entries.values()) {
@@ -178,10 +278,11 @@ class JsonFileBackend {
     if (updates.content !== undefined) e.content = updates.content;
     if (updates.tags) e.tags = updates.tags;
     e.updatedAt = Date.now();
+    this.written.set(id, e);
     this._persist();
     return e;
   }
-  async delete(id) { this.deletedIds.add(id); return this.entries.delete(id); }
+  async delete(id) { return this._forget(id); }
   async query(opts) {
     let results = [...this.entries.values()];
     if (opts?.namespace) results = results.filter(e => e.namespace === opts.namespace);
@@ -199,8 +300,8 @@ class JsonFileBackend {
     return results;
   }
   async search() { return []; } // No vector search in JSON backend
-  async bulkInsert(entries) { for (const e of entries) this.entries.set(e.id, e); this._persist(); }
-  async bulkDelete(ids) { let n = 0; for (const id of ids) { this.deletedIds.add(id); if (this.entries.delete(id)) n++; } this._persist(); return n; }
+  async bulkInsert(entries) { for (const e of entries) this._track(e); this._persist(); }
+  async bulkDelete(ids) { let n = 0; for (const id of ids) { if (this._forget(id)) n++; } this._persist(); return n; }
   async count() { return this.entries.size; }
   async listNamespaces() {
     const ns = new Set();
@@ -209,8 +310,8 @@ class JsonFileBackend {
   }
   async clearNamespace(ns) {
     let n = 0;
-    for (const [id, e] of this.entries) {
-      if (e.namespace === ns) { this.deletedIds.add(id); this.entries.delete(id); n++; }
+    for (const [id, e] of [...this.entries]) {
+      if (e.namespace === ns) { this._forget(id); n++; }
     }
     this._persist();
     return n;
@@ -235,25 +336,24 @@ class JsonFileBackend {
     };
   }
 
+  // Errors propagate (#4685): a failed read, write or rename must reject the
+  // store/bulkInsert/shutdown call instead of resolving with an in-memory-only
+  // update. The readback runs inside the lock so a parallel writer cannot race it.
   _persist() {
-    try {
-      withStoreLock(this.filePath, () => {
-        // Keep entries another writer (intelligence.cjs, a parallel hook) added
-        // after we loaded; ours win on the same id, and our own deletes stay deleted.
-        const merged = new Map(this.entries);
-        try {
-          const onDisk = JSON.parse(readFileSync(this.filePath, 'utf-8'));
-          if (Array.isArray(onDisk)) {
-            for (const e of onDisk) {
-              if (e && !merged.has(e.id) && !this.loadedIds.has(e.id) && !this.deletedIds.has(e.id)) merged.set(e.id, e);
-            }
-          }
-        } catch { /* missing or unreadable: write ours */ }
-        writeFileAtomic(this.filePath, JSON.stringify([...merged.values()], null, 2));
-        for (const id of merged.keys()) this.loadedIds.add(id);
-        this.entries = merged;
-      });
-    } catch { /* best effort */ }
+    withStoreLock(this.filePath, () => {
+      // Keep entries another writer (intelligence.cjs, a parallel hook) added
+      // after we loaded; ours win on the same id, and our own deletes stay deleted.
+      // A missing file is the only case that writes without merging.
+      const merged = new Map(this.entries);
+      for (const e of readStoreFile(this.filePath) || []) {
+        if (!merged.has(e.id) && !this.loadedIds.has(e.id) && !this.deletedIds.has(e.id)) merged.set(e.id, e);
+      }
+      writeFileAtomic(this.filePath, JSON.stringify([...merged.values()], null, 2));
+      verifyStoreFile(this.filePath, merged, this.deletedIds, sameJson);
+      for (const id of merged.keys()) this.loadedIds.add(id);
+      this.entries = merged;
+      this.storePresent = true;
+    });
   }
 }
 
@@ -365,6 +465,7 @@ async function doImport() {
   }
 
   const config = readConfig();
+  ensureDataDir();
   const backend = trackBackend(new JsonFileBackend(STORE_PATH));
   await backend.initialize();
 
@@ -395,19 +496,32 @@ async function doImport() {
   }
 
   const bridge = new memPkg.AutoMemoryBridge(backend, bridgeConfig);
+  const fileErrors = [];
+  if (typeof bridge.on === 'function') bridge.on('import:file-error', (info) => { fileErrors.push(info?.file || 'unknown'); });
 
+  // Success is reported only after the import, the final persist and a fresh
+  // readback of every entry this run wrote have all succeeded (#4685).
+  const failures = [];
+  let result = null;
   try {
-    const result = await bridge.importFromAutoMemory();
-    success(`Imported ${result.imported} entries (${result.skipped} skipped)`);
-    dim(`├─ Backend entries: ${await backend.count()}`);
-    dim(`├─ Learning: ${config.learningBridge.enabled ? 'active' : 'disabled'}`);
-    dim(`├─ Graph: ${config.memoryGraph.enabled ? 'active' : 'disabled'}`);
-    dim(`└─ Agent scopes: ${config.agentScopes.enabled ? 'active' : 'disabled'}`);
+    result = await bridge.importFromAutoMemory();
   } catch (err) {
-    dim(`Import failed (non-critical): ${err.message}`);
+    failures.push(`import: ${err.message}`);
   }
-
-  await backend.shutdown();
+  try {
+    await backend.shutdown();
+    verifyStoreFile(STORE_PATH, backend.written, backend.deletedIds, sameRecord);
+  } catch (err) {
+    failures.push(`persist: ${err.message}`);
+  }
+  if (fileErrors.length) failures.push(`unreadable source file(s): ${fileErrors.join(', ')}`);
+  if (failures.length) throw new HookFailure(`Import failed: ${failures.join('; ')}`);
+
+  success(`Imported ${result.imported} entries (${result.skipped} skipped), verified in ${STORE_PATH}`);
+  dim(`├─ Backend entries: ${await backend.count()}`);
+  dim(`├─ Learning: ${config.learningBridge.enabled ? 'active' : 'disabled'}`);
+  dim(`├─ Graph: ${config.memoryGraph.enabled ? 'active' : 'disabled'}`);
+  dim(`└─ Agent scopes: ${config.agentScopes.enabled ? 'active' : 'disabled'}`);
 }
 
 async function doSync() {
@@ -420,6 +534,7 @@ async function doSync() {
   }
 
   const config = readConfig();
+  ensureDataDir();
   const backend = trackBackend(new JsonFileBackend(STORE_PATH));
   await backend.initialize();
 
@@ -454,6 +569,7 @@ async function doSync() {
 
   const bridge = new memPkg.AutoMemoryBridge(backend, bridgeConfig);
 
+  let syncError = null;
   try {
     const syncResult = await bridge.syncToAutoMemory();
     success(`Synced ${syncResult.synced} entries to auto memory`);
@@ -467,11 +583,12 @@ async function doSync() {
     if (indexSkipped) dim(`MEMORY.md index unchanged (${indexSkipped.reason || 'nothing to curate'})`);
     else success('Curated MEMORY.md index');
   } catch (err) {
-    dim(`Sync failed (non-critical): ${err.message}`);
+    syncError = err;
   }
 
   if (bridge.destroy) bridge.destroy();
   await backend.shutdown();
+  if (syncError) throw new HookFailure(`Sync failed: ${syncError.message}`);
 }
 
 async function doStatus() {
@@ -489,16 +606,44 @@ async function doStatus() {
   console.log(`  MemoryGraph:    ${config.memoryGraph.enabled ? '✅ Enabled' : '⏸ Disabled'}`);
   console.log(`  AgentScopes:    ${config.agentScopes.enabled ? '✅ Enabled' : '⏸ Disabled'}`);
 
-  if (existsSync(STORE_PATH)) {
-    try {
-      const data = JSON.parse(readFileSync(STORE_PATH, 'utf-8'));
-      console.log(`  Entries:        ${Array.isArray(data) ? data.length : 0}`);
-    } catch { /* ignore */ }
+  try {
+    const data = readStoreFile(STORE_PATH);
+    if (data) console.log(`  Entries:        ${data.length}`);
+  } catch (err) {
+    console.log(`  Entries:        ❌ ${err.message}`);
   }
 
   console.log('');
 }
 
+// Read-only exact lookup (#4685). It never loads the memory package, creates a
+// directory, takes the write lock or calls shutdown, so it cannot change the store.
+const READ_SCHEMA_VERSION = 1;
+async function doRead(namespace, key) {
+  const out = { schemaVersion: READ_SCHEMA_VERSION, store: STORE_PATH, storePresent: false, namespace: namespace ?? null, key: key ?? null, found: false, entry: null };
+  const refuse = (code, message) => {
+    out.error = { code, message };
+    console.log(JSON.stringify(out, null, 2));
+    return 1;
+  };
+  if (typeof namespace !== 'string' || !namespace || typeof key !== 'string' || !key) {
+    return refuse('USAGE', 'usage: auto-memory-hook.mjs read <namespace> <key>');
+  }
+  const backend = new JsonFileBackend(STORE_PATH);
+  try {
+    await backend.initialize();
+  } catch (err) {
+    out.storePresent = true; // initialize() only throws for a file that exists
+    return refuse(err.code || 'STORE_READ_FAILED', err.message);
+  }
+  out.storePresent = backend.storePresent;
+  const matches = await backend.query({ namespace, key });
+  if (matches.length > 1) return refuse('AMBIGUOUS_KEY', `${matches.length} entries share namespace ${JSON.stringify(namespace)} and key ${JSON.stringify(key)}`);
+  if (matches.length === 1) { out.found = true; out.entry = matches[0]; }
+  console.log(JSON.stringify(out, null, 2));
+  return 0;
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -506,8 +651,10 @@ async function doStatus() {
 // Older settings.json files run `node -e "…import(file)" import`, where the
 // subcommand lands in argv[1] and argv[2] is empty, so both hooks fell through
 // to `status` and never imported or synced (#4058). Accept that shape too.
-const COMMANDS = ['import', 'sync', 'status'];
+const COMMANDS = ['import', 'sync', 'status', 'read'];
+const argvBase = process.argv[2] ? 2 : 1;
 const command = process.argv[2] || (COMMANDS.includes(process.argv[1]) ? process.argv[1] : 'status');
+const commandArgs = process.argv.slice(argvBase + 1);
 
 // Dynamic import() failures can surface as unhandled rejections on a later
 // microtask even when the awaiting call site already caught them, which would
@@ -521,18 +668,25 @@ process.on('unhandledRejection', (reason) => {
   }
 });
 
+// A failed import or sync exits 1, never 2: Claude Code treats exit 2 from a
+// hook as "block", while exit 1 is a non-blocking error it shows to the user,
+// so the session carries on and the failure is no longer hidden (#4685).
+let exitCode = 0;
 try {
   switch (command) {
     case 'import': await doImport(); break;
     case 'sync': await doSync(); break;
     case 'status': await doStatus(); break;
+    case 'read': exitCode = await doRead(commandArgs[0], commandArgs[1]); break;
     default:
-      console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
+      console.log('Usage: auto-memory-hook.mjs <import|sync|status|read <namespace> <key>>');
       break;
   }
 } catch (err) {
-  // Hooks must never crash Claude Code - fail silently
-  try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
+  exitCode = 1;
+  const detail = err && err.message ? err.message : String(err);
+  const line = err instanceof HookFailure ? `[AutoMemory] ${detail}` : `[AutoMemory] ${command} failed: ${detail}`;
+  try { process.stderr.write(`${line}\n`); } catch (_) {}
 }
-// Force clean exit — process.exitCode alone isn't enough if async errors override it
-process.exit(0);
+// Force exit — process.exitCode alone isn't enough if async errors override it
+process.exit(exitCode);

package/.claude/helpers/helpers.manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest": {
-    "version": "3.71.2",
+    "version": "3.71.3",
     "files": {
-      "auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",
+      "auto-memory-hook.mjs": "1953b51e9e88330e177e5a294ec3998b5a9cd0b481ba93398a2b0f01b4088e5b",
       "hook-handler.cjs": "0ce70981aa33f76d008b6f49626effaf4269918c4094f1a28c1ef6fceb097d6f",
       "intelligence.cjs": "1d981d6c6a35d70a66450e96458e26169e0cede11523ea246a2c129c197a5b4e",
       "statusline.cjs": "d72417ecb38634011a19f095a30e07b9929e6f97663520172ece9be7491b2eaa",
@@ -10,6 +10,6 @@
       "learning-loop.cjs": "d046cd6f8efb7dd40e1d2451516c181fc8b26477aefb1124c0df5f52a23f9190"
     }
   },
-  "signature": "awy0GR0jee+KKCI+7BgzocA29zGZTAZcNYRAwp7IDQ6xwzc6Rby9hqhTnk+68AHde2YvpNpuO8AyqU/P9JDFBw==",
+  "signature": "LJPNZ7bN0gsibn3NGkh0QPxBjPtMGYX4OibxWJwGZ5XCq3LdURP2lhGe+Yr4i5fBumpBTqyOElIuVCG0kReLCQ==",
   "algorithm": "ed25519"
 }

package/.claude/settings.json

@@ -12,7 +12,8 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs\" pre-bash",
-            "timeout": 5000
+            "timeout": 5000,
+            "onFailure": "block"
           }
         ]
       }

package/README.md

@@ -36,6 +36,8 @@
 /ruflo
 ```
 
+From a terminal on Claude Code 2.1.292 or later, one command adds the marketplace and installs a plugin: `claude plugin install ruflo-core@ruflo --marketplace ruvnet/ruflo`.
+
 **Core** provides foundation tools. **Console** opens the agent cockpit. **Mods** add routing and policy enforcement inside Claude Code. Mods run with your account's permissions; review their code before installing.
 
 <img src="docs/assets/readme/icons/terminal.svg" width="28" height="28" alt=""> **Using Codex or another MCP enabled tool?** Use NPX for Ruflo project setup and connect your client to the Ruflo MCP server. Run the setup wizard in your project terminal:

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-11-04T18:54:59.719Z",
-  "gitSha": "af95dd71",
+  "generatedAt": "2026-11-05T00:20:52.796Z",
+  "gitSha": "9045ab84",
   "catalog": {
     "agents": 177,
     "tools": 450,

package/dist/src/commands/daemon.js

@@ -4,7 +4,7 @@
  */
 import { output } from '../output.js';
 import { getDaemon, startDaemon, stopDaemon, parseEnabledWorkers } from '../services/worker-daemon.js';
-import { resolveDaemonProjectRoot } from '../services/daemon-autostart.js';
+import { AUTOSTART_ENV, clearDaemonStopMarker, isDaemonStopMarked, resolveDaemonProjectRoot, writeDaemonStopMarker, } from '../services/daemon-autostart.js';
 import { fork } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
@@ -72,6 +72,19 @@ const startCommand = {
         const projectRoot = resolveWorkspaceFlag(ctx.flags.workspace)
             ?? resolveDaemonProjectRoot(process.cwd());
         const isDaemonProcess = process.env.CLAUDE_FLOW_DAEMON === '1';
+        // #4654: an explicit start re-enables auto-start after `daemon stop`. The
+        // start that auto-start spawned must not clear it, and must re-check it:
+        // a `daemon stop` may have landed after the hook checked, and starting
+        // anyway would bring back the daemon the user just stopped.
+        if (!isDaemonProcess) {
+            if (process.env[AUTOSTART_ENV] === '1') {
+                if (isDaemonStopMarked(projectRoot))
+                    return { success: true };
+            }
+            else {
+                clearDaemonStopMarker(projectRoot);
+            }
+        }
         // Parse resource threshold overrides from CLI flags
         const config = {};
         // #2661: thread --headless into DaemonConfig so it actually gates the
@@ -649,6 +662,9 @@ const stopCommand = {
         // Git worktrees. Only processes positively identified as ruflo daemons
         // (via their self-identifying argv) are touched; each receives SIGTERM
         // so its own shutdown path reaps in-flight Claude process groups.
+        // #4654: record the opt-out first, so a hook firing mid-stop cannot
+        // auto-start a fresh daemon. Cleared only by an explicit `daemon start`.
+        writeDaemonStopMarker(projectRoot);
         if (ctx.flags.all) {
             return stopAllDaemons(quiet);
         }
@@ -716,6 +732,9 @@ async function stopAllDaemons(quiet) {
             else {
                 process.kill(d.pid, 'SIGTERM');
             }
+            // #4654: keep each stopped workspace stopped until an explicit start.
+            if (d.workspace)
+                writeDaemonStopMarker(d.workspace);
             stopped++;
             if (!quiet) {
                 output.printInfo(`Stopping daemon PID ${d.pid}${d.workspace ? ` (${d.workspace})` : ''}`);

package/dist/src/commands/hive-mind-worker.d.ts

@@ -44,6 +44,16 @@ export declare function currentRufloServer(): {
     command: string;
     args: string[];
 };
+/**
+ * The model for a spawned Claude, from `--model` (#1870). With no `--model`
+ * nothing is passed and Claude Code picks its own default. The value becomes
+ * its own argv token, so one starting with "-" would be read by Claude as a
+ * flag and is refused.
+ */
+export declare function resolveWorkerModel(flags: Record<string, unknown>): {
+    model?: string;
+    error?: string;
+};
 export interface RunOutcome {
     ok: boolean;
     output: string;

package/dist/src/commands/hive-mind-worker.js

@@ -88,6 +88,26 @@ export function currentRufloServer() {
         ? { command: process.execPath, args: [entry, 'mcp', 'start'] }
         : { command: 'npx', args: ['-y', '@claude-flow/cli@latest', 'mcp', 'start'] };
 }
+const WORKER_MODEL = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$/;
+/**
+ * The model for a spawned Claude, from `--model` (#1870). With no `--model`
+ * nothing is passed and Claude Code picks its own default. The value becomes
+ * its own argv token, so one starting with "-" would be read by Claude as a
+ * flag and is refused.
+ */
+export function resolveWorkerModel(flags) {
+    const raw = flags.model;
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        return { error: '--model needs a value, e.g. --model sonnet' };
+    }
+    const model = raw.trim();
+    if (!WORKER_MODEL.test(model)) {
+        return { error: `--model "${model}" is not a valid model name or id` };
+    }
+    return { model };
+}
 /** Run one prompt through `claude -p` and parse its JSON result. */
 export const runWithClaude = (prompt, opts) => new Promise((resolve) => {
     const started = Date.now();

package/dist/src/commands/hive-mind.js

@@ -10,7 +10,7 @@ import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { spawn as childSpawn } from 'child_process';
 import { mkdir, writeFile } from 'fs/promises';
-import { resolveWorkerMcpConfig, currentRufloServer, workCommand } from './hive-mind-worker.js';
+import { resolveWorkerMcpConfig, resolveWorkerModel, currentRufloServer, workCommand } from './hive-mind-worker.js';
 import { join } from 'path';
 import { resolveClaudeLaunchCommand } from '../runtime/claude-command.js';
 import { withHeadlessPlugins } from '../mods/headless-plugins.js';
@@ -168,6 +168,7 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
         const workerGroups = groupWorkersByType(workers);
         const hiveMindPrompt = generateHiveMindPrompt(swarmId, swarmName, objective, workers, workerGroups, flags);
         spinner.succeed('Hive Mind coordination prompt ready!');
+        const { model: workerModel } = resolveWorkerModel(flags);
         // Display coordination summary
         output.writeln();
         output.writeln(output.bold('🧠 Hive Mind Configuration'));
@@ -179,6 +180,7 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
             `Worker Count: ${output.highlight(String(workers.length))}`,
             `Worker Types: ${output.highlight(Object.keys(workerGroups).join(', '))}`,
             `Consensus: ${output.highlight(flags.consensus || 'byzantine')}`,
+            `Model: ${output.highlight(workerModel ?? 'Claude Code default')}`,
             `MCP Tools: ${output.success('Full Claude-Flow integration enabled')}`
         ]);
         // Ensure sessions directory exists
@@ -249,6 +251,10 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
                     output.printWarning('Using --dangerously-skip-permissions for seamless hive-mind execution');
                 }
             }
+            // #1870: without --model the argv is unchanged and Claude Code picks its default.
+            if (workerModel) {
+                claudeArgs.push('--model', workerModel);
+            }
             // ADR-510 §2.2: a non-interactive (-p) run is a headless worker and loads
             // no marketplace plugins on a fresh config, so stage the worker profile
             // (default ruflo-mods) as --plugin-dir before the prompt. The interactive
@@ -344,11 +350,12 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
             output.writeln();
             output.writeln(output.bold('📋 Manual Execution Instructions:'));
             output.writeln(output.dim('─'.repeat(50)));
+            const modelArg = workerModel ? ` --model ${workerModel}` : '';
             output.printList([
                 'Install Claude Code: npm install -g @anthropic-ai/claude-code',
-                `Run with saved prompt: claude < ${promptFile}`,
-                `Or copy manually: cat ${promptFile} | claude`,
-                `With auto-permissions: claude --dangerously-skip-permissions < ${promptFile}`
+                `Run with saved prompt: claude${modelArg} < ${promptFile}`,
+                `Or copy manually: cat ${promptFile} | claude${modelArg}`,
+                `With auto-permissions: claude${modelArg} --dangerously-skip-permissions < ${promptFile}`
             ]);
             return { success: true, promptFile };
         }
@@ -529,6 +536,12 @@ const spawnCommand = {
             description: 'Objective for the hive mind (used with --claude)',
             type: 'string'
         },
+        {
+            name: 'model',
+            short: 'm',
+            description: 'Model for the Claude Code worker started by --claude, passed as claude --model (e.g. sonnet, opus, or a full model id; default: the Claude Code default)',
+            type: 'string'
+        },
         {
             name: 'dangerously-skip-permissions',
             description: 'Skip permission prompts in Claude Code (use with caution)',
@@ -564,6 +577,7 @@ const spawnCommand = {
         { command: 'claude-flow hive-mind spawn -n 3 -r specialist', description: 'Spawn 3 specialists' },
         { command: 'claude-flow hive-mind spawn -t coder -p my-coder', description: 'Spawn coder with custom prefix' },
         { command: 'claude-flow hive-mind spawn --claude -o "Build a REST API"', description: 'Launch Claude Code with objective' },
+        { command: 'claude-flow hive-mind spawn --claude -m sonnet -o "Build a REST API"', description: 'Launch Claude Code on a pinned model' },
         { command: 'claude-flow hive-mind spawn -n 5 --claude -o "Research AI patterns"', description: 'Spawn workers and launch Claude Code' }
     ],
     action: async (ctx) => {
@@ -574,6 +588,15 @@ const spawnCommand = {
         const prefix = ctx.flags.prefix || 'hive-worker';
         const launchClaude = ctx.flags.claude;
         let objective = ctx.flags.objective || ctx.args.join(' ');
+        // #1870: refuse a bad --model before any worker is spawned.
+        const workerModel = resolveWorkerModel(ctx.flags);
+        if (workerModel.error) {
+            output.printError(workerModel.error);
+            return { success: false, exitCode: 1 };
+        }
+        if (workerModel.model && !launchClaude) {
+            output.printWarning('--model only applies with --claude; ignoring it');
+        }
         output.printInfo(`Spawning ${count} ${role} agent(s)...`);
         try {
             const result = await callMCPTool('hive-mind_spawn', {

package/dist/src/init/settings-generator.js

@@ -210,6 +210,10 @@ function generateHooksConfig(config, scope) {
                         type: 'command',
                         command: hookHandlerCmd('pre-bash', scope),
                         timeout: config.timeout,
+                        // Claude Code 2.1.295+: if the safety gate can't start, times out or
+                        // exits with an unexpected code, block the command instead of letting
+                        // it run. Older versions ignore the key.
+                        onFailure: 'block',
                     },
                 ],
             },