claude-flow 3.7.0-alpha.4 → 3.7.0-alpha.41

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

@@ -82,7 +82,7 @@ function saveMetrics(metrics) {
 export const systemTools = [
     {
         name: 'system_status',
-        description: 'Get overall system status',
+        description: 'Get overall system status Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -123,7 +123,7 @@ export const systemTools = [
     },
     {
         name: 'system_metrics',
-        description: 'Get system metrics and performance data',
+        description: 'Get system metrics and performance data Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -277,7 +277,7 @@ export const systemTools = [
     },
     {
         name: 'system_health',
-        description: 'Perform system health check',
+        description: 'Perform system health check Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -291,13 +291,21 @@ export const systemTools = [
             const metrics = loadMetrics();
             const checks = [];
             const projectCwd = getProjectCwd();
-            // Memory DB check — verify any supported store file exists
+            // Memory DB check — verify any supported store file exists.
+            // #1843: cover sql.js / HNSW / .swarm and root-level rvf/db paths,
+            // not just the legacy `.claude-flow/memory/*` triple.
             {
                 const t0 = performance.now();
-                const legacyPath = join(projectCwd, '.claude-flow', 'memory', 'store.json');
-                const agentDbPath = join(projectCwd, '.claude-flow', 'memory', 'agentdb.sqlite');
-                const rvfPath = join(projectCwd, '.claude-flow', 'memory', 'store.rvf');
-                const memoryExists = existsSync(legacyPath) || existsSync(agentDbPath) || existsSync(rvfPath);
+                const memoryCandidates = [
+                    join(projectCwd, '.claude-flow', 'memory', 'store.json'), // legacy
+                    join(projectCwd, '.claude-flow', 'memory', 'agentdb.sqlite'),
+                    join(projectCwd, '.claude-flow', 'memory', 'store.rvf'),
+                    join(projectCwd, '.claude-flow', 'memory', 'claude-flow.db'), // sql.js
+                    join(projectCwd, '.swarm', 'memory.db'), // swarm
+                    join(projectCwd, 'ruvector.db'), // ruvector
+                    join(projectCwd, 'agentdb.rvf'), // root rvf
+                ];
+                const memoryExists = memoryCandidates.some(existsSync);
                 const elapsed = performance.now() - t0;
                 checks.push({
                     name: 'memory',
@@ -306,12 +314,21 @@ export const systemTools = [
                     message: memoryExists ? undefined : 'Memory store not found — run memory init',
                 });
             }
-            // Config check — verify config file exists
+            // Config check — verify config file exists.
+            // #1843: also accept YAML config (.claude-flow/config.yaml) which
+            // the rest of v3 treats as canonical; previous code only counted
+            // .json variants and reported `degraded` when YAML was used.
             {
                 const t0 = performance.now();
-                const configPath = join(projectCwd, '.claude-flow', 'config.json');
-                const altConfigPath = join(projectCwd, 'claude-flow.config.json');
-                const configExists = existsSync(configPath) || existsSync(altConfigPath);
+                const configCandidates = [
+                    join(projectCwd, '.claude-flow', 'config.json'),
+                    join(projectCwd, '.claude-flow', 'config.yaml'),
+                    join(projectCwd, '.claude-flow', 'config.yml'),
+                    join(projectCwd, 'claude-flow.config.json'),
+                    join(projectCwd, 'claude-flow.config.yaml'),
+                    join(projectCwd, 'claude-flow.config.yml'),
+                ];
+                const configExists = configCandidates.some(existsSync);
                 const elapsed = performance.now() - t0;
                 checks.push({
                     name: 'config',
@@ -410,9 +427,16 @@ export const systemTools = [
                     });
                 }
             }
+            // #1843: exclude `unknown` checks from the health score denominator.
+            // Previously a check reporting `unknown` (e.g. swarm/neural which
+            // can't be probed in-process) was counted as a non-healthy hit and
+            // dragged the score below 100 even when every actionable check was
+            // green. Treat `unknown` as advisory and surface it separately.
             const healthy = checks.filter(c => c.status === 'healthy').length;
+            const advisory = checks.filter(c => c.status === 'unknown').length;
             const total = checks.length;
-            const overallHealth = healthy / total;
+            const scoreDenominator = total - advisory;
+            const overallHealth = scoreDenominator > 0 ? healthy / scoreDenominator : 1;
             // Update metrics
             metrics.health = overallHealth;
             saveMetrics(metrics);
@@ -421,9 +445,10 @@ export const systemTools = [
                 score: Math.round(overallHealth * 100),
                 checks,
                 healthy,
+                advisory,
                 total,
                 timestamp: new Date().toISOString(),
-                issues: checks.filter(c => c.status !== 'healthy').map(c => ({
+                issues: checks.filter(c => c.status !== 'healthy' && c.status !== 'unknown').map(c => ({
                     component: c.name,
                     status: c.status,
                     suggestion: `Check ${c.name} component configuration`,
@@ -433,7 +458,7 @@ export const systemTools = [
     },
     {
         name: 'system_info',
-        description: 'Get system information',
+        description: 'Get system information Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -468,7 +493,7 @@ export const systemTools = [
     },
     {
         name: 'system_reset',
-        description: 'Reset system state',
+        description: 'Reset system state Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -511,7 +536,7 @@ export const systemTools = [
     },
     {
         name: 'mcp_status',
-        description: 'Get MCP server status, including stdio mode detection',
+        description: 'Get MCP server status, including stdio mode detection Use when native Claude Code MCP status is wrong because you need Ruflo-side server detail — tool counts per namespace, transport stats, MCP handshake errors. For just "is MCP up?", `claude mcp list` is fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -568,7 +593,7 @@ export const systemTools = [
     },
     {
         name: 'task_summary',
-        description: 'Get a summary of all tasks by status',
+        description: 'Get a summary of all tasks by status Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -597,5 +622,53 @@ export const systemTools = [
             };
         },
     },
+    {
+        // #1916: `ruflo start` referenced an unregistered `mcp_start` tool. MCP
+        // tools run *in-process* via the CLI's TOOL_REGISTRY — there is no
+        // separate server process to spawn from inside an MCP call. If this tool
+        // responds, MCP is already up. (`ruflo mcp start` runs a standalone
+        // stdio/HTTP server; that's a process command, not an MCP tool.)
+        name: 'mcp_start',
+        description: 'Report that the in-process MCP toolset is available (no-op "start" — if this tool responds, MCP is up). Use when native `claude mcp list` is wrong because you want Ruflo-side confirmation that the in-process registry loaded. For a standalone stdio/HTTP MCP server, run `ruflo mcp start` (a process command, not this tool). Pair with mcp_status for detail.',
+        category: 'system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                port: { type: 'number', description: 'Port (advisory — in-process MCP has no port)' },
+                transport: { type: 'string', description: 'Transport (advisory)' },
+                tools: { type: 'array', items: { type: 'string' }, description: 'Tool namespaces (advisory — all are loaded)' },
+            },
+        },
+        handler: async (input) => {
+            const isStdio = !process.stdin.isTTY;
+            return {
+                serverId: `in-process-${process.pid}`,
+                port: typeof input.port === 'number' ? input.port : (parseInt(process.env.CLAUDE_FLOW_MCP_PORT || '0', 10) || null),
+                transport: input.transport || process.env.CLAUDE_FLOW_MCP_TRANSPORT || (isStdio ? 'stdio' : 'in-process'),
+                startedAt: new Date().toISOString(),
+                note: 'MCP tools run in-process via the CLI; no separate server process was started. Use `ruflo mcp start` for a standalone server.',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo stop` referenced an unregistered `mcp_stop` tool. Same
+        // story as mcp_start — nothing to stop for the in-process registry.
+        name: 'mcp_stop',
+        description: 'No-op "stop" for the in-process MCP toolset (there is no separate server process to stop from inside an MCP call). Use when native process-kill is wrong because you mistakenly think Ruflo runs a daemon — it does not, the tools live in the CLI process. To stop a standalone server run `ruflo mcp stop` or terminate that process. Pair with mcp_status.',
+        category: 'system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                graceful: { type: 'boolean', description: 'Advisory (no-op)' },
+                timeout: { type: 'number', description: 'Advisory (no-op)' },
+            },
+        },
+        handler: async () => {
+            return {
+                stopped: false,
+                note: 'no separate MCP server process; nothing to stop. The in-process toolset goes away when the CLI process exits. Use `ruflo mcp stop` for a standalone server.',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=system-tools.js.map

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

@@ -43,7 +43,7 @@ function saveTaskStore(store) {
 export const taskTools = [
     {
         name: 'task_create',
-        description: 'Create a new task',
+        description: 'Create a new task Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -95,7 +95,7 @@ export const taskTools = [
     },
     {
         name: 'task_status',
-        description: 'Get task status',
+        description: 'Get task status Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -137,7 +137,7 @@ export const taskTools = [
     },
     {
         name: 'task_list',
-        description: 'List all tasks',
+        description: 'List all tasks Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -195,7 +195,7 @@ export const taskTools = [
     },
     {
         name: 'task_complete',
-        description: 'Mark task as complete',
+        description: 'Mark task as complete Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -257,7 +257,7 @@ export const taskTools = [
     },
     {
         name: 'task_update',
-        description: 'Update task status or progress',
+        description: 'Update task status or progress Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -309,7 +309,7 @@ export const taskTools = [
     },
     {
         name: 'task_assign',
-        description: 'Assign a task to one or more agents',
+        description: 'Assign a task to one or more agents Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -393,7 +393,7 @@ export const taskTools = [
     },
     {
         name: 'task_cancel',
-        description: 'Cancel a task',
+        description: 'Cancel a task Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -435,5 +435,53 @@ export const taskTools = [
             };
         },
     },
+    {
+        // #1916: the `ruflo task retry <id>` CLI subcommand referenced an
+        // unregistered `task_retry` tool. Re-queues a finished/cancelled task by
+        // cloning its spec into a fresh pending task (the original is left intact
+        // as history).
+        name: 'task_retry',
+        description: 'Re-queue a failed/cancelled/completed task by cloning its spec into a fresh pending task (the original record is kept as history). Use when native TodoWrite is wrong because you need the original task\'s persisted spec (type, priority, assignees, tags) and a stable taskId chain across runs rather than hand-retyping a checklist item. For ad-hoc re-runs, native TodoWrite is fine.',
+        category: 'task',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskId: { type: 'string', description: 'ID of the task to retry' },
+                resetState: { type: 'boolean', description: 'Reset progress/result on the new task (default true)' },
+            },
+            required: ['taskId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.taskId, 'taskId');
+            if (!v.valid)
+                return { success: false, error: v.error };
+            const store = loadTaskStore();
+            const taskId = input.taskId;
+            const original = store.tasks[taskId];
+            if (!original)
+                return { success: false, taskId, error: 'Task not found' };
+            const newTaskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            store.tasks[newTaskId] = {
+                taskId: newTaskId,
+                type: original.type,
+                description: original.description,
+                priority: original.priority,
+                status: 'pending',
+                progress: 0,
+                assignedTo: [...original.assignedTo],
+                tags: [...original.tags, 'retry-of:' + taskId],
+                createdAt: new Date().toISOString(),
+                startedAt: null,
+                completedAt: null,
+            };
+            saveTaskStore(store);
+            return {
+                taskId,
+                newTaskId,
+                previousStatus: original.status,
+                status: 'pending',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=task-tools.js.map

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

@@ -52,7 +52,7 @@ function saveTerminalStore(store) {
 export const terminalTools = [
     {
         name: 'terminal_create',
-        description: 'Create a new terminal session',
+        description: 'Create a new terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -106,7 +106,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_execute',
-        description: 'Execute a command in a terminal session',
+        description: 'Execute a command in a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -193,7 +193,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_list',
-        description: 'List all terminal sessions',
+        description: 'List all terminal sessions Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -226,7 +226,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_close',
-        description: 'Close a terminal session',
+        description: 'Close a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -258,7 +258,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_history',
-        description: 'Get command history for a terminal session',
+        description: 'Get command history for a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',

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

@@ -29,7 +29,7 @@ export const transferTools = [
     // ═══════════════════════════════════════════════════════════════
     {
         name: 'transfer_detect-pii',
-        description: 'Detect PII in content without redacting',
+        description: 'Detect PII in content without redacting Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -63,7 +63,7 @@ export const transferTools = [
     // ═══════════════════════════════════════════════════════════════
     {
         name: 'transfer_ipfs-resolve',
-        description: 'Resolve IPNS name to CID',
+        description: 'Resolve IPNS name to CID Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -97,7 +97,7 @@ export const transferTools = [
     // ═══════════════════════════════════════════════════════════════
     {
         name: 'transfer_store-search',
-        description: 'Search the pattern store',
+        description: 'Search the pattern store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -150,7 +150,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_store-info',
-        description: 'Get detailed info about a pattern',
+        description: 'Get detailed info about a pattern Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -186,7 +186,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_store-download',
-        description: 'Download a pattern from the store',
+        description: 'Download a pattern from the store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -223,7 +223,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_store-featured',
-        description: 'Get featured patterns from the store',
+        description: 'Get featured patterns from the store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -251,7 +251,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_store-trending',
-        description: 'Get trending patterns from the store',
+        description: 'Get trending patterns from the store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -282,7 +282,7 @@ export const transferTools = [
     // ═══════════════════════════════════════════════════════════════
     {
         name: 'transfer_plugin-search',
-        description: 'Search the plugin store',
+        description: 'Search the plugin store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -348,7 +348,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_plugin-info',
-        description: 'Get detailed info about a plugin',
+        description: 'Get detailed info about a plugin Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -388,7 +388,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_plugin-featured',
-        description: 'Get featured plugins from the store',
+        description: 'Get featured plugins from the store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -419,7 +419,7 @@ export const transferTools = [
     },
     {
         name: 'transfer_plugin-official',
-        description: 'Get official plugins from the store',
+        description: 'Get official plugins from the store Use when native package install (`npm i`, `pip install`) is wrong because the artifact lives on IPFS (plugins, witness chains, learned patterns). For npm-registry deps, native npm is fine.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {

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

@@ -12,12 +12,12 @@ async function loadAgentWasm() {
 export const wasmAgentTools = [
     {
         name: 'wasm_agent_create',
-        description: 'Create a sandboxed WASM agent with virtual filesystem (no OS access). Optionally use a gallery template.',
+        description: 'Create a sandboxed WASM agent with virtual filesystem (no OS access). Optionally use a gallery template. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
                 template: { type: 'string', description: 'Gallery template name (coder, researcher, tester, reviewer, security, swarm)' },
-                model: { type: 'string', description: 'Model identifier (default: anthropic:claude-sonnet-4-20250514)' },
+                model: { type: 'string', description: 'Model identifier (default: anthropic:claude-sonnet-4-6)' },
                 instructions: { type: 'string', description: 'System instructions for the agent' },
                 maxTurns: { type: 'number', description: 'Max conversation turns (default: 50)' },
             },
@@ -58,7 +58,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_prompt',
-        description: 'Send a prompt to a WASM agent and get a response.',
+        description: 'Send a prompt to a WASM agent and get a response. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -90,7 +90,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_tool',
-        description: 'Execute a tool on a WASM agent sandbox. Tools: read_file, write_file, edit_file, write_todos, list_files. Use flat format: {tool, path, content, ...}.',
+        description: 'Execute a tool on a WASM agent sandbox. Tools: read_file, write_file, edit_file, write_todos, list_files. Use flat format: {tool, path, content, ...}. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -128,7 +128,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_list',
-        description: 'List all active WASM agents.',
+        description: 'List all active WASM agents. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
             try {
@@ -143,7 +143,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_terminate',
-        description: 'Terminate a WASM agent and free resources.',
+        description: 'Terminate a WASM agent and free resources. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -169,7 +169,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_files',
-        description: 'Get a WASM agent\'s available tools and info.',
+        description: 'Get a WASM agent\'s available tools and info. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -196,7 +196,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_agent_export',
-        description: 'Export a WASM agent\'s full state (config, filesystem, conversation) as JSON.',
+        description: 'Export a WASM agent\'s full state (config, filesystem, conversation) as JSON. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -222,7 +222,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_gallery_list',
-        description: 'List all available WASM agent gallery templates (Coder, Researcher, Tester, Reviewer, Security, Swarm).',
+        description: 'List all available WASM agent gallery templates (Coder, Researcher, Tester, Reviewer, Security, Swarm). Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
             try {
@@ -237,7 +237,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_gallery_search',
-        description: 'Search WASM agent gallery templates by query.',
+        description: 'Search WASM agent gallery templates by query. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -263,7 +263,7 @@ export const wasmAgentTools = [
     },
     {
         name: 'wasm_gallery_create',
-        description: 'Create a WASM agent from a gallery template.',
+        description: 'Create a WASM agent from a gallery template. Use when native Task is wrong because the workload needs sandboxed isolation — untrusted code execution, browser-side run, deterministic replay. Pair with wasm_gallery_search to find a published agent, or wasm_agent_create to scaffold a fresh one. For trusted in-process work, native Task is fine.',
         inputSchema: {
             type: 'object',
             properties: {