@claudetools/tools 0.8.4 → 0.8.5

package/dist/handlers/tool-handlers.js

@@ -11,8 +11,8 @@ import { recordToolCall, getToolCallWarnings } from '../helpers/session-validati
 import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
 import { checkPatterns } from '../helpers/patterns.js';
 import { formatContextForClaude } from '../helpers/formatter.js';
-import { compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactSummary, } from '../helpers/compact-formatter.js';
-import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getActiveTaskCount, } from '../helpers/tasks.js';
+import { shortId, compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactTaskHandoff, compactSummary, } from '../helpers/compact-formatter.js';
+import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, handoffTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getEpicAggregate, getActiveTaskCount, reviseEpic, } from '../helpers/tasks.js';
 import { detectTimedOutTasks, retryTask, failTask, autoRetryTimedOutTasks, } from '../helpers/tasks-retry.js';
 import { detectLibrariesFromPlan } from '../helpers/library-detection.js';
 import { handleGenerateApi, handleGenerateFrontend, handleGenerateComponent, handleListGenerators, handleValidateSpec, handleListPatterns, handleGetPattern, handleDetectPatterns, handleInitProject, } from './codedna-handlers.js';
@@ -827,6 +827,73 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_plan_revise': {
+                    const epicId = args?.epic_id;
+                    const addTasks = args?.add_tasks;
+                    const removeTaskIds = args?.remove_task_ids;
+                    const updateTasks = args?.update_tasks;
+                    try {
+                        const result = await reviseEpic(DEFAULT_USER_ID, projectId, epicId, {
+                            add_tasks: addTasks,
+                            remove_task_ids: removeTaskIds,
+                            update_tasks: updateTasks,
+                        });
+                        mcpLogger.toolResult(name, true, timer(), `Epic ${shortId(epicId)} revised: +${result.added.length} tasks, -${result.removed.length} tasks, ~${result.updated.length} tasks`);
+                        let output = `# Epic Revised: ${result.epic.title}\n\n`;
+                        output += `**Epic ID:** \`${result.epic.id}\`\n`;
+                        output += `**Status:** ${result.epic.status}\n\n`;
+                        if (result.added.length > 0) {
+                            output += `## Added Tasks (${result.added.length})\n\n`;
+                            result.added.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`)`;
+                                if (task.estimated_effort)
+                                    output += ` - ${task.estimated_effort}`;
+                                output += `\n`;
+                                if (task.description)
+                                    output += `   ${task.description}\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.removed.length > 0) {
+                            output += `## Cancelled Tasks (${result.removed.length})\n\n`;
+                            result.removed.forEach((taskId, i) => {
+                                output += `${i + 1}. \`${shortId(taskId)}\` (cancelled)\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.updated.length > 0) {
+                            output += `## Updated Tasks (${result.updated.length})\n\n`;
+                            result.updated.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`) - Context added with update details\n`;
+                            });
+                            output += '\n';
+                        }
+                        // Get updated epic status
+                        const epicStatus = await getEpicStatus(DEFAULT_USER_ID, projectId, epicId);
+                        output += `## Current Status\n\n`;
+                        output += `**Total Tasks:** ${epicStatus.totalTasks}\n`;
+                        output += `**Progress:** ${epicStatus.percentComplete}% complete\n`;
+                        output += `**By Status:**\n`;
+                        Object.entries(epicStatus.byStatus).forEach(([status, count]) => {
+                            if (count > 0) {
+                                output += `- ${status}: ${count}\n`;
+                            }
+                        });
+                        return {
+                            content: [{ type: 'text', text: output }],
+                        };
+                    }
+                    catch (error) {
+                        mcpLogger.toolResult(name, false, timer(), error instanceof Error ? error.message : 'Unknown error');
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Error revising epic: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                                }],
+                            isError: true,
+                        };
+                    }
+                }
                 case 'task_start': {
                     const taskId = args?.task_id;
                     const agentId = args?.agent_id || 'claude-code';
@@ -1048,6 +1115,19 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_handoff': {
+                    const taskId = args?.task_id;
+                    const newWorkerType = args?.new_worker_type;
+                    const reason = args?.reason;
+                    const agentId = args?.agent_id || 'claude-code';
+                    const result = await handoffTask(DEFAULT_USER_ID, projectId, taskId, agentId, newWorkerType, reason);
+                    mcpLogger.toolResult(name, true, timer());
+                    // Compact output
+                    const output = compactTaskHandoff(result.data.task, result.data.handed_off, result.data.new_worker_type);
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 // =========================================================================
                 // ORCHESTRATION HANDLERS
                 // =========================================================================
@@ -1100,7 +1180,12 @@ export function registerToolHandlers(server) {
                     output += `**Task:** ${context.task.title}\n`;
                     output += `**Task ID:** \`${context.task.id}\`\n`;
                     output += `**Worker Type:** ${context.worker.name} (\`${context.worker.id}\`)\n`;
-                    output += `**Status:** ${context.task.status}\n\n`;
+                    output += `**Status:** ${context.task.status}\n`;
+                    // Display lock expiry warning if present
+                    if (context.lockWarning?.warning && context.lockWarning.message) {
+                        output += `\n${context.lockWarning.message}\n`;
+                    }
+                    output += `\n`;
                     output += `## System Prompt for Worker\n\n`;
                     output += `\`\`\`\n${context.systemPrompt}\`\`\`\n\n`;
                     if (context.parentTask) {
@@ -1224,6 +1309,47 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_aggregate': {
+                    const epicId = args?.epic_id;
+                    const includePending = args?.include_pending || false;
+                    const aggregate = await getEpicAggregate(DEFAULT_USER_ID, projectId, epicId, includePending);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Epic Aggregate: ${aggregate.epic.title}\n\n`;
+                    output += `**Epic ID:** \`${epicId}\`\n`;
+                    output += `**Epic Status:** ${aggregate.epic.status}\n`;
+                    output += `**Description:** ${aggregate.epic.description}\n\n`;
+                    output += `## Summary Statistics\n\n`;
+                    output += `- **Total Tasks:** ${aggregate.summary_stats.total}\n`;
+                    output += `- **Completed:** ${aggregate.summary_stats.completed}\n`;
+                    output += `- **In Progress:** ${aggregate.summary_stats.in_progress}\n`;
+                    output += `- **Pending:** ${aggregate.summary_stats.pending}\n\n`;
+                    output += `## Task Work Logs\n\n`;
+                    if (aggregate.tasks.length === 0) {
+                        output += `No tasks ${includePending ? '' : 'with work logs '}found for this epic.\n`;
+                    }
+                    else {
+                        for (const task of aggregate.tasks) {
+                            const statusEmoji = task.status === 'done' ? '✅' : task.status === 'in_progress' ? '🔄' : '📋';
+                            output += `### ${statusEmoji} ${task.title}\n`;
+                            output += `- **Task ID:** \`${task.id}\`\n`;
+                            output += `- **Status:** ${task.status}\n`;
+                            if (task.completed_at) {
+                                const completedDate = new Date(task.completed_at).toLocaleString();
+                                output += `- **Completed:** ${completedDate}\n`;
+                            }
+                            if (task.work_log) {
+                                output += `- **Work Log:**\n\n`;
+                                output += `  ${task.work_log}\n\n`;
+                            }
+                            else {
+                                output += `- **Work Log:** None\n\n`;
+                            }
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 case 'task_detect_timeouts': {
                     const timedOut = await detectTimedOutTasks(DEFAULT_USER_ID, projectId);
                     mcpLogger.toolResult(name, true, timer());
@@ -1278,6 +1404,10 @@ export function registerToolHandlers(server) {
                         if (result.error?.includes('Retry limit exceeded')) {
                             output += `The task has been marked as **failed** permanently.\n`;
                         }
+                        else if (result.retryAfter) {
+                            output += `**Retry After:** ${result.retryAfter}\n`;
+                            output += `The task is in exponential backoff. Please wait before retrying.\n`;
+                        }
                     }
                     return {
                         content: [{ type: 'text', text: output }],

package/dist/helpers/circuit-breaker.d.ts

@@ -0,0 +1,28 @@
+export interface CircuitState {
+    failures: number;
+    lastFailure: number;
+    openedAt: number | null;
+}
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export declare function recordWorkerFailure(workerType: string): void;
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export declare function isCircuitOpen(workerType: string): boolean;
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export declare function getCircuitStatus(): Map<string, CircuitState>;
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export declare function resetCircuit(workerType: string): void;
+/**
+ * Reset all circuits (for testing)
+ */
+export declare function resetAllCircuits(): void;

package/dist/helpers/circuit-breaker.js

@@ -0,0 +1,97 @@
+// =============================================================================
+// Circuit Breaker for Worker Failure Tracking
+// =============================================================================
+//
+// Implements the circuit breaker pattern to prevent dispatching tasks to
+// failing workers. Tracks failures per worker type and opens circuit after
+// threshold is reached. Circuit auto-closes after cooldown period.
+//
+// Circuit States:
+// - CLOSED: Normal operation, tasks dispatched
+// - OPEN: Too many failures, tasks NOT dispatched to this worker type
+// - HALF_OPEN: Cooldown complete, attempting recovery (not implemented yet)
+//
+// Configuration
+const FAILURE_THRESHOLD = 3; // Open circuit after N failures
+const FAILURE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes window for counting failures
+const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes cooldown before auto-close
+// In-memory circuit state (per worker type)
+const circuits = new Map();
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export function recordWorkerFailure(workerType) {
+    const now = Date.now();
+    const state = circuits.get(workerType) || {
+        failures: 0,
+        lastFailure: 0,
+        openedAt: null,
+    };
+    // If circuit is already open, don't count new failures
+    if (state.openedAt !== null) {
+        return;
+    }
+    // Check if last failure was outside the window
+    if (now - state.lastFailure > FAILURE_WINDOW_MS) {
+        // Reset failure count (new window)
+        state.failures = 1;
+    }
+    else {
+        // Within window, increment
+        state.failures++;
+    }
+    state.lastFailure = now;
+    // Check if we should open the circuit
+    if (state.failures >= FAILURE_THRESHOLD) {
+        state.openedAt = now;
+        console.warn(`[Circuit Breaker] OPENED for worker type: ${workerType} (${state.failures} failures)`);
+    }
+    circuits.set(workerType, state);
+}
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export function isCircuitOpen(workerType) {
+    const state = circuits.get(workerType);
+    // No failures recorded = closed
+    if (!state || state.openedAt === null) {
+        return false;
+    }
+    const now = Date.now();
+    const timeSinceOpened = now - state.openedAt;
+    // Check if cooldown has elapsed
+    if (timeSinceOpened >= COOLDOWN_MS) {
+        // Auto-close circuit
+        state.openedAt = null;
+        state.failures = 0;
+        circuits.set(workerType, state);
+        console.info(`[Circuit Breaker] AUTO-CLOSED for worker type: ${workerType} (cooldown elapsed)`);
+        return false;
+    }
+    // Still in cooldown
+    return true;
+}
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export function getCircuitStatus() {
+    // Return a copy of the current state
+    return new Map(circuits);
+}
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export function resetCircuit(workerType) {
+    circuits.delete(workerType);
+    console.info(`[Circuit Breaker] RESET for worker type: ${workerType}`);
+}
+/**
+ * Reset all circuits (for testing)
+ */
+export function resetAllCircuits() {
+    circuits.clear();
+    console.info('[Circuit Breaker] RESET ALL circuits');
+}

package/dist/helpers/compact-formatter.d.ts

@@ -49,3 +49,5 @@ export declare function compactMemoryIndex(entries: {
     relevance: number;
     is_critical?: boolean;
 }[]): string;
+/** Compact task handoff */
+export declare function compactTaskHandoff(task: Task, handedOff: boolean, newWorkerType: string): string;

package/dist/helpers/compact-formatter.js

@@ -128,3 +128,9 @@ export function compactMemoryIndex(entries) {
         return `${i + 1}. ${critical}${e.summary.slice(0, 60)} (${rel}%) [${shortId(e.id)}]`;
     }).join('\n');
 }
+/** Compact task handoff */
+export function compactTaskHandoff(task, handedOff, newWorkerType) {
+    if (!handedOff)
+        return `❌ Failed to hand off: ${task.title}`;
+    return `🔄 Handed off: ${task.title} → ${newWorkerType} (ready for re-dispatch)`;
+}

package/dist/helpers/tasks-retry.d.ts

@@ -7,12 +7,19 @@ export interface TimedOutTask {
 export interface RetryMetadata {
     retryCount: number;
     lastFailedAt: string;
+    lastRetryAt?: string;
     lastError?: string;
     failureHistory: Array<{
         timestamp: string;
         error?: string;
     }>;
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export declare function calculateBackoffDelay(retryCount: number): number;
 /**
  * Detect tasks that have timed out (lock expired while in_progress)
  * These are likely abandoned or failed tasks
@@ -28,8 +35,10 @@ export declare function retryTask(userId: string, projectId: string, taskId: str
         task: Task;
         retryCount: number;
         retriesRemaining: number;
+        retryAfter?: string;
     };
     error?: string;
+    retryAfter?: string;
 }>;
 /**
  * Mark a task as failed with context

package/dist/helpers/tasks-retry.js

@@ -11,10 +11,22 @@ function getRetryMetadata(task) {
     return {
         retryCount: metadata.retryCount || 0,
         lastFailedAt: metadata.lastFailedAt || '',
+        lastRetryAt: metadata.lastRetryAt,
         lastError: metadata.lastError,
         failureHistory: metadata.failureHistory || [],
     };
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export function calculateBackoffDelay(retryCount) {
+    const baseDelay = 1000; // 1 second
+    const maxDelay = 300000; // 5 minutes
+    const delay = baseDelay * Math.pow(2, retryCount);
+    return Math.min(delay, maxDelay);
+}
 /**
  * Update retry metadata
  */
@@ -27,6 +39,7 @@ function updateRetryMetadata(metadata, error) {
         ...metadata,
         retryCount,
         lastFailedAt: timestamp,
+        lastRetryAt: timestamp,
         lastError: error,
         failureHistory: [
             ...failureHistory,
@@ -90,6 +103,23 @@ export async function retryTask(userId, projectId, taskId, maxRetries = 3, error
             error: `Retry limit exceeded (${maxRetries} retries)`,
         };
     }
+    // Check exponential backoff window
+    if (retryMetadata.lastRetryAt && retryMetadata.retryCount > 0) {
+        const lastRetryTime = new Date(retryMetadata.lastRetryAt);
+        const now = new Date();
+        const timeSinceLastRetry = now.getTime() - lastRetryTime.getTime();
+        const backoffDelay = calculateBackoffDelay(retryMetadata.retryCount);
+        if (timeSinceLastRetry < backoffDelay) {
+            const remainingBackoff = backoffDelay - timeSinceLastRetry;
+            const retryAfterTime = new Date(now.getTime() + remainingBackoff);
+            const retryAfter = retryAfterTime.toISOString();
+            return {
+                success: false,
+                error: `Task is in backoff window. Please wait ${Math.ceil(remainingBackoff / 1000)} seconds before retrying.`,
+                retryAfter,
+            };
+        }
+    }
     // Update metadata with failure info
     const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
     // Update task with retry metadata and reset status

package/dist/helpers/tasks.d.ts

@@ -127,15 +127,30 @@ export declare function heartbeatTask(userId: string, projectId: string, taskId:
         new_expires_at: string;
     };
 }>;
-export declare const DEFAULT_MAX_PARALLEL = 5;
+export declare const EFFORT_WEIGHTS: {
+    readonly xs: 1;
+    readonly s: 2;
+    readonly m: 4;
+    readonly l: 8;
+    readonly xl: 16;
+};
+export declare const LOCK_DURATION_BY_EFFORT: {
+    readonly xs: 15;
+    readonly s: 30;
+    readonly m: 60;
+    readonly l: 120;
+    readonly xl: 240;
+};
+export declare const DEFAULT_CAPACITY_BUDGET = 20;
 /**
- * Get count of currently active tasks
- * Returns both in_progress and claimed (locked) task counts
+ * Get effort-weighted load of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts, plus effort-weighted load
  */
 export declare function getActiveTaskCount(userId: string, projectId: string, epicId?: string): Promise<{
     inProgress: number;
     claimed: number;
     total: number;
+    effortLoad: number;
 }>;
 /**
  * Get all tasks ready for parallel dispatch
@@ -143,9 +158,17 @@ export declare function getActiveTaskCount(userId: string, projectId: string, ep
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
- * - Respects max parallel limit by considering currently active tasks
+ * - Respects effort-weighted capacity budget
  */
-export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
+export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, capacityBudget?: number): Promise<DispatchableTask[]>;
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export declare function getLockExpiryWarning(lockExpiresAt: string | null): {
+    warning: boolean;
+    minutes_remaining: number;
+    message?: string;
+};
 /**
  * Get full execution context for a worker agent
  */
@@ -156,11 +179,41 @@ export declare function getExecutionContext(userId: string, projectId: string, t
     context: TaskContext[];
     parentTask?: Task;
     siblingTasks?: Task[];
+    lockWarning?: {
+        warning: boolean;
+        minutes_remaining: number;
+        message?: string;
+    };
 }>;
 /**
  * Find newly unblocked tasks after a completion and update their status to ready
  */
 export declare function resolveTaskDependencies(userId: string, projectId: string, completedTaskId: string, epicId?: string): Promise<Task[]>;
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export declare function getEpicAggregate(userId: string, projectId: string, epicId: string, includePending?: boolean): Promise<{
+    epic: {
+        id: string;
+        title: string;
+        description: string;
+        status: string;
+    };
+    tasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+        work_log: string | null;
+        completed_at: string | null;
+    }>;
+    summary_stats: {
+        total: number;
+        completed: number;
+        in_progress: number;
+        pending: number;
+    };
+}>;
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -173,3 +226,36 @@ export declare function getEpicStatus(userId: string, projectId: string, epicId:
     allComplete: boolean;
     autoCompleted: boolean;
 }>;
+export declare function handoffTask(userId: string, projectId: string, taskId: string, agentId: string, newWorkerType: string, reason: string): Promise<{
+    success: boolean;
+    data: {
+        task: Task;
+        handed_off: boolean;
+        new_worker_type: string;
+    };
+}>;
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export declare function reviseEpic(userId: string, projectId: string, epicId: string, changes: {
+    add_tasks?: {
+        title: string;
+        description?: string;
+        effort?: string;
+        domain?: string;
+        blocked_by?: string[];
+    }[];
+    remove_task_ids?: string[];
+    update_tasks?: {
+        task_id: string;
+        title?: string;
+        description?: string;
+        effort?: string;
+    }[];
+}): Promise<{
+    epic: Task;
+    added: Task[];
+    removed: string[];
+    updated: Task[];
+}>;

package/dist/helpers/tasks.js

@@ -3,6 +3,7 @@
 // =============================================================================
 import { apiRequest } from './api-client.js';
 import { matchTaskToWorker, buildWorkerPrompt } from './workers.js';
+import { isCircuitOpen } from './circuit-breaker.js';
 export function parseJsonArray(value) {
     if (!value)
         return [];
@@ -51,11 +52,12 @@ export async function getTask(userId, projectId, taskId, full = false) {
     const endpoint = full ? 'full' : '';
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}${endpoint ? `/${endpoint}` : ''}`);
 }
-export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes = 30) {
-    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', {
-        agent_id: agentId,
-        lock_duration_minutes: lockDurationMinutes,
-    });
+export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes) {
+    const body = { agent_id: agentId };
+    if (lockDurationMinutes !== undefined) {
+        body.lock_duration_minutes = lockDurationMinutes;
+    }
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', body);
 }
 export async function releaseTask(userId, projectId, taskId, agentId, newStatus, workLog) {
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/release`, 'POST', {
@@ -90,11 +92,29 @@ export async function heartbeatTask(userId, projectId, taskId, agentId, extendMi
 // -----------------------------------------------------------------------------
 // Orchestration Functions
 // -----------------------------------------------------------------------------
-// Configuration: Default maximum parallel tasks
-export const DEFAULT_MAX_PARALLEL = 5;
+// Effort weights for capacity planning
+export const EFFORT_WEIGHTS = {
+    xs: 1,
+    s: 2,
+    m: 4,
+    l: 8,
+    xl: 16,
+};
+// Default lock duration by effort size (in minutes)
+// Used when no explicit lockDurationMinutes is provided to claimTask
+export const LOCK_DURATION_BY_EFFORT = {
+    xs: 15, // Extra small: 15 minutes
+    s: 30, // Small: 30 minutes (default)
+    m: 60, // Medium: 1 hour
+    l: 120, // Large: 2 hours
+    xl: 240, // Extra large: 4 hours
+};
+// Configuration: Default capacity budget in effort units
+// 20 units allows: 20 xs tasks OR 1 xl + 1 m task OR 5 m tasks, etc.
+export const DEFAULT_CAPACITY_BUDGET = 20;
 /**
- * Get count of currently active tasks
- * Returns both in_progress and claimed (locked) task counts
+ * Get effort-weighted load of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts, plus effort-weighted load
  */
 export async function getActiveTaskCount(userId, projectId, epicId) {
     // Get all in_progress tasks
@@ -105,10 +125,15 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
     });
     let inProgressCount = 0;
     let claimedCount = 0;
+    let effortLoad = 0;
     if (inProgressResult.success && inProgressResult.data.length > 0) {
         const now = new Date();
         for (const task of inProgressResult.data) {
             inProgressCount++;
+            // Calculate effort weight (default to 'm' = 4 units if not specified)
+            const effort = task.estimated_effort || 'm';
+            const weight = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+            effortLoad += weight;
             // Check if task is also claimed (has valid lock)
             if (task.assigned_to && task.lock_expires_at) {
                 const lockExpires = new Date(task.lock_expires_at);
@@ -122,6 +147,7 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
         inProgress: inProgressCount,
         claimed: claimedCount,
         total: inProgressCount,
+        effortLoad,
     };
 }
 /**
@@ -130,13 +156,13 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
- * - Respects max parallel limit by considering currently active tasks
+ * - Respects effort-weighted capacity budget
  */
-export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = DEFAULT_MAX_PARALLEL) {
-    // Get current active task count
+export async function getDispatchableTasks(userId, projectId, epicId, capacityBudget = DEFAULT_CAPACITY_BUDGET) {
+    // Get current active task effort load
     const activeCount = await getActiveTaskCount(userId, projectId, epicId);
-    // Calculate remaining capacity
-    const remainingCapacity = maxParallel - activeCount.total;
+    // Calculate remaining effort capacity
+    let remainingCapacity = capacityBudget - activeCount.effortLoad;
     if (remainingCapacity <= 0) {
         // No capacity available, return empty array
         return [];
@@ -178,6 +204,13 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
                 continue; // Still blocked
             }
         }
+        // Calculate task effort weight
+        const effort = task.estimated_effort || 'm';
+        const taskEffort = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+        // Check if this task fits within remaining capacity
+        if (taskEffort > remainingCapacity) {
+            continue; // Task too large for remaining capacity
+        }
         // Match to expert worker
         const worker = matchTaskToWorker({
             title: task.title,
@@ -185,6 +218,11 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             domain: task.domain || undefined,
             tags: parseJsonArray(task.tags),
         });
+        // Circuit breaker check: skip if worker circuit is open
+        if (isCircuitOpen(worker.id)) {
+            console.warn(`[Circuit Breaker] Skipping task ${task.id} - circuit OPEN for worker type: ${worker.id}`);
+            continue; // Skip this task
+        }
         // Get task context
         const fullTask = await getTask(userId, projectId, task.id, true);
         const taskData = fullTask.data;
@@ -195,13 +233,48 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             parentContext: taskData.parent,
             dependencies: [],
         });
-        // Only dispatch tasks that fit within remaining capacity
-        if (dispatchable.length >= remainingCapacity) {
+        // Reduce remaining capacity by the effort of this task
+        remainingCapacity -= taskEffort;
+        // Stop if no capacity remains
+        if (remainingCapacity <= 0) {
             break;
         }
     }
+    // Sort by priority: critical → high → medium → low
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    dispatchable.sort((a, b) => (priorityOrder[a.task.priority] ?? 2) - (priorityOrder[b.task.priority] ?? 2));
     return dispatchable;
 }
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export function getLockExpiryWarning(lockExpiresAt) {
+    if (!lockExpiresAt) {
+        return { warning: false, minutes_remaining: 0 };
+    }
+    const now = new Date();
+    const expiryTime = new Date(lockExpiresAt);
+    const secondsRemaining = (expiryTime.getTime() - now.getTime()) / 1000;
+    const minutesRemaining = Math.floor(secondsRemaining / 60);
+    // Expired (lock time has passed)
+    if (secondsRemaining <= 0) {
+        return {
+            warning: true,
+            minutes_remaining: 0,
+            message: '🚨 Lock has EXPIRED. Task may be claimed by another agent.',
+        };
+    }
+    // Warn if lock expires within 5 minutes (but not yet expired)
+    if (minutesRemaining <= 5 && minutesRemaining >= 1) {
+        return {
+            warning: true,
+            minutes_remaining: minutesRemaining,
+            message: `⚠️  Lock expires in ${minutesRemaining} minute${minutesRemaining !== 1 ? 's' : ''}. Call task_heartbeat to extend.`,
+        };
+    }
+    // Less than 1 minute but not expired - no warning (edge case)
+    return { warning: false, minutes_remaining: minutesRemaining };
+}
 /**
  * Get full execution context for a worker agent
  */
@@ -251,6 +324,8 @@ export async function getExecutionContext(userId, projectId, taskId) {
             status: s.status,
         })),
     });
+    // Check for lock expiry warning
+    const lockWarning = getLockExpiryWarning(task.lock_expires_at);
     return {
         task,
         worker,
@@ -258,6 +333,7 @@ export async function getExecutionContext(userId, projectId, taskId) {
         context: taskData.context,
         parentTask: taskData.parent,
         siblingTasks,
+        lockWarning,
     };
 }
 /**
@@ -303,6 +379,81 @@ export async function resolveTaskDependencies(userId, projectId, completedTaskId
     }
     return newlyUnblocked;
 }
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export async function getEpicAggregate(userId, projectId, epicId, includePending = false) {
+    // Get the epic
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    // Verify it's an epic
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    // Get all child tasks
+    const tasksResult = await listTasks(userId, projectId, {
+        parent_id: epicId,
+        limit: 100,
+    });
+    if (!tasksResult.success) {
+        return {
+            epic: {
+                id: epic.id,
+                title: epic.title,
+                description: epic.description,
+                status: epic.status,
+            },
+            tasks: [],
+            summary_stats: {
+                total: 0,
+                completed: 0,
+                in_progress: 0,
+                pending: 0,
+            },
+        };
+    }
+    const allTasks = tasksResult.data;
+    // Get work_log context for each task
+    const tasksWithLogs = await Promise.all(allTasks.map(async (task) => {
+        // Get full task data to access context
+        const fullTaskResult = await getTask(userId, projectId, task.id, true);
+        const fullTaskData = fullTaskResult.data;
+        // Find work_log context
+        const workLogContext = fullTaskData.context?.find(ctx => ctx.context_type === 'work_log');
+        return {
+            id: task.id,
+            title: task.title,
+            status: task.status,
+            work_log: workLogContext?.content || null,
+            completed_at: task.completed_at,
+        };
+    }));
+    // Filter based on includePending
+    const filteredTasks = includePending
+        ? tasksWithLogs
+        : tasksWithLogs.filter(t => t.status === 'done' || t.status === 'in_progress');
+    // Calculate stats
+    const stats = {
+        total: allTasks.length,
+        completed: allTasks.filter(t => t.status === 'done').length,
+        in_progress: allTasks.filter(t => t.status === 'in_progress').length,
+        pending: allTasks.filter(t => t.status === 'ready' || t.status === 'backlog').length,
+    };
+    return {
+        epic: {
+            id: epic.id,
+            title: epic.title,
+            description: epic.description,
+            status: epic.status,
+        },
+        tasks: filteredTasks,
+        summary_stats: stats,
+    };
+}
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -368,3 +519,97 @@ export async function getEpicStatus(userId, projectId, epicId) {
         autoCompleted,
     };
 }
+export async function handoffTask(userId, projectId, taskId, agentId, newWorkerType, reason) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/handoff`, 'POST', {
+        agent_id: agentId,
+        new_worker_type: newWorkerType,
+        reason,
+    });
+}
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export async function reviseEpic(userId, projectId, epicId, changes) {
+    // Verify epic exists and is not done
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    if (epic.status === 'done') {
+        throw new Error(`Cannot revise completed epic: ${epicId}`);
+    }
+    const added = [];
+    const removed = [];
+    const updated = [];
+    // Add new tasks
+    if (changes.add_tasks && changes.add_tasks.length > 0) {
+        for (const taskDef of changes.add_tasks) {
+            const taskResult = await createTask(userId, projectId, {
+                type: 'task',
+                title: taskDef.title,
+                description: taskDef.description,
+                parent_id: epicId,
+                priority: epic.priority,
+                estimated_effort: taskDef.effort,
+                blocked_by: taskDef.blocked_by,
+                domain: taskDef.domain,
+            });
+            added.push(taskResult.data);
+        }
+    }
+    // Remove tasks (set to cancelled status)
+    if (changes.remove_task_ids && changes.remove_task_ids.length > 0) {
+        for (const taskId of changes.remove_task_ids) {
+            try {
+                await updateTaskStatus(userId, projectId, taskId, 'cancelled', 'system:epic-revision');
+                removed.push(taskId);
+            }
+            catch (error) {
+                // Log but continue - task may not exist
+                console.warn(`Failed to cancel task ${taskId}:`, error);
+            }
+        }
+    }
+    // Update existing tasks
+    // Note: The API doesn't support PATCH for tasks, so we can only update status
+    // For title/description/effort updates, we'll need to add context explaining the change
+    if (changes.update_tasks && changes.update_tasks.length > 0) {
+        for (const update of changes.update_tasks) {
+            try {
+                const taskResult = await getTask(userId, projectId, update.task_id);
+                if (!taskResult.success)
+                    continue;
+                const task = taskResult.data;
+                // Add context about the updates since we can't modify fields directly
+                const updates = [];
+                if (update.title && update.title !== task.title) {
+                    updates.push(`Title updated: "${task.title}" → "${update.title}"`);
+                }
+                if (update.description && update.description !== task.description) {
+                    updates.push(`Description updated: "${update.description}"`);
+                }
+                if (update.effort && update.effort !== task.estimated_effort) {
+                    updates.push(`Effort updated: ${task.estimated_effort || 'unset'} → ${update.effort}`);
+                }
+                if (updates.length > 0) {
+                    await addTaskContext(userId, projectId, update.task_id, 'decision', updates.join('\n'), 'task_plan_revise', 'epic-revision');
+                    updated.push(task);
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to update task ${update.task_id}:`, error);
+            }
+        }
+    }
+    return {
+        epic,
+        added,
+        removed,
+        updated,
+    };
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export type { ExpertWorker } from './helpers/workers.js';
 export type { Task, TaskContext, DispatchableTask } from './helpers/tasks.js';
 export type { DeduplicationTracker } from './context/index.js';
+export type { CircuitState } from './helpers/circuit-breaker.js';
 export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
 export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
 export { injectContext } from './helpers/api-client.js';
 export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
 export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
+export { recordWorkerFailure, isCircuitOpen, getCircuitStatus, resetCircuit, resetAllCircuits } from './helpers/circuit-breaker.js';
 export declare function startServer(): Promise<void>;

package/dist/index.js

@@ -17,6 +17,7 @@ export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskD
 export { injectContext } from './helpers/api-client.js';
 export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
 export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
+export { recordWorkerFailure, isCircuitOpen, getCircuitStatus, resetCircuit, resetAllCircuits } from './helpers/circuit-breaker.js';
 // =============================================================================
 // Server Initialization
 // =============================================================================

package/dist/tools.js

@@ -465,6 +465,54 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['goal', 'epic_title', 'tasks'],
                 },
             },
+            {
+                name: 'task_plan_revise',
+                description: 'Modify an existing epic by adding new tasks, removing tasks, or updating task details. Enables iterative planning without recreating the entire plan.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'The ID of the epic to revise',
+                        },
+                        add_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                    domain: { type: 'string' },
+                                    blocked_by: { type: 'array', items: { type: 'string' } },
+                                },
+                                required: ['title'],
+                            },
+                            description: 'New tasks to add to the epic',
+                        },
+                        remove_task_ids: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Task IDs to cancel (sets status to cancelled)',
+                        },
+                        update_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    task_id: { type: 'string' },
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                },
+                                required: ['task_id'],
+                            },
+                            description: 'Tasks to update (adds context about changes)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             {
                 name: 'task_start',
                 description: 'PROACTIVE: When starting work on a task, claim it and get all context. Use this before beginning any task work.',
@@ -608,7 +656,16 @@ High hit rate memories (frequently fetched after being indexed) are good candida
             },
             {
                 name: 'task_claim',
-                description: 'Claim a task for working on it. Creates a lock preventing other agents from working on it.',
+                description: `Claim a task for working on it. Creates a lock preventing other agents from working on it.
+
+Lock duration is automatically scaled based on task effort:
+- xs: 15 minutes
+- s: 30 minutes (default if no effort specified)
+- m: 60 minutes (1 hour)
+- l: 120 minutes (2 hours)
+- xl: 240 minutes (4 hours)
+
+Explicit lock_duration_minutes parameter overrides the effort-based default.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -622,7 +679,7 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                         },
                         lock_duration_minutes: {
                             type: 'number',
-                            description: 'Lock duration in minutes (default: 30)',
+                            description: 'Optional: Override effort-based lock duration (in minutes)',
                         },
                     },
                     required: ['task_id', 'agent_id'],
@@ -739,6 +796,32 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['task_id', 'agent_id'],
                 },
             },
+            {
+                name: 'task_handoff',
+                description: 'Hand off a task to a different expert worker type during execution. Releases current lock, updates agent_type, and sets task back to ready status for re-dispatch.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_id: {
+                            type: 'string',
+                            description: 'The task ID to hand off',
+                        },
+                        new_worker_type: {
+                            type: 'string',
+                            description: 'Target worker type (e.g., "api-expert", "frontend-expert", "database-expert")',
+                        },
+                        reason: {
+                            type: 'string',
+                            description: 'Why the handoff is needed (e.g., "requires database expertise", "needs API integration")',
+                        },
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your agent identifier (default: claude-code)',
+                        },
+                    },
+                    required: ['task_id', 'new_worker_type', 'reason'],
+                },
+            },
             // =========================================================================
             // ORCHESTRATION TOOLS
             // =========================================================================
@@ -921,6 +1004,24 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['epic_id'],
                 },
             },
+            {
+                name: 'task_aggregate',
+                description: 'Aggregate work_log context from all sibling tasks under an epic for orchestrator synthesis. Returns structured summary of completed work across all tasks in the epic.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'Epic ID to aggregate from',
+                        },
+                        include_pending: {
+                            type: 'boolean',
+                            description: 'Include non-completed tasks (default: false)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             // =========================================================================
             // CODEBASE MAPPING TOOLS
             // =========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -14,22 +14,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "prepublishOnly": "npm run build",
-    "codedna:monitor": "tsx -e \"import { runMonitoring } from './src/helpers/codedna-monitoring.js'; runMonitoring()\"",
-    "codedna:analytics": "tsx -e \"import { weeklyAnalyticsSummary } from './src/helpers/usage-analytics.js'; weeklyAnalyticsSummary()\"",
-    "codedna:analytics:24h": "tsx -e \"import { getLast24HoursAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast24HoursAnalytics(); printAnalytics(r, 'Last 24 Hours')\"",
-    "codedna:analytics:30d": "tsx -e \"import { getLast30DaysAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast30DaysAnalytics(); printAnalytics(r, 'Last 30 Days')\"",
-    "prompt:verify": "scripts/verify-prompt-compliance.sh",
-    "eval:build-dataset": "tsx src/evaluation/build-dataset.ts",
-    "eval:threshold": "tsx src/evaluation/threshold-eval.ts"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/claudetools/memory.git"
@@ -74,5 +58,20 @@
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "codedna:monitor": "tsx -e \"import { runMonitoring } from './src/helpers/codedna-monitoring.js'; runMonitoring()\"",
+    "codedna:analytics": "tsx -e \"import { weeklyAnalyticsSummary } from './src/helpers/usage-analytics.js'; weeklyAnalyticsSummary()\"",
+    "codedna:analytics:24h": "tsx -e \"import { getLast24HoursAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast24HoursAnalytics(); printAnalytics(r, 'Last 24 Hours')\"",
+    "codedna:analytics:30d": "tsx -e \"import { getLast30DaysAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast30DaysAnalytics(); printAnalytics(r, 'Last 30 Days')\"",
+    "prompt:verify": "scripts/verify-prompt-compliance.sh",
+    "eval:build-dataset": "tsx src/evaluation/build-dataset.ts",
+    "eval:threshold": "tsx src/evaluation/threshold-eval.ts"
   }
-}
+}