claude-flow 3.57.2 → 3.58.1

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

@@ -216,6 +216,7 @@ export const agentTools = [
             properties: {
                 agentType: { type: 'string', description: 'Type of agent to spawn' },
                 agentId: { type: 'string', description: 'Optional custom agent ID' },
+                name: { type: 'string', description: 'Optional display name for the agent (shown by agent_list, agent_status and ruflo-console)' },
                 // #2085 — accept swarmId so spawned agents register in the
                 // swarm.agents array that swarm_status reports. Omit to register
                 // with the most-recently-created swarm.
@@ -241,6 +242,18 @@ export const agentTools = [
             }
             const agentId = input.agentId || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
             const agentType = input.agentType;
+            // #4300 — older callers (including `agent spawn` before this fix) send
+            // the name only as metadata.name.
+            const metadata = input.metadata;
+            const rawName = input.name ?? metadata?.name;
+            let name;
+            if (rawName !== undefined && rawName !== '') {
+                const vName = validateText(rawName, 'name', 200);
+                if (!vName.valid) {
+                    return { success: false, error: `Input validation failed: ${vName.error}` };
+                }
+                name = vName.sanitized;
+            }
             const config = input.config || {};
             // Add explicit model to config if provided
             if (input.model) {
@@ -262,6 +275,7 @@ export const agentTools = [
             const agent = {
                 agentId,
                 agentType,
+                ...(name ? { name } : {}),
                 status: 'idle',
                 health: 1.0,
                 taskCount: 0,
@@ -347,6 +361,7 @@ export const agentTools = [
                 success: true,
                 agentId,
                 agentType: agent.agentType,
+                ...(agent.name ? { name: agent.name } : {}),
                 model: agent.model,
                 modelRoutedBy: routingResult.routedBy,
                 ...(routingResult.modelId ? { modelId: routingResult.modelId } : {}),
@@ -501,6 +516,7 @@ export const agentTools = [
                 return {
                     agentId: agent.agentId,
                     agentType: agent.agentType,
+                    ...(agent.name ? { name: agent.name } : {}),
                     status: agent.status,
                     health: agent.health,
                     taskCount: agent.taskCount,
@@ -525,6 +541,7 @@ export const agentTools = [
             properties: {
                 status: { type: 'string', description: 'Filter by status' },
                 domain: { type: 'string', description: 'Filter by domain' },
+                agentType: { type: 'string', description: 'Filter by agent type' },
                 includeTerminated: { type: 'boolean', description: 'Include terminated agents' },
             },
         },
@@ -539,6 +556,11 @@ export const agentTools = [
                 if (!v.valid)
                     return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
             }
+            if (input.agentType) {
+                const v = validateIdentifier(input.agentType, 'agentType');
+                if (!v.valid)
+                    return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+            }
             let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
             // Filter by status
             if (input.status) {
@@ -551,10 +573,15 @@ export const agentTools = [
             if (input.domain) {
                 agents = agents.filter(a => a.domain === input.domain);
             }
+            // Filter by agent type
+            if (input.agentType) {
+                agents = agents.filter(a => a.agentType === input.agentType);
+            }
             return {
                 agents: agents.map(a => ({
                     agentId: a.agentId,
                     agentType: a.agentType,
+                    ...(a.name ? { name: a.name } : {}),
                     status: a.status,
                     health: a.health,
                     taskCount: a.taskCount,
@@ -565,6 +592,7 @@ export const agentTools = [
                 filters: {
                     status: input.status,
                     domain: input.domain,
+                    agentType: input.agentType,
                     includeTerminated: input.includeTerminated,
                 },
             };

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

@@ -13,6 +13,7 @@ import { existsSync, writeFileSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
 const CLAIMS_DIR = '.claude-flow/claims';
 const CLAIMS_FILE = 'claims.json';
+const DEFAULT_MAX_CLAIMS = 5;
 function getClaimsPath() {
     return resolve(join(CLAIMS_DIR, CLAIMS_FILE));
 }
@@ -47,7 +48,7 @@ function parseClaimant(str) {
 export const claimsTools = [
     {
         name: 'claims_claim',
-        description: 'Claim an issue for work (human or agent) Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Claim an issue for work (human or agent). Use when multiple agents might pick up the same issue — claiming makes ownership visible via claims_list before work starts.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -64,6 +65,10 @@ export const claimsTools = [
                     type: 'string',
                     description: 'Optional context about the work approach',
                 },
+                ttlMs: {
+                    type: 'number',
+                    description: 'Optional time-to-live in milliseconds; when set, the claim records an expiresAt timestamp. Informational only today — no handler currently enforces it (e.g. claims_steal still requires claims_mark-stealable rather than checking expiry).',
+                },
             },
             required: ['issueId', 'claimant'],
         },
@@ -71,6 +76,7 @@ export const claimsTools = [
             const issueId = input.issueId;
             const claimantStr = input.claimant;
             const context = input.context;
+            const ttlMs = input.ttlMs;
             {
                 const v = validateIdentifier(issueId, 'issueId');
                 if (!v.valid)
@@ -86,6 +92,9 @@ export const claimsTools = [
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
+            if (ttlMs !== undefined && (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0)) {
+                return { success: false, error: 'ttlMs must be a positive number' };
+            }
             const claimant = parseClaimant(claimantStr);
             if (!claimant) {
                 return { success: false, error: 'Invalid claimant format. Use "human:userId:name" or "agent:agentId:agentType"' };
@@ -109,6 +118,7 @@ export const claimsTools = [
                 statusChangedAt: now,
                 progress: 0,
                 context,
+                expiresAt: ttlMs !== undefined ? new Date(Date.now() + ttlMs).toISOString() : undefined,
             };
             store.claims[issueId] = claim;
             saveClaims(store);
@@ -121,7 +131,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_release',
-        description: 'Release a claim on an issue Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Release a claim on an issue. Use when the claimant stops working on it, freeing it for another claims_claim instead of leaving it claimed indefinitely.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -186,7 +196,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_handoff',
-        description: 'Request handoff of an issue to another claimant Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Request handoff of an issue to another claimant. Use when transferring in-progress work to a different agent, instead of releasing and having them claim it fresh.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -270,7 +280,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_accept-handoff',
-        description: 'Accept a pending handoff Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Accept a pending handoff. Use when the receiving claimant confirms a claims_handoff request, completing the ownership transfer.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -333,7 +343,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_status',
-        description: 'Update claim status Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Update claim status. Use when progress changes (active, blocked, review-requested, etc.) so claims_list and claims_load reflect current state.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -398,7 +408,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_list',
-        description: 'List all claims or filter by criteria Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'List all claims or filter by criteria. Use when checking what is already claimed before starting new work, instead of guessing from issue comments.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -453,7 +463,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_mark-stealable',
-        description: 'Mark an issue as stealable by other agents Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Mark an issue as stealable by other agents. Use when a claimant is overloaded or stalled and wants another agent to pick it up via claims_steal.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -521,7 +531,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_steal',
-        description: 'Steal a stealable issue Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Steal a stealable issue. Use when picking up work already marked stealable via claims_mark-stealable, rather than claiming an issue someone else still owns.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -592,7 +602,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_stealable',
-        description: 'List all stealable issues Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'List all stealable issues. Use when looking for available work that has been freed up via claims_mark-stealable.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -628,7 +638,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_load',
-        description: 'Get agent load information Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Get agent load information. Use when deciding which agent should take new work by comparing claim counts against claims_rebalance targets.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -689,8 +699,8 @@ export const claimsTools = [
                 agentId: l.agentId,
                 agentType: l.agentType,
                 claimCount: l.claims.length,
-                maxClaims: 5, // Default max
-                utilization: l.claims.length / 5,
+                maxClaims: DEFAULT_MAX_CLAIMS,
+                utilization: l.claims.length / DEFAULT_MAX_CLAIMS,
                 blockedCount: l.blockedCount,
                 claims: l.claims.map(c => ({
                     issueId: c.issueId,
@@ -711,7 +721,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_board',
-        description: 'Get a visual board view of all claims Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Get a visual board view of all claims. Use when scanning overall claim status across issues and agents instead of composing the view from claims_list yourself.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -760,7 +770,7 @@ export const claimsTools = [
     },
     {
         name: 'claims_rebalance',
-        description: 'Suggest or apply load rebalancing across agents Use when nothing native covers per-agent capability gating — Claude Code agents have file-system access by default. Pair claims_grant + claims_check before letting an agent run privileged ops. For trusted in-session work, no claims call is needed.',
+        description: 'Suggest or apply load rebalancing across agents. Use when some agents are overloaded and others idle, instead of manually reassigning claims one at a time.',
         category: 'claims',
         inputSchema: {
             type: 'object',
@@ -794,7 +804,7 @@ export const claimsTools = [
                 agentLoads.get(key).claims.push(claim);
             }
             const loads = Array.from(agentLoads.values());
-            const maxClaims = 5;
+            const maxClaims = DEFAULT_MAX_CLAIMS;
             const avgLoad = loads.length > 0
                 ? loads.reduce((sum, l) => sum + l.claims.length, 0) / loads.length
                 : 0;

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

@@ -5,7 +5,7 @@ import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feed
  */
 import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync, unlinkSync, readdirSync } from 'fs';
 import * as nodeFs from 'fs';
-import { dirname, join, resolve } from 'path';
+import { dirname, join, resolve, sep } from 'path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validatePath } from './validate-input.js';
 import { commandRecordingDisabled, redactCommandForStorage } from '../services/command-recording.js';
@@ -5136,7 +5136,17 @@ export const hooksCodemod = {
                 if (!v.valid)
                     return v.error;
                 const abs = resolve(cwd, v.sanitized);
-                if (!abs.startsWith(cwd))
+                // Anchor containment at a path-separator boundary — an unanchored
+                // `abs.startsWith(cwd)` string-prefix check would let an absolute
+                // path like `${cwd}-staging/x.ts` pass as "inside" `cwd`. Matches
+                // the pattern already used correctly elsewhere in this codebase
+                // (@claude-flow/security's `isWithinPrefix`, hooks/workers, plugins/security).
+                // KNOWN LIMITATION (disclosed 2026-10-20, not fixed here): this
+                // compares the resolved-but-not-realpath'd path, so a symlink
+                // inside cwd pointing outside it still escapes containment
+                // (CWE-59, a distinct/broader gap than the CWE-22 prefix bug this
+                // anchors). Needs fs.realpathSync-based containment as a follow-up.
+                if (abs !== cwd && !abs.startsWith(cwd + sep))
                     return `path escapes project root: ${p}`;
                 out.add(abs);
                 return undefined;
@@ -5169,7 +5179,7 @@ export const hooksCodemod = {
                 }
                 for (const m of matches) {
                     const abs = resolve(cwd, m);
-                    if (abs.startsWith(cwd) && CODEMOD_EXTENSIONS.has(abs.slice(abs.lastIndexOf('.')).toLowerCase())) {
+                    if ((abs === cwd || abs.startsWith(cwd + sep)) && CODEMOD_EXTENSIONS.has(abs.slice(abs.lastIndexOf('.')).toLowerCase())) {
                         out.add(abs);
                     }
                 }

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

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 import { readFileMaybeEncrypted, writeDbImagePreservingFormat, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
 import { validateIdentifier } from '../mcp-tools/validate-input.js';
+import { resolveModelCacheDir } from './model-cache-dir.js';
 /**
  * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
  * entry (a user's stated claim vs an agent's own output vs a tool result vs
@@ -2009,6 +2010,8 @@ export async function applyTemporalDecay(dbPath) {
         };
     }
 }
+/** ADR-454: minimum interval before a 'retryable' degraded state re-attempts real init. */
+const MODEL_INIT_RETRY_INTERVAL_MS = 60_000;
 /**
  * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
  * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
@@ -2058,8 +2061,15 @@ export async function loadEmbeddingModel(options) {
  */
 async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()) {
     if (embeddingModelState?.loaded) {
-        return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        const isRetryableDue = embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS;
+        if (!isRetryableDue) {
+            return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        }
+        // Fall through to re-attempt real initialization — the retryable
+        // failure (e.g. EACCES on the model cache dir) may now be fixed.
     }
+    let sawRetryableFailure = false;
     try {
         // ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
         // critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2068,6 +2078,7 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         // @claude-flow/embeddings/src/transformers-loader.ts.
         let transformersSource = null;
         let pipelineFn = null;
+        let transformersModule = null;
         {
             const tryLoad = async (specifier) => {
                 try {
@@ -2081,12 +2092,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
             if (hf && typeof hf.pipeline === 'function') {
                 pipelineFn = hf.pipeline;
                 transformersSource = '@huggingface/transformers';
+                transformersModule = hf;
             }
             else {
                 const xen = await tryLoad('@xenova/transformers');
                 if (xen && typeof xen.pipeline === 'function') {
                     pipelineFn = xen.pipeline;
                     transformersSource = '@xenova/transformers';
+                    transformersModule = xen;
                 }
             }
         }
@@ -2103,6 +2116,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 if (verbose) {
                     console.log(`Loading ONNX embedding model via ${transformersSource} (all-MiniLM-L6-v2)...`);
                 }
+                // ADR-454: route model downloads to a user-writable cache dir —
+                // the package-relative default is root-owned under a system-prefix
+                // global install, which throws EACCES for the runtime user.
+                const cacheDir = resolveModelCacheDir();
+                fs.mkdirSync(cacheDir, { recursive: true });
+                const env = transformersModule?.env;
+                if (env)
+                    env.cacheDir = cacheDir;
                 const embedder = await pipelineFn('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
                 embeddingModelState = {
                     loaded: true,
@@ -2118,6 +2139,10 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 };
             }
             catch (err) {
+                // ADR-454: a real backend was importable and callable — this failure
+                // (EACCES, ENOSPC, transient network error, etc.) is environmental,
+                // not a missing dependency, so it must not be memoized permanently.
+                sawRetryableFailure = true;
                 if (verbose) {
                     console.warn(`${transformersSource} pipeline init failed (${err instanceof Error ? err.message : String(err)}); ` +
                         'falling through to ruvector ONNX / agentic-flow / hash fallback.');
@@ -2186,12 +2211,18 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         }
         // No agentic-flow root-entry fallback: no published root exports
         // `embeddings`, and importing it runs its CLI main() in 3.0.0-alpha.x.
-        // No ONNX model available - use fallback
+        // No ONNX model available - use fallback.
+        // ADR-454: mark whether this is a permanent (no backend importable at
+        // all) or retryable (a backend existed but init failed for an
+        // environmental reason) degraded state, so a later call can re-attempt
+        // real initialization once the condition is fixed.
         embeddingModelState = {
             loaded: true,
             model: null, // Will use simple hash-based fallback
             tokenizer: null,
-            dimensions: 128 // Smaller fallback dimensions
+            dimensions: 128, // Smaller fallback dimensions
+            degradedReason: sawRetryableFailure ? 'retryable' : 'permanent',
+            lastAttemptAt: Date.now()
         };
         return {
             success: true,
@@ -2257,7 +2288,15 @@ export async function generateLocalEmbedding(text) {
     // loadEmbeddingModel(), which is bridge-first — when the bridge answered
     // there, no local model was ever loaded and this function always returned
     // the hash fallback.
-    if (!embeddingModelState?.loaded) {
+    //
+    // ADR-454: also re-attempt when the memoized state is a 'retryable'
+    // degraded fallback whose retry interval has elapsed — otherwise this
+    // guard short-circuits past loadLocalEmbeddingChain()'s own retry check
+    // and the fix (e.g. a now-writable cache dir) never gets exercised.
+    const shouldRetryLoad = !embeddingModelState?.loaded ||
+        (embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS);
+    if (shouldRetryLoad) {
         await loadLocalEmbeddingChain();
     }
     // #2461: loadEmbeddingModel() can leave embeddingModelState null when an

package/v3/@claude-flow/cli/dist/src/memory/memory-peek.d.ts

@@ -0,0 +1,28 @@
+export type MemoryRootSource = 'path' | 'CLAUDE_FLOW_DB_PATH' | 'CLAUDE_FLOW_MEMORY_PATH' | 'config' | 'default';
+export interface MemoryPeekStore {
+    role: 'cli' | 'mcp';
+    path: string;
+    exists: boolean;
+    rows: number | null;
+    lastWrite: string | null;
+    sizeBytes: number | null;
+    walBytes: number | null;
+    encrypted?: boolean;
+}
+export interface MemoryPeekResult {
+    cwd: string;
+    root: {
+        path: string;
+        source: MemoryRootSource;
+    };
+    stores: MemoryPeekStore[];
+    sharedKeys: number | null;
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export declare function memoryPeek(opts?: {
+    path?: string;
+}): Promise<MemoryPeekResult>;
+//# sourceMappingURL=memory-peek.d.ts.map