vellum 0.2.0 → 0.2.2

package/src/tools/tasks/work-item-enqueue.ts

@@ -1,8 +1,10 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { getTask, listTasks, createTask } from '../../tasks/task-store.js';
-import { createWorkItem } from '../../work-items/work-item-store.js';
+import { createWorkItemWithPermissions, findActiveWorkItemsByTitle, updateWorkItem, identifyEntityById, buildWorkItemMismatchError } from '../../work-items/work-item-store.js';
+import { sanitizeToolList } from '../../tasks/tool-sanitizer.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-list-add');
 
 const PRIORITY_LABELS: Record<number, string> = {
   0: 'high',
@@ -10,151 +12,114 @@ const PRIORITY_LABELS: Record<number, string> = {
   2: 'low',
 };
 
-const definition: ToolDefinition = {
-  name: 'task_list_add',
-  description:
-    'Add a task to the user\'s Task Queue. Use this when the user says "add to my tasks", "add to my queue", "put this on my task list", "track this task", or any variation of adding a one-off item they want to remember or work on. You can provide just a title for ad-hoc items, or reference an existing task definition by name or ID. Do NOT use schedule_create or reminder for simple "add to tasks" requests — those are for timed/recurring automation only.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      task_id: {
-        type: 'string',
-        description: 'ID of an existing task definition to enqueue. Provide this, task_name, or just title.',
-      },
-      task_name: {
-        type: 'string',
-        description:
-          'Title/name of an existing task definition to search for (case-insensitive substring match). Provide this, task_id, or just title.',
-      },
-      title: {
-        type: 'string',
-        description:
-          'Title for the work item. When provided WITHOUT task_id or task_name, creates an ad-hoc work item directly (a lightweight task template is auto-created behind the scenes). When provided WITH task_id or task_name, overrides the task definition title.',
-      },
-      notes: {
-        type: 'string',
-        description: 'Notes to attach to the work item.',
-      },
-      priority_tier: {
-        type: 'number',
-        description: '0 = high, 1 = medium (default), 2 = low.',
-      },
-      sort_index: {
-        type: 'number',
-        description: 'Manual sort order within the priority tier.',
-      },
-    },
-  },
-};
-
-class TaskListAddTool implements Tool {
-  name = 'task_list_add';
-  description = definition.description;
-  category = 'tasks';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+function handleDuplicate(
+  title: string,
+  ifExists: string,
+  input: Record<string, unknown>,
+): ToolExecutionResult | null {
+  const existing = findActiveWorkItemsByTitle(title);
+  if (existing.length === 0) return null;
+
+  const match = existing[0];
+  log.info({ title, existingId: match.id, ifExists }, 'task_list_add: duplicate detected');
+
+  if (ifExists === 'reuse_existing') {
+    log.info({ title, existingId: match.id }, 'task_list_add: reused existing item');
+    return {
+      content: `Task "${match.title}" already exists in the queue (ID: ${match.id}, status: ${match.status}). Use task_list_update to modify it.`,
+      isError: false,
+    };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    try {
-      const taskId = input.task_id as string | undefined;
-      const taskName = input.task_name as string | undefined;
-      const titleOverride = input.title as string | undefined;
-      const notes = input.notes as string | undefined;
-      const priorityTier = input.priority_tier as number | undefined;
-      const sortIndex = input.sort_index as number | undefined;
-
-      // Ad-hoc mode: title provided without task_id or task_name
-      if (!taskId && !taskName) {
-        if (!titleOverride) {
-          return {
-            content: 'Error: You must provide either task_id, task_name, or title to create a work item.',
-            isError: true,
-          };
-        }
+  if (ifExists === 'update_existing') {
+    const updates: Partial<{ title: string; notes: string; priorityTier: number; sortIndex: number }> = {};
+    if (input.priority_tier !== undefined) updates.priorityTier = input.priority_tier as number;
+    if (input.notes !== undefined) updates.notes = input.notes as string;
+    if (input.sort_index !== undefined) updates.sortIndex = input.sort_index as number;
+    if (Object.keys(updates).length > 0) {
+      updateWorkItem(match.id, updates);
+    }
+    log.info({ title, existingId: match.id, updates }, 'task_list_add: updated existing item');
+    return {
+      content: `Reused existing task "${match.title}" (ID: ${match.id}) instead of creating a duplicate.${
+        Object.keys(updates).length > 0 ? ` Updated: ${Object.keys(updates).join(', ')}.` : ''
+      }`,
+      isError: false,
+    };
+  }
 
-        // Auto-create a lightweight task template for the ad-hoc item
-        const adHocTask = createTask({
-          title: titleOverride,
-          template: titleOverride,
-        });
-
-        const workItem = createWorkItem({
-          taskId: adHocTask.id,
-          title: titleOverride,
-          notes,
-          priorityTier: priorityTier ?? 1,
-          sortIndex,
-        });
-
-        const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
-        const lines = [
-          `Enqueued work item:`,
-          `  Title: ${workItem.title}`,
-          `  ID: ${workItem.id}`,
-          `  Priority: ${priority}`,
-          `  Status: ${workItem.status}`,
-        ];
-        if (workItem.notes) {
-          lines.push(`  Notes: ${workItem.notes}`);
-        }
-        if (workItem.sortIndex !== null) {
-          lines.push(`  Sort index: ${workItem.sortIndex}`);
-        }
+  return null;
+}
 
-        return { content: lines.join('\n'), isError: false };
+export async function executeTaskListAdd(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  try {
+    const taskId = input.task_id as string | undefined;
+    const taskName = input.task_name as string | undefined;
+    const titleOverride = input.title as string | undefined;
+    const executionPrompt = input.execution_prompt as string | undefined;
+    const notes = input.notes as string | undefined;
+    const priorityTier = input.priority_tier as number | undefined;
+    const sortIndex = input.sort_index as number | undefined;
+    const rawRequiredTools = input.required_tools as string[] | undefined;
+
+    const ifExists = (input.if_exists as string) || 'reuse_existing';
+
+    // Sanitize explicit required_tools if provided (including empty array)
+    const hasExplicitTools = rawRequiredTools !== undefined;
+    const sanitizedTools = hasExplicitTools ? sanitizeToolList(rawRequiredTools) : undefined;
+
+    // Ad-hoc mode: title provided without task_id or task_name
+    if (!taskId && !taskName) {
+      if (!titleOverride) {
+        return {
+          content: 'Error: You must provide either task_id, task_name, or title to create a work item.',
+          isError: true,
+        };
       }
 
-      let resolvedTask;
-
-      if (taskId) {
-        resolvedTask = getTask(taskId);
-        if (!resolvedTask) {
-          return { content: `Error: No task definition found with ID "${taskId}".`, isError: true };
-        }
+      // Duplicate-prevention guard
+      if (ifExists !== 'create_duplicate') {
+        const duplicateResult = handleDuplicate(titleOverride, ifExists, input);
+        if (duplicateResult) return duplicateResult;
       } else {
-        // Search by name (case-insensitive substring match)
-        const needle = taskName!.toLowerCase();
-        const allTasks = listTasks();
-        const matches = allTasks.filter((t) => t.title.toLowerCase().includes(needle));
-
-        if (matches.length === 0) {
-          return {
-            content: `Error: No task definition found matching "${taskName}". Use task_list to see available tasks.`,
-            isError: true,
-          };
-        }
+        log.info({ title: titleOverride }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
+      }
 
-        if (matches.length > 1) {
-          const lines = [
-            `Multiple task definitions match "${taskName}". Please specify by ID:`,
-            '',
-          ];
-          for (const m of matches) {
-            lines.push(`- ${m.title}  (ID: ${m.id})`);
-          }
-          return { content: lines.join('\n'), isError: true };
-        }
+      log.debug({ title: titleOverride }, 'task_list_add: creating new item');
+
+      // Auto-create a lightweight task template for the ad-hoc item.
+      // Use execution_prompt as the template (the actual instruction sent to the
+      // model at run time), falling back to notes then title. This preserves
+      // detailed instructions (e.g. full file paths) that may be shortened in
+      // the display title.
+      const adHocTemplate = executionPrompt ?? notes ?? titleOverride;
+      const adHocTask = createTask({
+        title: titleOverride,
+        template: adHocTemplate,
+      });
 
-        resolvedTask = matches[0];
-      }
+      // For ad-hoc items: explicit tools → persist; omitted → null
+      const adHocRequiredTools = hasExplicitTools ? JSON.stringify(sanitizedTools) : undefined;
 
-      const workItem = createWorkItem({
-        taskId: resolvedTask.id,
-        title: titleOverride ?? resolvedTask.title,
+      const workItem = createWorkItemWithPermissions({
+        taskId: adHocTask.id,
+        title: titleOverride,
         notes,
         priorityTier: priorityTier ?? 1,
         sortIndex,
+        requiredTools: adHocRequiredTools,
       });
 
+      log.info({ selectorType: 'title', workItemId: workItem.id, title: workItem.title }, 'ad-hoc work item created');
+
       const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
       const lines = [
         `Enqueued work item:`,
         `  Title: ${workItem.title}`,
         `  ID: ${workItem.id}`,
-        `  Task definition: ${resolvedTask.title} (${resolvedTask.id})`,
         `  Priority: ${priority}`,
         `  Status: ${workItem.status}`,
       ];
@@ -166,11 +131,104 @@ class TaskListAddTool implements Tool {
       }
 
       return { content: lines.join('\n'), isError: false };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
     }
+
+    let resolvedTask;
+
+    if (taskId) {
+      resolvedTask = getTask(taskId);
+      if (!resolvedTask) {
+        const entity = identifyEntityById(taskId);
+        if (entity.type === 'work_item') {
+          return {
+            content: `Error: ${buildWorkItemMismatchError(taskId, entity.title!, 'task_list_update to modify the existing work item, or task_list_add with just a title for a new ad-hoc item')}`,
+            isError: true,
+          };
+        }
+        return { content: `Error: No task definition found with ID "${taskId}". Use task_list to see available task templates, or provide just a title to create an ad-hoc work item.`, isError: true };
+      }
+    } else {
+      // Search by name (case-insensitive substring match)
+      const needle = taskName!.toLowerCase();
+      const allTasks = listTasks();
+      const matches = allTasks.filter((t) => t.title.toLowerCase().includes(needle));
+
+      if (matches.length === 0) {
+        return {
+          content: `Error: No task definition found matching "${taskName}". Use task_list to see available tasks.`,
+          isError: true,
+        };
+      }
+
+      if (matches.length > 1) {
+        const lines = [
+          `Multiple task definitions match "${taskName}". Please specify by ID:`,
+          '',
+        ];
+        for (const m of matches) {
+          lines.push(`- ${m.title}  (ID: ${m.id})`);
+        }
+        return { content: lines.join('\n'), isError: true };
+      }
+
+      resolvedTask = matches[0];
+    }
+
+    const finalTitle = titleOverride ?? resolvedTask.title;
+
+    // Duplicate-prevention guard
+    if (ifExists !== 'create_duplicate') {
+      const duplicateResult = handleDuplicate(finalTitle, ifExists, input);
+      if (duplicateResult) return duplicateResult;
+    } else {
+      log.info({ title: finalTitle }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
+    }
+
+    log.debug({ title: finalTitle }, 'task_list_add: creating new item');
+
+    const selectorType = taskId ? 'task_id' : 'task_name';
+
+    // Snapshot precedence: explicit required_tools > template tools > null
+    let resolvedRequiredTools: string | undefined;
+    if (hasExplicitTools) {
+      resolvedRequiredTools = JSON.stringify(sanitizedTools);
+    } else if (resolvedTask.requiredTools) {
+      // Snapshot template tools at add time
+      const templateTools = sanitizeToolList(JSON.parse(resolvedTask.requiredTools));
+      resolvedRequiredTools = JSON.stringify(templateTools);
+    }
+
+    const workItem = createWorkItemWithPermissions({
+      taskId: resolvedTask.id,
+      title: finalTitle,
+      notes,
+      priorityTier: priorityTier ?? 1,
+      sortIndex,
+      requiredTools: resolvedRequiredTools,
+    });
+
+    log.info({ selectorType, taskId: resolvedTask.id, workItemId: workItem.id, title: workItem.title }, 'work item created from task definition');
+
+    const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
+    const lines = [
+      `Enqueued work item:`,
+      `  Title: ${workItem.title}`,
+      `  ID: ${workItem.id}`,
+      `  Task definition: ${resolvedTask.title} (${resolvedTask.id})`,
+      `  Priority: ${priority}`,
+      `  Status: ${workItem.status}`,
+    ];
+    if (workItem.notes) {
+      lines.push(`  Notes: ${workItem.notes}`);
+    }
+    if (workItem.sortIndex !== null) {
+      lines.push(`  Sort index: ${workItem.sortIndex}`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ error: msg }, 'enqueue failed');
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-export const taskListAddTool = new TaskListAddTool();

package/src/tools/tasks/work-item-list.ts

@@ -1,86 +1,41 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { listWorkItems, type WorkItemStatus } from '../../work-items/work-item-store.js';
 
-const PRIORITY_LABELS: Record<number, string> = {
-  0: 'high',
-  1: 'medium',
-  2: 'low',
-};
-
-const definition: ToolDefinition = {
-  name: 'task_list_show',
-  description: 'List the user\'s Task Queue (work items) with their status, priority, and last run info. Use this when the user says "show my tasks", "what\'s in my queue", "what\'s on my task list", or similar.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      status: {
-        oneOf: [
-          { type: 'string' },
-          { type: 'array', items: { type: 'string' } },
-        ],
-        description:
-          'Optional status filter. A single status string (e.g. "queued") or an array of statuses to include.',
-      },
-    },
-  },
-};
-
-class TaskListShowTool implements Tool {
-  name = 'task_list_show';
-  description = definition.description;
-  category = 'tasks';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
-  }
-
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    try {
-      const statusFilter = input.status as string | string[] | undefined;
-
-      let items;
-      if (typeof statusFilter === 'string') {
-        items = listWorkItems({ status: statusFilter as WorkItemStatus });
-      } else if (Array.isArray(statusFilter)) {
-        // listWorkItems only supports a single status filter, so we fetch all
-        // and filter client-side when an array is provided
-        const allItems = listWorkItems();
-        const allowed = new Set(statusFilter);
-        items = allItems.filter((item) => allowed.has(item.status));
-      } else {
-        items = listWorkItems();
-      }
+export async function executeTaskListShow(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  try {
+    const statusFilter = input.status as string | string[] | undefined;
+
+    let items;
+    if (typeof statusFilter === 'string') {
+      items = listWorkItems({ status: statusFilter as WorkItemStatus });
+    } else if (Array.isArray(statusFilter)) {
+      // listWorkItems only supports a single status filter, so we fetch all
+      // and filter client-side when an array is provided
+      const allItems = listWorkItems();
+      const allowed = new Set(statusFilter);
+      items = allItems.filter((item) => allowed.has(item.status));
+    } else {
+      items = listWorkItems();
+    }
 
-      if (items.length === 0) {
-        return { content: 'No Tasks found.', isError: false };
-      }
+    const count = items.length;
+    const filtered = statusFilter !== undefined;
 
-      const lines = [`Found ${items.length} work item(s):`, ''];
+    if (count === 0) {
+      const suffix = filtered ? 'no items matching filter.' : 'no tasks queued.';
+      return { content: `Opened Tasks window \u2014 ${suffix}`, isError: false };
+    }
 
-      for (const item of items) {
-        const priority = PRIORITY_LABELS[item.priorityTier] ?? `tier ${item.priorityTier}`;
-        lines.push(`- ${item.title}`);
-        lines.push(`    ID: ${item.id}`);
-        lines.push(`    Status: ${item.status}`);
-        lines.push(`    Priority: ${priority}`);
-        if (item.notes) {
-          lines.push(`    Notes: ${item.notes}`);
-        }
-        if (item.lastRunStatus) {
-          lines.push(`    Last run: ${item.lastRunStatus}`);
-        }
-        lines.push('');
-      }
+    const label = filtered
+      ? `${count} ${Array.isArray(statusFilter) ? 'matching' : statusFilter} item${count === 1 ? '' : 's'}`
+      : `${count} item${count === 1 ? '' : 's'}`;
 
-      return { content: lines.join('\n'), isError: false };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
-    }
+    return { content: `Opened Tasks window (${label}).`, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-export const taskListShowTool = new TaskListShowTool();

package/src/tools/tasks/work-item-remove.ts

@@ -0,0 +1,60 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { resolveWorkItem, removeWorkItemFromQueue, identifyEntityById, buildTaskTemplateMismatchError, type WorkItemStatus } from '../../work-items/work-item-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-list-remove');
+
+export async function executeTaskListRemove(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const selectorType = input.work_item_id ? 'work_item_id' : input.task_id ? 'task_id' : input.task_name ? 'task_name' : input.title ? 'title' : 'none';
+
+  try {
+    const selector = {
+      workItemId: input.work_item_id as string | undefined,
+      taskId: input.task_id as string | undefined,
+      title: (input.task_name ?? input.title) as string | undefined,
+      priorityTier: input.priority_tier as number | undefined,
+      status: input.status as WorkItemStatus | undefined,
+      createdOrder: input.created_order as number | undefined,
+    };
+
+    const resolveResult = resolveWorkItem(selector);
+
+    if (resolveResult.status === 'not_found') {
+      // When the model passes an ID directly, check if it's a task template
+      if (selector.workItemId) {
+        const entity = identifyEntityById(selector.workItemId);
+        if (entity.type === 'task_template') {
+          log.warn({ selectorType, inputId: selector.workItemId }, 'task template ID passed as work_item_id');
+          return {
+            content: `Error: ${buildTaskTemplateMismatchError(selector.workItemId, entity.title!, 'task_delete to delete task templates')}`,
+            isError: true,
+          };
+        }
+      }
+      log.warn({ selectorType, error: resolveResult.message }, 'work item not found for removal');
+      return { content: `Error: ${resolveResult.message}`, isError: true };
+    }
+
+    if (resolveResult.status === 'ambiguous') {
+      log.warn({ selectorType, matchCount: resolveResult.matches.length }, 'ambiguous selector for removal');
+      return { content: `Error: ${resolveResult.message}`, isError: true };
+    }
+
+    const item = resolveResult.workItem;
+
+    log.info({ selectorType, selectorValue: input[selectorType], resolvedWorkItemId: item.id, title: item.title }, 'resolved work item for removal');
+
+    const removeResult = removeWorkItemFromQueue(item.id);
+
+    log.info({ resolvedWorkItemId: item.id, deletedCount: 1 }, 'work item removed');
+
+    return { content: removeResult.message, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ selectorType, error: msg }, 'remove failed');
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/tools/tasks/work-item-update.ts

@@ -0,0 +1,114 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { resolveWorkItem, updateWorkItem, identifyEntityById, buildTaskTemplateMismatchError, type WorkItemStatus } from '../../work-items/work-item-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-list-update');
+
+const PRIORITY_LABELS: Record<number, string> = {
+  0: 'high',
+  1: 'medium',
+  2: 'low',
+};
+
+export async function executeTaskListUpdate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const selectorType = input.work_item_id ? 'work_item_id' : input.task_id ? 'task_id' : input.task_name ? 'task_name' : input.title ? 'title' : 'none';
+
+  try {
+    // Build selector from whichever identifier was provided
+    const selector = {
+      workItemId: input.work_item_id as string | undefined,
+      taskId: input.task_id as string | undefined,
+      title: (input.task_name ?? input.title) as string | undefined,
+      priorityTier: input.filter_priority_tier as number | undefined,
+      status: input.filter_status as WorkItemStatus | undefined,
+      createdOrder: input.created_order as number | undefined,
+    };
+
+    // Resolve the target work item
+    const result = resolveWorkItem(selector);
+
+    if (result.status === 'not_found') {
+      // When the model passes an ID directly, check if it's a task template
+      if (selector.workItemId) {
+        const entity = identifyEntityById(selector.workItemId);
+        if (entity.type === 'task_template') {
+          log.warn({ selectorType, inputId: selector.workItemId }, 'task template ID passed as work_item_id');
+          return {
+            content: `Error: ${buildTaskTemplateMismatchError(selector.workItemId, entity.title!, 'task_delete to remove task templates, or task_list to view them')}`,
+            isError: true,
+          };
+        }
+      }
+      log.warn({ selectorType, error: result.message }, 'work item not found for update');
+      return { content: `Error: ${result.message}`, isError: true };
+    }
+
+    if (result.status === 'ambiguous') {
+      log.warn({ selectorType, matchCount: result.matches.length }, 'ambiguous selector for update');
+      return { content: `Error: ${result.message}`, isError: true };
+    }
+
+    const item = result.workItem;
+
+    // Block direct transitions to 'done' — the only path to done is
+    // through the Review action (handleWorkItemComplete in the daemon).
+    if (input.status === 'done') {
+      log.warn({ selectorType, resolvedWorkItemId: item.id }, 'rejected attempt to set status to done directly');
+      return {
+        content: 'Error: Cannot set status to \'done\' directly. Use the Review action in the Tasks window.',
+        isError: true,
+      };
+    }
+
+    log.info({ selectorType, selectorValue: input[selectorType], resolvedWorkItemId: item.id }, 'resolved work item for update');
+
+    // Build updates from provided fields
+    const updates: Partial<{
+      priorityTier: number;
+      notes: string;
+      status: WorkItemStatus;
+      sortIndex: number;
+    }> = {};
+    if (input.priority_tier !== undefined) updates.priorityTier = input.priority_tier as number;
+    if (input.notes !== undefined) updates.notes = input.notes as string;
+    if (input.status !== undefined) updates.status = input.status as WorkItemStatus;
+    if (input.sort_index !== undefined) updates.sortIndex = input.sort_index as number;
+
+    if (Object.keys(updates).length === 0) {
+      log.warn({ selectorType, resolvedWorkItemId: item.id }, 'update called with no fields to update');
+      return {
+        content: 'No updates specified. Provide at least one field to update (priority_tier, notes, status, sort_index).',
+        isError: true,
+      };
+    }
+
+    const updated = updateWorkItem(item.id, updates);
+    if (!updated) {
+      log.error({ selectorType, resolvedWorkItemId: item.id, updates }, 'updateWorkItem returned null');
+      return {
+        content: `Error: Failed to update work item "${item.title}".`,
+        isError: true,
+      };
+    }
+
+    log.info({ resolvedWorkItemId: item.id, updatedFields: Object.keys(updates) }, 'work item updated');
+
+    // Build confirmation message
+    const parts: string[] = [`Updated "${updated.title}"`];
+    if (input.priority_tier !== undefined) {
+      parts.push(`priority → ${PRIORITY_LABELS[updated.priorityTier] ?? updated.priorityTier}`);
+    }
+    if (input.notes !== undefined) parts.push('notes updated');
+    if (input.status !== undefined) parts.push(`status → ${updated.status}`);
+    if (input.sort_index !== undefined) parts.push(`sort index → ${updated.sortIndex}`);
+
+    return { content: parts.join(', ') + '.', isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ selectorType, error: msg }, 'update failed');
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}