@claude-flow/cli 3.57.2 → 3.58.0

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

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.57.2",
+    "version": "3.58.0",
     "files": {
       "auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",
       "hook-handler.cjs": "bc12b3cae92d5a7c8deef699fa00d0ef07b57625c18dbeac4387f15725b8e09f",
@@ -9,6 +9,6 @@
       "router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"
     }
   },
-  "signature": "1NC9a0vJ78KCh8TIZfhExMq0923sXMkAej7Dxg4hlTqmOBzS1Gn9ex7z1lpkCTOlVafXVVXXMsEa1BSdsvQ7CQ==",
+  "signature": "xqclyZcKpZly9uW8nOyUEwAcR+R/7JlzjHdKXYJ5I2lWeBWYWogZZjrijQEQMGSNvN61cVs3Xtyob91K7mxIBQ==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -240,6 +240,7 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
 | [**ruflo-browser**](plugins/ruflo-browser/README.md) | Automate browser testing with Playwright |
 | [**ruflo-jujutsu**](plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |
 | [**ruflo-docs**](plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |
+| [**agentic-qe-fleet**](https://github.com/proffesor-for-testing/agentic-qe/tree/v3.15.10/plugins/agentic-qe-fleet) | External, maintained by [Agentic QE](https://github.com/proffesor-for-testing/agentic-qe): 11 QE agents, test generation, coverage, chaos and TDD skills, the `agentic-qe` MCP server, and a guard for AQE learning data (`/plugin install agentic-qe-fleet@ruflo`). Install it from one marketplace only, `agentic-qe` or `ruflo`: enabled from both, its mod and commands load twice |
 
 #### Security & Compliance
 

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-19T23:34:04.095Z",
-  "gitSha": "7be330bc",
+  "generatedAt": "2026-10-20T06:14:05.915Z",
+  "gitSha": "d529a38a",
   "catalog": {
     "agents": 176,
     "tools": 423,

package/dist/src/commands/agent.js

@@ -136,6 +136,7 @@ const spawnCommand = {
             const result = await callMCPTool('agent_spawn', {
                 agentType,
                 id: agentName,
+                name: agentName,
                 config: {
                     provider: ctx.flags.provider || 'anthropic',
                     model: ctx.flags.model,
@@ -214,7 +215,9 @@ const listCommand = {
         try {
             // Call MCP tool to list agents
             const result = await callMCPTool('agent_list', {
-                status: ctx.flags.all ? 'all' : ctx.flags.status || undefined,
+                // agent_list has no 'all' status: --all means "don't hide terminated agents".
+                status: ctx.flags.status || undefined,
+                includeTerminated: ctx.flags.all ? true : undefined,
                 agentType: ctx.flags.type || undefined,
                 limit: 100,
             });

package/dist/src/commands/mcp.js

@@ -34,6 +34,14 @@ function formatUptime(seconds) {
     const mins = Math.floor((seconds % 3600) / 60);
     return `${hours}h ${mins}m`;
 }
+function readIntegerOption(flags, name, envName) {
+    const camelName = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const input = flags[camelName] ?? flags[name] ?? process.env[envName];
+    return input === undefined ? undefined : Number(input);
+}
+function isOutOfRange(value, min, max) {
+    return value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max);
+}
 // Start MCP server
 const startCommand = {
     name: 'start',
@@ -71,6 +79,31 @@ const startCommand = {
             description: 'HTTP request timeout in milliseconds (default 30000; env RUFLO_MCP_REQUEST_TIMEOUT_MS)',
             type: 'number'
         },
+        {
+            name: 'rate-limit-per-ip',
+            description: 'HTTP requests allowed per client IP per window (env RUFLO_MCP_RATE_LIMIT_PER_IP)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-window-ms',
+            description: 'HTTP rate limit window in milliseconds (env RUFLO_MCP_RATE_LIMIT_WINDOW_MS)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-per-session',
+            description: 'Request burst allowed per MCP session, refilled over 10s; also bounded by the server-wide bucket (env RUFLO_MCP_RATE_LIMIT_PER_SESSION)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-global-rps',
+            description: 'Server-wide requests per second across all sessions (env RUFLO_MCP_RATE_LIMIT_GLOBAL_RPS)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-global-burst',
+            description: 'Server-wide request burst across all sessions (env RUFLO_MCP_RATE_LIMIT_GLOBAL_BURST)',
+            type: 'number'
+        },
         {
             name: 'auth-token-file',
             description: 'Read the HTTP bearer token from this file (http transport). Preferred over --auth-token; env RUFLO_MCP_HTTP_TOKEN also works',
@@ -100,6 +133,7 @@ const startCommand = {
         { command: 'claude-flow mcp start', description: 'Start with defaults (stdio)' },
         { command: 'claude-flow mcp start -p 8080 -t http', description: 'Start HTTP server' },
         { command: 'claude-flow mcp start -t http --request-timeout-ms 120000', description: 'Allow slower cold-start HTTP tools' },
+        { command: 'claude-flow mcp start -t http --rate-limit-per-ip 600 --rate-limit-per-session 500 --rate-limit-global-burst 1000', description: 'Raise rate limits for a shared control plane' },
         { command: 'RUFLO_MCP_HTTP_TOKEN=<16+ chars> claude-flow mcp start -t http', description: 'HTTP server requiring "Authorization: Bearer <token>" on every request (except GET /health)' },
         { command: 'RUFLO_MCP_HTTP_TOKEN=<16+ chars> claude-flow mcp start -t http --host 0.0.0.0', description: 'Non-loopback bind: allowed only with a token (or RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1)' },
         { command: 'claude-flow mcp start -d', description: 'Start as daemon' },
@@ -112,15 +146,36 @@ const startCommand = {
         const tools = ctx.flags.tools
             || process.env.CLAUDE_FLOW_MCP_TOOLS
             || 'all';
-        const timeoutInput = ctx.flags.requestTimeoutMs
-            ?? ctx.flags['request-timeout-ms']
-            ?? process.env.RUFLO_MCP_REQUEST_TIMEOUT_MS;
-        const requestTimeoutMs = timeoutInput === undefined ? undefined : Number(timeoutInput);
-        if (requestTimeoutMs !== undefined &&
-            (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > 3_600_000)) {
+        const requestTimeoutMs = readIntegerOption(ctx.flags, 'request-timeout-ms', 'RUFLO_MCP_REQUEST_TIMEOUT_MS');
+        if (isOutOfRange(requestTimeoutMs, 1, 3_600_000)) {
             output.printError('Request timeout must be an integer from 1 to 3600000 milliseconds');
             return { success: false, exitCode: 1 };
         }
+        const rateLimitPerIp = readIntegerOption(ctx.flags, 'rate-limit-per-ip', 'RUFLO_MCP_RATE_LIMIT_PER_IP');
+        if (isOutOfRange(rateLimitPerIp, 1, 100_000)) {
+            output.printError('HTTP rate limit must be an integer from 1 to 100000 requests per window');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitWindowMs = readIntegerOption(ctx.flags, 'rate-limit-window-ms', 'RUFLO_MCP_RATE_LIMIT_WINDOW_MS');
+        if (isOutOfRange(rateLimitWindowMs, 1000, 3_600_000)) {
+            output.printError('Rate limit window must be an integer from 1000 to 3600000 milliseconds');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitPerSession = readIntegerOption(ctx.flags, 'rate-limit-per-session', 'RUFLO_MCP_RATE_LIMIT_PER_SESSION');
+        if (isOutOfRange(rateLimitPerSession, 1, 10_000)) {
+            output.printError('Session rate limit must be an integer from 1 to 10000 requests');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitGlobalRps = readIntegerOption(ctx.flags, 'rate-limit-global-rps', 'RUFLO_MCP_RATE_LIMIT_GLOBAL_RPS');
+        if (isOutOfRange(rateLimitGlobalRps, 1, 10_000)) {
+            output.printError('Global rate limit must be an integer from 1 to 10000 requests per second');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitGlobalBurst = readIntegerOption(ctx.flags, 'rate-limit-global-burst', 'RUFLO_MCP_RATE_LIMIT_GLOBAL_BURST');
+        if (isOutOfRange(rateLimitGlobalBurst, 1, 20_000)) {
+            output.printError('Global rate limit burst must be an integer from 1 to 20000 requests');
+            return { success: false, exitCode: 1 };
+        }
         let authToken;
         try {
             authToken = resolveMcpHttpAuthToken({
@@ -189,6 +244,11 @@ const startCommand = {
             port,
             tools: !tools || tools === 'all' ? 'all' : tools.split(','),
             ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+            ...(rateLimitPerIp === undefined ? {} : { rateLimitPerIp }),
+            ...(rateLimitWindowMs === undefined ? {} : { rateLimitWindowMs }),
+            ...(rateLimitPerSession === undefined ? {} : { rateLimitPerSession }),
+            ...(rateLimitGlobalRps === undefined ? {} : { rateLimitGlobalRps }),
+            ...(rateLimitGlobalBurst === undefined ? {} : { rateLimitGlobalBurst }),
             ...(authToken ? { authToken } : {}),
             daemonize: daemon,
         };

package/dist/src/commands/memory.js

@@ -16,6 +16,7 @@ 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';
+import { memoryPeek } from '../memory/memory-peek.js';
 /**
  * #3228: a miss in one store is not a miss in the memory.
  *
@@ -1223,6 +1224,54 @@ const statsCommand = {
         }
     }
 };
+// #3508: read-only route/peek — which store files this cwd resolves to,
+// their row counts and last write, without creating or initializing
+// anything. Unlike `stats`, this never calls into the MCP tool layer (no
+// `authorizeMcpTool` receipt, no `ensureInitialized()`): it reads both
+// files directly, in-process, read-only.
+const peekCommand = {
+    name: 'peek',
+    description: 'Report which memory store files this cwd resolves to, their row counts and last write — read-only, creates nothing',
+    options: [DB_PATH_OPTION],
+    action: async (ctx) => {
+        try {
+            const result = await memoryPeek({ path: ctx.flags.path });
+            if (ctx.flags.format === 'json') {
+                output.printJson(result);
+                return { success: true, data: result };
+            }
+            output.writeln();
+            output.writeln(output.bold('Memory Peek'));
+            output.writeln();
+            output.writeln(`cwd: ${result.cwd}`);
+            output.writeln(`root: ${result.root.path} (source: ${result.root.source})`);
+            output.writeln();
+            output.printTable({
+                columns: [
+                    { key: 'role', header: 'Role', width: 6 },
+                    { key: 'path', header: 'Path', width: 40 },
+                    { key: 'exists', header: 'Exists', width: 8 },
+                    { key: 'rows', header: 'Rows', width: 8, align: 'right' },
+                    { key: 'lastWrite', header: 'Last Write', width: 24 },
+                ],
+                data: result.stores.map((store) => ({
+                    role: store.role,
+                    path: store.path,
+                    exists: store.exists ? 'yes' : 'no',
+                    rows: store.encrypted ? 'encrypted' : (store.rows === null ? 'unknown' : String(store.rows)),
+                    lastWrite: store.lastWrite ?? 'N/A',
+                })),
+            });
+            output.writeln();
+            output.writeln(`Shared keys (same namespace+key in both stores): ${result.sharedKeys === null ? 'unknown' : result.sharedKeys}`);
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`Failed to peek: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return { success: false, exitCode: 1 };
+        }
+    }
+};
 // Configure command
 const configureCommand = {
     name: 'configure',
@@ -2038,12 +2087,13 @@ const classifyCommand = {
 export const memoryCommand = {
     name: 'memory',
     description: 'Memory management commands',
-    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand, selectOperatorCommand],
+    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, peekCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand, selectOperatorCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
         { command: 'claude-flow memory search -q "auth patterns"', description: 'Search memory' },
-        { command: 'claude-flow memory stats', description: 'Show statistics' }
+        { command: 'claude-flow memory stats', description: 'Show statistics' },
+        { command: 'claude-flow memory peek', description: 'Read-only: which store files this cwd resolves to, rows, last write' }
     ],
     action: async (ctx) => {
         output.writeln();
@@ -2060,6 +2110,7 @@ export const memoryCommand = {
             `${output.highlight('list')}       - List memory entries`,
             `${output.highlight('delete')}     - Delete memory entry`,
             `${output.highlight('stats')}      - Show statistics`,
+            `${output.highlight('peek')}       - Read-only: resolved store files, rows, last write (creates nothing)`,
             `${output.highlight('configure')}  - Configure backend`,
             `${output.highlight('cleanup')}    - Clean expired entries`,
             `${output.highlight('compress')}   - Compress database`,

package/dist/src/mcp-server.d.ts

@@ -30,6 +30,11 @@ export interface MCPServerOptions {
     daemonize?: boolean;
     timeout?: number;
     requestTimeoutMs?: number;
+    rateLimitPerIp?: number;
+    rateLimitWindowMs?: number;
+    rateLimitPerSession?: number;
+    rateLimitGlobalRps?: number;
+    rateLimitGlobalBurst?: number;
     /**
      * Bearer token every HTTP request must present (`Authorization: Bearer <token>`).
      * http transport only. Prefer RUFLO_MCP_HTTP_TOKEN / a token file over this

package/dist/src/mcp-server.js

@@ -103,6 +103,10 @@ function processStartToken(pid) {
         return undefined;
     }
 }
+function definedFields(fields) {
+    const entries = Object.entries(fields).filter(([, value]) => value !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
 /**
  * Hosts treated as same-machine-only for MCP HTTP tool-call authorization
  * purposes (see startHttpServer's non-loopback authorization gate below).
@@ -134,6 +138,26 @@ export function isUnauthenticatedHttpAllowed(env = process.env) {
 export function shouldRefuseUnauthenticatedHttp(host, env = process.env, authenticated = false) {
     return !isLoopbackHost(host) && !authenticated && !isUnauthenticatedHttpAllowed(env);
 }
+/** The limits @claude-flow/mcp applies when a rate limit option is unset. */
+const DEFAULT_RATE_LIMITS = {
+    rateLimitPerIp: 120,
+    rateLimitPerSession: 50,
+    rateLimitGlobalRps: 100,
+    rateLimitGlobalBurst: 200,
+};
+const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+/**
+ * Rate limit options that are looser than the @claude-flow/mcp defaults. A
+ * shorter window counts as looser.
+ */
+function raisedRateLimits(options) {
+    const raised = Object.keys(DEFAULT_RATE_LIMITS)
+        .filter((name) => (options[name] ?? 0) > DEFAULT_RATE_LIMITS[name]);
+    if ((options.rateLimitWindowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS) < DEFAULT_RATE_LIMIT_WINDOW_MS) {
+        raised.push('rateLimitWindowMs');
+    }
+    return raised;
+}
 /** Printable ASCII without space (RFC 6750 token-ish), 16-512 chars. */
 const AUTH_TOKEN_PATTERN = /^[\x21-\x7e]{16,512}$/;
 /**
@@ -822,6 +846,15 @@ export class MCPServerManager extends EventEmitter {
                 'RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 to acknowledge the risk and proceed ' +
                 '(e.g. when a trusted reverse proxy or network boundary already enforces auth).');
         }
+        const raised = raisedRateLimits(this.options);
+        if (raised.length > 0 && !isLoopbackHost(this.options.host) && !authToken) {
+            // RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 lets an open server start, but
+            // anyone who can reach it should not also get more than the default
+            // request budget.
+            throw new Error(`Refusing to raise MCP rate limits (${raised.join(', ')}) above the defaults on non-loopback ` +
+                `host "${this.options.host}" without a bearer token. Set RUFLO_MCP_HTTP_TOKEN (or ` +
+                '--auth-token-file), or bind to a loopback host (127.0.0.1, ::1, or localhost).');
+        }
         // Dynamically import the MCP server package
         // FIX for issue #942: Use proper package import instead of broken relative path
         const { createMCPServer } = await import('@claude-flow/mcp');
@@ -867,6 +900,12 @@ export class MCPServerManager extends EventEmitter {
             enableMetrics: true,
             enableCaching: true,
             requestTimeout: this.options.requestTimeoutMs,
+            rateLimit: definedFields({ windowMs: this.options.rateLimitWindowMs, limit: this.options.rateLimitPerIp }),
+            sessionRateLimit: definedFields({
+                requestsPerSecond: this.options.rateLimitGlobalRps,
+                burstSize: this.options.rateLimitGlobalBurst,
+                perSessionLimit: this.options.rateLimitPerSession,
+            }),
             auth: authToken
                 ? { enabled: true, method: 'token', tokens: [authToken] }
                 : undefined,

package/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/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;