@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/mcp/taskAttachmentCommandAdapter.d.ts

@@ -52,6 +52,7 @@ export interface SaveTaskAttachmentInput {
     sizeBytes?: unknown;
     expectedSizeBytes?: unknown;
     expectedSha256?: unknown;
+    displayName?: unknown;
     caption?: unknown;
     overwrite?: unknown;
     overwriteAssetId?: unknown;
@@ -69,6 +70,7 @@ export type SaveTaskAttachmentResult = {
     expiresAt: string;
     uploadUrl: string;
     uploadedPath: string;
+    displayName?: string;
     caption?: string;
     overwrite: boolean;
     expectedSizeBytes?: unknown;

package/dist/mcp/taskAttachmentCommandAdapter.js

@@ -20,7 +20,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
     return {
         buildAttachmentResponse,
         async save(input) {
-            const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, expectedSizeBytes, expectedSha256, caption, overwrite = false, overwriteAssetId, } = input;
+            const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, expectedSizeBytes, expectedSha256, displayName, caption, overwrite = false, overwriteAssetId, } = input;
             const { id, task } = deps.resolveTask(inputId);
             const durableAttachmentLinksEnabled = deps.durableAttachmentLinksEnabled(id);
             if (!filename || typeof filename !== 'string')
@@ -38,6 +38,9 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 ? caption.trim()
                 : undefined;
             const safeFilename = deps.sanitizeFilename(filename);
+            const safeDisplayName = typeof displayName === 'string' && displayName.trim().length > 0
+                ? displayName.trim()
+                : safeFilename;
             const stableAttachmentAssetId = deps.stableRequestId('operation', `task-attachment-asset:${id}:${safeFilename}`)?.replace(/^operation-/, 'asset-') || `asset-${randomUUID().replace(/-/g, '')}`;
             const safeMimeType = typeof mimeType === 'string' && mimeType.trim().length > 0
                 ? mimeType.trim().toLowerCase()
@@ -53,7 +56,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
@@ -63,7 +66,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                         : `/api/taskforce/context/${encodeURIComponent(storageKey)}`),
                     fsPath: asset?.storageKey || overwriteTarget?.attachment.fsPath || storageKey,
                     caption: isMarkdownDocument ? canonicalName : persistedCaption,
-                    displayName: isMarkdownDocument ? canonicalName : safeFilename,
+                    displayName: safeDisplayName,
                     originalFilename: safeFilename,
                     ...(asset?.assetId ? { assetId: asset.assetId } : {}),
                     timestamp: now,
@@ -110,6 +113,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                     expiresAt,
                     uploadUrl: objectStorageClient.createSignedPutUrl(stagedAsset.relativePath, uploadExpiresInSeconds, safeMimeType),
                     uploadedPath: stagedAsset.relativePath,
+                    ...(safeDisplayName !== safeFilename ? { displayName: safeDisplayName } : {}),
                     ...(safeCaption ? { caption: safeCaption } : {}),
                     overwrite: overwrite === true,
                     ...(expectedSizeBytes !== undefined ? { expectedSizeBytes } : {}),
@@ -218,7 +222,8 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName
+                    || existingUploadedAsset?.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
@@ -234,7 +239,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                     assetId: overwriteTarget?.asset.assetId || existingUploadedAsset?.assetId || embeddedAssetId || `asset-${randomUUID().replace(/-/g, '')}`,
                     workspaceId: deps.activeWorkspaceId,
                     kind,
-                    logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                    logicalName: canonicalName,
                     originalFilename: safeFilename,
                     mimeType: resolvedMimeType,
                     storageProvider: 'r2',
@@ -269,7 +274,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                         assetId: asset.assetId,
                         taskId: id,
                         role: 'attachment',
-                        displayName: kind === 'document' ? null : persistedCaption,
+                        displayName: kind === 'document' ? null : safeDisplayName,
                         updatedAt: now,
                         deletedAt: null,
                     });
@@ -324,13 +329,14 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
                 asset = await deps.canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
                     originalFilename: safeFilename,
-                    logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                    logicalName: canonicalName,
+                    displayName: safeDisplayName,
                     ...(!overwriteTarget ? { assetId: stableAttachmentAssetId } : {}),
                     ...(overwriteTarget
                         ? {

package/dist/mcp/taskPlanningRegistrar.js

@@ -11,8 +11,16 @@ function nullableStringProperty(description) {
         ],
     };
 }
-function numberProperty(description) {
-    return { type: 'number', description };
+function integerProperty(description, minimum, maximum) {
+    return {
+        type: 'integer',
+        description,
+        ...(minimum === undefined ? {} : { minimum }),
+        ...(maximum === undefined ? {} : { maximum }),
+    };
+}
+function integerEnumProperty(description, values) {
+    return { type: 'integer', description, enum: values };
 }
 function booleanProperty(description) {
     return { type: 'boolean', description };
@@ -57,7 +65,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                         title: stringProperty('Initiative title.'),
                         description: stringProperty('Optional initiative description.'),
                         ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
-                        order: numberProperty('Optional initiative order.'),
+                        order: integerProperty('Optional non-negative initiative order.', 0),
                     },
                     required: ['title'],
                 },
@@ -71,7 +79,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                             title: stringProperty('Workstream title.'),
                             description: stringProperty('Optional workstream description.'),
                             ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
-                            order: numberProperty('Optional workstream order.'),
+                            order: integerProperty('Optional non-negative workstream order.', 0),
                             tasks: {
                                 type: 'array', maxItems: 50,
                                 items: {
@@ -83,8 +91,8 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                                         assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
                                         category: stringProperty('Task category.', context.categoryEnum),
                                         type: stringProperty('Task type.', context.typeEnum),
-                                        priority: numberProperty(context.priorityDesc),
-                                        complexity: numberProperty(context.complexityDesc),
+                                        priority: integerEnumProperty(context.priorityDesc, context.priorityEnum),
+                                        complexity: integerProperty(context.complexityDesc, 1, 5),
                                         scheduledDate: stringProperty('Optional schedule date (YYYY-MM-DD).'),
                                         dueDate: stringProperty('Optional due date (YYYY-MM-DD).'),
                                     },
@@ -112,30 +120,32 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('list_tasks', (context) => ({
-        description: context.describeTool('List active tasks with optional filters, including workstreamId (an ID or WS-123 reference). Use offset and limit for bounded pagination. Use openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Returns compact task summaries without descriptions, comments, activity, attachments, or event streams. When a task URL is provided, preserve it when presenting the task so the user can open it directly. Use get_task for one task’s details.'),
+        description: context.describeTool('List active tasks with filters and bounded pagination. Use workstreamId with an ID or WS-123 and openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Returns compact summaries; use get_task for details. When a task URL is returned, preserve it when presenting the task.'),
         inputSchema: {
             properties: {
                 format: stringProperty('Toggle output format (default: markdown).', ['markdown', 'json']),
                 category: stringProperty('Filter by category.'),
                 status: stringProperty('Filter by status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 openOnly: booleanProperty('When true, only include open tasks (task, on-hold, in-progress, review).'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                priority: numberProperty('Filter by priority level.'),
+                assignee: stringProperty(context.assigneeHint),
+                priority: integerEnumProperty(context.priorityDesc, context.priorityEnum),
                 type: stringProperty('Filter by task type.', context.typeEnum),
                 workstreamId: stringProperty('Filter by workstream ID or workstream reference such as WS-123.'),
                 sort: stringProperty('Sort field (default: created).', ['priority', 'created', 'updated']),
                 order: stringProperty('Sort order (default: desc).', ['asc', 'desc']),
-                limit: numberProperty('Max tasks to return.'),
-                offset: numberProperty('Non-negative result offset for pagination (default: 0).'),
+                limit: integerProperty('Max tasks to return (max 200).', 1, 200),
+                offset: integerProperty('Non-negative result offset for pagination (default: 0).', 0),
             },
         },
     }));
     register('search_tasks', (context) => ({
-        description: context.describeTool('Search active and archived tasks by keyword or exact task reference. Matches title, description, internal ID, canonical T-* references, and provisional local LT-* references. Results use linked task references when an application URL is available; preserve those links when presenting tasks. Use scope=\'active\' or scope=\'archive\' to narrow results. Prefer this over list_tasks when looking for a specific task by name.'),
+        description: context.describeTool('Search active and archived tasks by keyword, ID, T-* reference, or provisional LT-* reference. Use scope to narrow results and offset/limit to continue broad searches. Prefer this over list_tasks when looking for a specific task by name. When results include links, preserve those links when presenting tasks.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Search term or exact task reference such as T-123 or LT-123.'),
                 scope: stringProperty('Search scope (default: all).', ['all', 'active', 'archive']),
+                limit: integerProperty('Page size (default 25; max 50).', 1, 50),
+                offset: integerProperty('Non-negative result offset (default 0).', 0),
             },
             required: ['query'],
         },
@@ -150,6 +160,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('link_task_relationship', (context) => ({
         description: context.describeTool('Create an idempotent structured relationship between two tasks. blocks(A,B) is the inverse view of depends_on(B,A). Rejects self-links, missing tasks, and dependency/supersession cycles.'),
+        annotations: { idempotentHint: true },
         inputSchema: { properties: {
                 sourceTaskId: stringProperty('Source task ID or reference.'),
                 targetTaskId: stringProperty('Target task ID or reference.'),
@@ -159,6 +170,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('unlink_task_relationship', (context) => ({
         description: context.describeTool('Idempotently remove a structured task relationship. The relationship is tombstoned so deletion converges across sync.'),
+        annotations: { idempotentHint: true },
         inputSchema: { properties: {
                 sourceTaskId: stringProperty('Source task ID or reference.'),
                 targetTaskId: stringProperty('Target task ID or reference.'),
@@ -167,43 +179,45 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
     }));
     register('get_task', (context) => ({
-        description: context.describeTool('Get one task by ID or T-123 reference. The default compact response returns scalar task fields and collection counts without comments, history, checklist items, or attachments. When the response includes url, preserve it in any task reference you present so the user can open the task directly. Pass detail=full for comments and attachment/checklist metadata, or detail=history for one chronological comment/event stream. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images. When showing this task to the user in a client that supports rich inline rendering, prefer a compact visual summary that retains the task link.'),
+        description: context.describeTool('Get one task by ID or T-123 reference. The default compact response returns scalar fields and collection counts. Use detail=full for comments and attachment/checklist metadata, or detail=history for chronology. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images. When url is returned, preserve it in any task reference you present.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
-                detail: stringProperty('Response detail level (default: compact). Use full for comments and attachment/checklist metadata, or history for chronological task events.', ['compact', 'full', 'history']),
+                detail: stringProperty('Response detail: compact, full, or chronological history.', ['compact', 'full', 'history']),
             },
             required: ['id'],
         },
     }));
     register('list_initiatives', (context) => ({
-        description: context.describeTool('List or search initiatives for the active workspace. Pass query to search by initiative title, description, ID/reference, owner, or linked workstream title. Returns compact initiative summaries with workstream and task counts.'),
+        description: context.describeTool('List or search initiatives for the active workspace. Pass query to search by initiative title, description, ID/reference, owner, or linked workstream title. Use offset/limit to continue through compact summaries.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Optional search term for initiative title, description, ID/reference such as IN-123, owner, or linked workstream title.'),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Non-negative result offset (default 0).' },
             },
         },
     }));
     register('get_initiative', (context) => ({
-        description: context.describeTool('Get one initiative by ID or IN-123 reference. The default compact response returns summary counts. Use detail=planning for current attachments plus paginated active/archived workstream summaries and historical task counts, detail=history for bounded chronological history, or detail=full for the compatible rich response.'),
+        description: context.describeTool('Get one initiative by ID or IN-123. Compact returns counts; detail=planning adds attachments, paginated workstreams, and historical task counts; detail=history returns bounded chronology; full returns the compatible rich response.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
-                detail: stringProperty('Response detail level (default: compact). Planning excludes history; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
-                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for planning workstreams or history entries (default: 25, max: 100).' },
-                offset: { type: 'integer', minimum: 0, description: 'Non-negative page offset for planning workstreams or history entries (default: 0).' },
+                detail: stringProperty('Response detail: compact, planning, history, or full.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Planning/history page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Planning/history page offset (default 0).' },
             },
             required: ['id'],
         },
     }));
     register('create_initiative', (context) => ({
-        description: context.describeTool('Create a new initiative. Use this for the top planning layer when a body of work should coordinate multiple workstreams.'),
+        description: context.describeTool('Create a new initiative. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same payload.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Initiative title.'),
                 description: stringProperty('Optional initiative description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                order: numberProperty('Optional sort order among initiatives.'),
+                ownerId: stringProperty(context.assigneeHint),
+                order: integerProperty('Optional non-negative sort order among initiatives.', 0),
                 attachments: arrayProperty('Optional attachment descriptors to store on the initiative. Prefer save_initiative_attachment for generated content or files.', {
                     type: 'object',
                     properties: {
@@ -216,6 +230,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     },
                     required: ['path'],
                 }),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['title'],
         },
@@ -227,9 +242,9 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 title: stringProperty('Updated initiative title.'),
                 description: stringProperty('Updated initiative description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                order: numberProperty('Optional sort order among initiatives.'),
-                attachments: arrayProperty('Replacement attachment descriptors for the initiative. Prefer save_initiative_attachment and delete_initiative_attachment for generated content or files.', {
+                ownerId: stringProperty(context.assigneeHint),
+                order: integerProperty('Optional non-negative sort order among initiatives.', 0),
+                attachments: arrayProperty('Replacement attachment descriptors for the initiative. Prefer save_initiative_attachment for generated content or files. Removing managed attachments requires delete_initiative_attachment in the extended profile.', {
                     type: 'object',
                     properties: {
                         path: { type: 'string' },
@@ -246,11 +261,12 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('add_initiative_comment', (context) => ({
-        description: context.describeTool('Add a comment to an initiative. Use this for initiative-level progress notes, decisions, coordination context, and audit trails. Comments appear in the initiative activity feed.'),
+        description: context.describeTool('Add a comment to an initiative. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same target and text.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 text: stringProperty('Comment text.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['id', 'text'],
         },
@@ -274,34 +290,36 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('list_workstreams', (context) => ({
-        description: context.describeTool('List or search workstreams for the active workspace. Pass query to search by workstream title, description, ID/reference, owner, or linked initiative title/reference. Returns compact workstream summaries with task counts.'),
+        description: context.describeTool('List or search workstreams for the active workspace. Pass query to search by workstream title, description, ID/reference, owner, or linked initiative title/reference. Use offset/limit to continue through compact summaries.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Optional search term for workstream title, description, ID/reference such as WS-123, owner, or linked initiative title/reference.'),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Non-negative result offset (default 0).' },
             },
         },
     }));
     register('get_workstream', (context) => ({
-        description: context.describeTool('Get one workstream by ID or WS-123 reference. The default compact response returns a summary and task count. Use detail=planning for current attachments and explicit historical task counts without nested tasks, detail=history for bounded chronological history, or detail=full for the compatible rich response. Use list_tasks with workstreamId for bounded active task discovery.'),
+        description: context.describeTool('Get one workstream by ID or WS-123. Compact returns a summary and task count; detail=planning adds attachments and historical counts; detail=history returns bounded chronology; full returns the compatible rich response. Use list_tasks with workstreamId for active tasks.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-                detail: stringProperty('Response detail level (default: compact). Planning excludes history and nested tasks; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
-                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for history entries (default: 25, max: 100).' },
-                offset: { type: 'integer', minimum: 0, description: 'Non-negative history page offset (default: 0).' },
+                detail: stringProperty('Response detail: compact, planning, history, or full.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'History page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'History page offset (default 0).' },
             },
             required: ['id'],
         },
     }));
     register('create_workstream', (context) => ({
-        description: context.describeTool('Create a new workstream. Use initiativeId to link it to an initiative, or omit initiativeId to create a standalone workstream.'),
+        description: context.describeTool('Create a new workstream. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same payload.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Workstream title.'),
                 description: stringProperty('Optional workstream description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 initiativeId: stringProperty('Optional initiative ID or initiative reference such as IN-123.'),
-                order: numberProperty('Optional sort order among workstreams.'),
+                order: integerProperty('Optional non-negative sort order among workstreams.', 0),
                 attachments: arrayProperty('Optional attachment descriptors to store on the workstream. Prefer save_workstream_attachment for generated content or files.', {
                     type: 'object',
                     properties: {
@@ -314,6 +332,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     },
                     required: ['path'],
                 }),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['title'],
         },
@@ -325,10 +344,10 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 title: stringProperty('Updated workstream title.'),
                 description: stringProperty('Updated workstream description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 initiativeId: stringProperty('Optional initiative ID or initiative reference such as IN-123. Pass an empty string to unlink.'),
-                order: numberProperty('Optional sort order among workstreams.'),
-                attachments: arrayProperty('Replacement attachment descriptors for the workstream. Prefer save_workstream_attachment and delete_workstream_attachment for generated content or files.', {
+                order: integerProperty('Optional non-negative sort order among workstreams.', 0),
+                attachments: arrayProperty('Replacement attachment descriptors for the workstream. Prefer save_workstream_attachment for generated content or files. Removing managed attachments requires delete_workstream_attachment in the extended profile.', {
                     type: 'object',
                     properties: {
                         path: { type: 'string' },
@@ -345,11 +364,12 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('add_workstream_comment', (context) => ({
-        description: context.describeTool('Add a comment to a workstream. Use this for workstream-level progress notes, decisions, coordination context, and audit trails. Comments appear in the workstream activity feed.'),
+        description: context.describeTool('Add a comment to a workstream. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same target and text.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 text: stringProperty('Comment text.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['id', 'text'],
         },
@@ -374,12 +394,13 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('update_task_workstream', (context) => ({
         description: context.describeTool('Set or clear the workstream for one task. Pass workstreamId to assign or reassign; pass an empty string or null to unlink the task from its current workstream.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
-                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
                 workstreamId: nullableStringProperty('Workstream ID or workstream reference such as WS-123. Pass an empty string or null to unlink.'),
             },
+            required: ['taskId', 'workstreamId'],
         },
     }));
     register('update_workstream_initiative', (context) => ({
@@ -387,9 +408,9 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-                id: stringProperty('Alias for workstreamId. Workstream ID or workstream reference such as WS-123.'),
                 initiativeId: nullableStringProperty('Initiative ID or initiative reference such as IN-123. Pass an empty string or null to unlink.'),
             },
+            required: ['workstreamId', 'initiativeId'],
         },
     }));
     register('get_task_checklist', (context) => ({
@@ -423,7 +444,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                         id: { type: 'string', description: 'Stable checklist item ID. Reuse it when reordering or updating an existing item.' },
                         text: { type: 'string' },
                         done: { type: 'boolean' },
-                        order: { type: 'number', description: 'Optional zero-based display order.' },
+                        order: { type: 'integer', minimum: 0, description: 'Optional zero-based display order.' },
                         createdAt: { type: 'string', description: 'Optional canonical ISO creation timestamp.' },
                         updatedAt: { type: 'string', description: 'Optional canonical ISO last-change timestamp.' },
                     },
@@ -447,28 +468,17 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
-                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
-                date: nullableStringProperty('Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
-                scheduledDate: nullableStringProperty('Alias for date. Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
-                order: numberProperty('Optional position within that day.'),
-                orderInDay: numberProperty('Alias for order. Optional position within that day.'),
-                taskIds: arrayProperty('Ordered task IDs or task references for replacing one scheduled day order.', { type: 'string' }),
-                moves: arrayProperty('Advanced reorder moves. Each move may include id or taskId, date or scheduledDate, and order or orderInDay.', {
+                date: nullableStringProperty('YYYY-MM-DD; null or empty with taskId unschedules.'),
+                order: integerProperty('Optional non-negative position within that day.', 0),
+                taskIds: arrayProperty('Ordered task IDs or references replacing one day.', { type: 'string' }),
+                moves: arrayProperty('Advanced reorder moves using canonical taskId, date, and order fields.', {
                     type: 'object',
                     properties: {
-                        id: { type: 'string' },
                         taskId: { type: 'string' },
                         date: { type: 'string' },
-                        scheduledDate: { type: 'string' },
-                        order: { type: 'number' },
-                        orderInDay: { type: 'number' },
+                        order: { type: 'integer', minimum: 0 },
                     },
-                    anyOf: [
-                        { required: ['id', 'date'] },
-                        { required: ['id', 'scheduledDate'] },
-                        { required: ['taskId', 'date'] },
-                        { required: ['taskId', 'scheduledDate'] },
-                    ],
+                    required: ['taskId', 'date'],
                 }),
             },
         },
@@ -513,7 +523,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('create_task', (context) => ({
-        description: context.describeTool('Create a new task. Pass idempotencyKey when the call may be retried after a timeout; the same key and payload return the original task, while a changed payload is rejected. Current taxonomy values are included in this schema; call get_config only for richer metadata or after a validation mismatch.'),
+        description: context.describeTool('Create a task. For retries, the same idempotencyKey and payload return the original; changed payloads conflict. Taxonomy enums are current; use get_config for metadata or after validation errors.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Task title.'),
@@ -524,13 +534,13 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     description: 'Optional opaque retry key scoped to the active workspace and AI profile.',
                 },
                 description: stringProperty('Optional task description.'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                workstreamId: stringProperty('Optional workstream ID or workstream reference such as WS-123. Use this to create the task directly inside a workstream without a separate update_task_workstream call. Call list_workstreams with query first if you only know the workstream name.'),
+                assignee: stringProperty(context.assigneeHint),
+                workstreamId: stringProperty('Workstream ID or WS-123; use to create the task directly inside a workstream. Search list_workstreams if needed.'),
                 category: stringProperty('Task category value.', context.categoryEnum),
                 type: stringProperty('Task type value.', context.typeEnum),
-                priority: numberProperty(context.priorityDesc),
+                priority: integerEnumProperty(context.priorityDesc, context.priorityEnum),
                 status: stringProperty('Initial task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
-                complexity: numberProperty(context.complexityDesc),
+                complexity: integerProperty(context.complexityDesc, 1, 5),
                 scheduledDate: stringProperty('Optional scheduled date in YYYY-MM-DD format.'),
                 dueDate: stringProperty('Optional due date in YYYY-MM-DD format.'),
             },
@@ -548,6 +558,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('reopen_task', (context) => ({
         description: context.describeTool('Safely resume reviewed work in one call. Reopens archived done tasks or active/archived review tasks to in-progress, preserves an existing assignee, and claims only unassigned work. Cancelled tasks are rejected. Already in-progress tasks are idempotent no-ops.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
@@ -562,13 +573,13 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 title: stringProperty('Updated task title.'),
                 description: stringProperty('Updated task description.'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                assignee: stringProperty(context.assigneeHint),
                 workstreamId: stringProperty('Updated workstream ID or workstream reference such as WS-123. Pass an empty string to unlink the task. Call list_workstreams with query first if you only know the workstream name.'),
                 category: stringProperty('Updated category value.', context.categoryEnum),
                 type: stringProperty('Updated task type value.', context.typeEnum),
-                priority: numberProperty(context.priorityDesc),
+                priority: integerEnumProperty(context.priorityDesc, context.priorityEnum),
                 status: stringProperty('Updated task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
-                complexity: numberProperty(context.complexityDesc),
+                complexity: integerProperty(context.complexityDesc, 1, 5),
                 scheduledDate: stringProperty('Updated scheduled date in YYYY-MM-DD format. Pass an empty string to clear.'),
                 dueDate: stringProperty('Updated due date in YYYY-MM-DD format. Pass an empty string to clear.'),
             },
@@ -576,7 +587,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('finish_task', (context) => ({
-        description: context.describeTool('default end-of-task handoff for active work. Archived tasks are rejected; call reopen_task first. Use outcome=\'done\' when work is complete and outcome=\'review\' when human validation or approval is needed. If you report completed work on a tracked task, either finish it with this tool or explain why it remains open. Both outcomes remain active and unarchived. This tool never archives automatically; use archive_task separately to move work to history. The response always reports completion.archived from persisted state.'),
+        description: context.describeTool('Default end-of-task handoff. Use outcome=\'done\' for completed work or outcome=\'review\' for validation. Both remain active and unarchived; use archive_task for history. Archived tasks require reopen_task first.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),

package/dist/mcp/toolCallCompatibility.js

@@ -10,7 +10,44 @@ export function resolveCanonicalMcpToolName(nameRaw) {
 export function resolveMcpToolCallCompatibility(nameRaw, argsRaw) {
     const name = resolveCanonicalMcpToolName(nameRaw);
     const args = argsRaw && typeof argsRaw === 'object' && !Array.isArray(argsRaw)
-        ? argsRaw
+        ? { ...argsRaw }
         : {};
+    const moveAlias = (alias, canonical) => {
+        if (args[canonical] === undefined && args[alias] !== undefined)
+            args[canonical] = args[alias];
+        delete args[alias];
+    };
+    if (name === 'get_image')
+        moveAlias('id', 'imageId');
+    if (name === 'get_image_annotations')
+        moveAlias('imageAssetId', 'imageId');
+    if (name === 'get_task_attachments')
+        moveAlias('id', 'taskId');
+    if (name === 'update_task_workstream')
+        moveAlias('id', 'taskId');
+    if (name === 'update_workstream_initiative')
+        moveAlias('id', 'workstreamId');
+    if (name === 'update_schedule') {
+        moveAlias('id', 'taskId');
+        moveAlias('scheduledDate', 'date');
+        moveAlias('orderInDay', 'order');
+        if (Array.isArray(args.moves)) {
+            args.moves = args.moves.map((move) => {
+                if (!move || typeof move !== 'object' || Array.isArray(move))
+                    return move;
+                const normalized = { ...move };
+                const normalizeMoveAlias = (alias, canonical) => {
+                    if (normalized[canonical] === undefined && normalized[alias] !== undefined) {
+                        normalized[canonical] = normalized[alias];
+                    }
+                    delete normalized[alias];
+                };
+                normalizeMoveAlias('id', 'taskId');
+                normalizeMoveAlias('scheduledDate', 'date');
+                normalizeMoveAlias('orderInDay', 'order');
+                return normalized;
+            });
+        }
+    }
     return { name, arguments: args };
 }

package/dist/mcp/toolCatalog.d.ts

@@ -22,6 +22,7 @@ export type McpToolDescriptorContext = {
     describeTool: (text: string) => string;
     assigneeHint: string;
     categoryEnum: string[];
+    priorityEnum: number[];
     priorityDesc: string;
     typeEnum: string[];
     complexityDesc: string;

package/dist/mcp/toolRegistry.js

@@ -52,10 +52,10 @@ export const MCP_TOOL_REGISTRY = Object.freeze({
     replace_task_checklist: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     get_task_attachments: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),
     get_workstream_attachments: extendedTool({ kind: 'scope', scope: 'tasks:read' }, false),
-    save_workstream_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
+    save_workstream_attachment: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     delete_workstream_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
     get_initiative_attachments: extendedTool({ kind: 'scope', scope: 'tasks:read' }, false),
-    save_initiative_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
+    save_initiative_attachment: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     delete_initiative_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
     search_images: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),
     get_image: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),