@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/mcp/taskPlanningRegistrar.js

@@ -33,68 +33,178 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                         type: 'object',
                         properties: descriptor.inputSchema.properties,
                         ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
+                        ...(descriptor.inputSchema.additionalProperties !== undefined
+                            ? { additionalProperties: descriptor.inputSchema.additionalProperties }
+                            : {}),
                     },
+                    ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
                 };
             },
             handler: bindDomainTool(executeTool, name),
         });
     };
+    register('scaffold_program', (context) => ({
+        description: context.describeTool('Preview or atomically create one bounded Initiative → Workstream → Task program with depends_on edges. Use dryRun=true first; commit requires idempotencyKey and exact retries return the original compact mapping.'),
+        annotations: { idempotentHint: true },
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                dryRun: booleanProperty('When true, validate through the real durable application path and roll back every write.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Required for commit. Opaque retry key scoped to the current caller and workspace.' },
+                initiative: {
+                    type: 'object', additionalProperties: false,
+                    properties: {
+                        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.'),
+                    },
+                    required: ['title'],
+                },
+                workstreams: {
+                    type: 'array', maxItems: 12,
+                    description: 'Ordered workstreams and their ordered tasks.',
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            key: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                            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.'),
+                            tasks: {
+                                type: 'array', maxItems: 50,
+                                items: {
+                                    type: 'object', additionalProperties: false,
+                                    properties: {
+                                        key: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                                        title: stringProperty('Task title.'),
+                                        description: stringProperty('Optional task description.'),
+                                        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),
+                                        scheduledDate: stringProperty('Optional schedule date (YYYY-MM-DD).'),
+                                        dueDate: stringProperty('Optional due date (YYYY-MM-DD).'),
+                                    },
+                                    required: ['key', 'title'],
+                                },
+                            },
+                        },
+                        required: ['key', 'title', 'tasks'],
+                    },
+                },
+                dependencies: {
+                    type: 'array', maxItems: 100,
+                    description: 'Depends-on edges between task keys.',
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            taskKey: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                            dependsOnTaskKey: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                        },
+                        required: ['taskKey', 'dependsOnTaskKey'],
+                    },
+                },
+            },
+            required: ['dryRun', 'initiative', 'workstreams', 'dependencies'],
+        },
+    }));
     register('list_tasks', (context) => ({
-        description: context.describeTool('List active tasks with optional filters. Supports filtering by status, assignee, priority, type, and category. Use openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Default sort is by created date descending. Returns a compact summary of each task — description, comments, and activity are omitted to keep responses concise. Use get_task to retrieve full details for a specific task.'),
+        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.`),
+                assignee: stringProperty(context.assigneeHint),
                 priority: numberProperty('Filter by priority level.'),
                 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).'),
             },
         },
     }));
     register('search_tasks', (context) => ({
-        description: context.describeTool('Search active and archived tasks by keyword. Matches against title, description, and ID. 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. 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 (matches title, description, internal ID, or task reference such as T-123).'),
+                query: stringProperty('Search term or exact task reference such as T-123 or LT-123.'),
                 scope: stringProperty('Search scope (default: all).', ['all', 'active', 'archive']),
             },
             required: ['query'],
         },
     }));
+    register('list_task_relationships', (context) => ({
+        description: context.describeTool('List structured dependency, related, and supersession relationships for one task. Returns compact task references; use this instead of attachment/document link tools.'),
+        inputSchema: { properties: {
+                taskId: stringProperty('Task ID or reference such as T-123.'),
+                type: stringProperty('Optional relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                direction: stringProperty('Optional stored-edge direction; default both.', ['outgoing', 'incoming', 'both']),
+            }, required: ['taskId'] },
+    }));
+    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.'),
+                type: stringProperty('Relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                profileToken: stringProperty('Optional profileToken for stateless MCP clients.'),
+            }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
+    }));
+    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.'),
+                type: stringProperty('Relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                profileToken: stringProperty('Optional profileToken for stateless MCP clients.'),
+            }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
+    }));
     register('get_task', (context) => ({
-        description: context.describeTool('Get one task by ID or T-123 reference, including comments, activity, checklist, links, and attachment metadata. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images.'),
+        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: compact, full, or chronological history.', ['compact', 'full', 'history']),
             },
             required: ['id'],
         },
     }));
     register('list_initiatives', (context) => ({
-        description: context.describeTool('List initiatives for the active workspace. Returns initiative records with attached workstream summaries and task counts so AI agents can reason about the planning model directly.'),
-        inputSchema: { properties: {} },
+        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.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Optional search term for initiative title, description, ID/reference such as IN-123, owner, or linked workstream title.'),
+            },
+        },
     }));
     register('get_initiative', (context) => ({
-        description: context.describeTool('Get a single initiative by ID or initiative reference such as IN-123. Returns the initiative plus its workstreams and rolled-up task counts.'),
+        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: 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.`),
+                ownerId: stringProperty(context.assigneeHint),
                 order: numberProperty('Optional sort order among initiatives.'),
                 attachments: arrayProperty('Optional attachment descriptors to store on the initiative. Prefer save_initiative_attachment for generated content or files.', {
                     type: 'object',
@@ -108,6 +218,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'],
         },
@@ -119,9 +230,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.`),
+                ownerId: stringProperty(context.assigneeHint),
                 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.', {
+                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' },
@@ -137,6 +248,17 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
+    register('add_initiative_comment', (context) => ({
+        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'],
+        },
+    }));
     register('archive_initiative', (context) => ({
         description: context.describeTool('Archive an initiative without deleting it. This hides it from open planning views while preserving its workstreams and history.'),
         inputSchema: {
@@ -156,25 +278,32 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('list_workstreams', (context) => ({
-        description: context.describeTool('List workstreams for the active workspace. Returns workstream records with attached task summaries and linked initiative information when present.'),
-        inputSchema: { properties: {} },
+        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.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Optional search term for workstream title, description, ID/reference such as WS-123, owner, or linked initiative title/reference.'),
+            },
+        },
     }));
     register('get_workstream', (context) => ({
-        description: context.describeTool('Get a single workstream by ID or workstream reference such as WS-123. Returns the workstream plus its tasks.'),
+        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: 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.'),
                 attachments: arrayProperty('Optional attachment descriptors to store on the workstream. Prefer save_workstream_attachment for generated content or files.', {
@@ -189,6 +318,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'],
         },
@@ -200,10 +330,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.', {
+                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' },
@@ -219,6 +349,17 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
+    register('add_workstream_comment', (context) => ({
+        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'],
+        },
+    }));
     register('archive_workstream', (context) => ({
         description: context.describeTool('Archive a workstream without deleting it. This hides it from open planning views while preserving its linked tasks.'),
         inputSchema: {
@@ -239,6 +380,7 @@ 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.'),
@@ -266,16 +408,31 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['taskId'],
         },
     }));
+    register('add_task_checklist_item', (context) => ({
+        description: context.describeTool('Append one structured checklist item to a task. Use this when a user asks to add a checklist item without replacing the existing checklist.'),
+        inputSchema: {
+            properties: {
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
+                text: stringProperty('Checklist item text to append. Must be descriptive, not a placeholder.'),
+                done: { type: 'boolean', description: 'Whether the new checklist item is already complete.' },
+            },
+            required: ['taskId', 'text'],
+        },
+    }));
     register('replace_task_checklist', (context) => ({
-        description: context.describeTool('Replace the structured checklist items for one task with a new ordered list.'),
+        description: context.describeTool('Replace the structured checklist items for one task with a new ordered list. Use this when a user explicitly asks to create, update, or replace a task checklist; do not just draft checklist text.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
                 items: arrayProperty('Ordered checklist items to persist.', {
                     type: 'object',
                     properties: {
+                        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.' },
+                        createdAt: { type: 'string', description: 'Optional canonical ISO creation timestamp.' },
+                        updatedAt: { type: 'string', description: 'Optional canonical ISO last-change timestamp.' },
                     },
                     required: ['text'],
                 }),
@@ -285,20 +442,25 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('get_schedule_board', (context) => ({
         description: context.describeTool('Read the current schedule board for the active workspace. Use this before scheduling tasks when you need the existing day layout and order.'),
-        inputSchema: { properties: {} },
+        inputSchema: {
+            properties: {
+                week: stringProperty('Optional ISO week key such as 2026-W29. Defaults to the current week.'),
+                showWeekends: booleanProperty('When true, include weekends in the returned board.'),
+            },
+        },
     }));
     register('update_schedule', (context) => ({
         description: context.describeTool('Default schedule write path. Schedule, unschedule, or reorder scheduled tasks. Pass taskId with date to schedule, taskId with date=null or an empty string to unschedule, or pass date plus taskIds to replace one day order. Use get_schedule_board first when you need the current board state.'),
         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.'),
+                id: stringProperty('Alias for taskId.'),
+                date: nullableStringProperty('YYYY-MM-DD; null or empty with taskId unschedules.'),
+                scheduledDate: nullableStringProperty('Alias for date.'),
                 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.', {
+                orderInDay: numberProperty('Alias for order.'),
+                taskIds: arrayProperty('Ordered task IDs or references replacing one day.', { type: 'string' }),
+                moves: arrayProperty('Advanced reorder moves using task, date, and order aliases.', {
                     type: 'object',
                     properties: {
                         id: { type: 'string' },
@@ -322,34 +484,58 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         description: context.describeTool('Extended precision tool for carrying unfinished scheduled tasks forward from one day or week to another in bulk. Use get_schedule_board first to inspect the source period.'),
         inputSchema: {
             properties: {
-                fromDate: stringProperty('Source date in YYYY-MM-DD format.'),
-                toDate: stringProperty('Destination date in YYYY-MM-DD format.'),
-                preserveCompleted: booleanProperty('When true, leave completed tasks on the source date.'),
+                fromWeek: stringProperty('Source ISO week key such as 2026-W29.'),
+                toWeek: stringProperty('Destination ISO week key such as 2026-W30.'),
+                mode: stringProperty('Carryover interval.', ['day', 'week']),
+                includeStatuses: arrayProperty('Optional active task statuses to carry over.', {
+                    type: 'string',
+                    enum: ['task', 'in-progress', 'review', 'on-hold'],
+                }),
             },
-            required: ['fromDate', 'toDate'],
+            required: ['fromWeek', 'toWeek', 'mode'],
         },
     }));
     register('set_schedule_preferences', (context) => ({
         description: context.describeTool('Update schedule board display and planning preferences for the current session.'),
         inputSchema: {
             properties: {
-                weekStartsOn: numberProperty('Week start day index, where 0 is Sunday and 1 is Monday.'),
                 showWeekends: booleanProperty('When true, include weekends in schedule views.'),
+                isCalendarSidebarOpen: booleanProperty('Whether the calendar sidebar is open.'),
+                weekStartsOn: stringProperty('First day of the schedule week.', ['sunday', 'monday']),
+                dailyCapacity: {
+                    type: 'object',
+                    description: 'Optional per-day capacity settings.',
+                    properties: {
+                        monday: { type: 'number', minimum: 0 },
+                        tuesday: { type: 'number', minimum: 0 },
+                        wednesday: { type: 'number', minimum: 0 },
+                        thursday: { type: 'number', minimum: 0 },
+                        friday: { type: 'number', minimum: 0 },
+                        saturday: { type: 'number', minimum: 0 },
+                        sunday: { type: 'number', minimum: 0 },
+                    },
+                    additionalProperties: false,
+                },
             },
         },
     }));
     register('create_task', (context) => ({
-        description: context.describeTool('Create a new task. Use get_config first so category, type, priority, approach, status, and complexity values match the active workspace taxonomy.'),
+        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.'),
+                idempotencyKey: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 128,
+                    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.'),
-                category: stringProperty('Task category value.'),
+                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),
-                approach: stringProperty('Task approach value.', context.approachEnum),
                 status: stringProperty('Initial task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 complexity: numberProperty(context.complexityDesc),
                 scheduledDate: stringProperty('Optional scheduled date in YYYY-MM-DD format.'),
@@ -367,18 +553,28 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
+    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.'),
+            },
+            required: ['id'],
+        },
+    }));
     register('update_task', (context) => ({
-        description: context.describeTool('Update an existing task. Use get_config first for taxonomy-backed fields. Use start_task when beginning active work on a tracked task, and prefer finish_task for the final completion or review handoff.'),
+        description: context.describeTool('Update an existing task. Current taxonomy values are included in this tool schema; call get_config only for richer metadata or after a validation mismatch. Use start_task when beginning active work on a tracked task, and prefer finish_task for the final completion or review handoff.'),
         inputSchema: {
             properties: {
                 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.`),
-                category: stringProperty('Updated category value.'),
+                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),
-                approach: stringProperty('Updated task approach value.', context.approachEnum),
                 status: stringProperty('Updated task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 complexity: numberProperty(context.complexityDesc),
                 scheduledDate: stringProperty('Updated scheduled date in YYYY-MM-DD format. Pass an empty string to clear.'),
@@ -388,14 +584,14 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('finish_task', (context) => ({
-        description: context.describeTool('default end-of-task handoff. Use outcome=\'done\' when work is complete and no explicit human action is requested. Use 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. This tool never archives automatically.'),
+        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.'),
                 outcome: stringProperty('Completion outcome.', ['review', 'done']),
-                comment: stringProperty('Optional completion note to add as a task comment.'),
+                comment: stringProperty('Optional completion note returned in the handoff response.'),
             },
-            required: ['id'],
+            required: ['id', 'outcome'],
         },
     }));
     register('archive_task', (context) => ({

package/dist/mcp/toolCallCompatibility.d.ts

@@ -0,0 +1,6 @@
+export type ResolvedMcpToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export declare function resolveCanonicalMcpToolName(nameRaw: unknown): string;
+export declare function resolveMcpToolCallCompatibility(nameRaw: unknown, argsRaw: unknown): ResolvedMcpToolCall;

package/dist/mcp/toolCallCompatibility.js

@@ -0,0 +1,16 @@
+const LEGACY_TOOL_NAME_ALIASES = Object.freeze({
+    // Kept callable for connector hosts that cached the pre-T-684 contract.
+    // Do not advertise this alias from tools/list; get_task_attachments is canonical.
+    read_task_attachment: 'get_task_attachments',
+});
+export function resolveCanonicalMcpToolName(nameRaw) {
+    const name = String(nameRaw || '').trim();
+    return LEGACY_TOOL_NAME_ALIASES[name] || name;
+}
+export function resolveMcpToolCallCompatibility(nameRaw, argsRaw) {
+    const name = resolveCanonicalMcpToolName(nameRaw);
+    const args = argsRaw && typeof argsRaw === 'object' && !Array.isArray(argsRaw)
+        ? argsRaw
+        : {};
+    return { name, arguments: args };
+}

package/dist/mcp/toolCatalog.d.ts

@@ -3,6 +3,7 @@ export type McpToolInputSchema = {
     type: 'object';
     properties?: Record<string, unknown>;
     required?: string[];
+    additionalProperties?: boolean;
 };
 export type McpToolDescriptor = {
     name: McpToolName;
@@ -17,11 +18,12 @@ export type McpToolDescriptor = {
     };
 };
 export type McpToolDescriptorContext = {
+    runtimeMode: 'local' | 'cloud';
     describeTool: (text: string) => string;
     assigneeHint: string;
+    categoryEnum: string[];
     priorityDesc: string;
     typeEnum: string[];
-    approachEnum: string[];
     complexityDesc: string;
 };
 export type McpToolHandlerResult = {

package/dist/mcp/toolProfiles.d.ts

@@ -1,7 +1,18 @@
-import { type McpToolName, type McpToolProfile, type McpToolSuccessor } from './toolRegistry.js';
+import { type McpPermission, type McpToolName, type McpToolProfile, type McpToolSuccessor } from './toolRegistry.js';
+export declare const MCP_MANAGED_AGENT_DEFAULT_PROFILE: "managed-agent-default";
+export type ManagedAgentMcpToolProfile = typeof MCP_MANAGED_AGENT_DEFAULT_PROFILE;
+type McpScopedPermission = Extract<McpPermission, {
+    kind: 'scope';
+}>;
+type McpScope = McpScopedPermission['scope'];
 export declare function normalizeMcpToolProfile(value: unknown, fallback: McpToolProfile): McpToolProfile;
 export declare function getDefaultMcpToolProfile(runtimeMode: 'local' | 'cloud'): McpToolProfile;
 export declare function isMcpToolVisibleInProfile(name: string, profile: McpToolProfile): boolean;
 export declare function getMcpToolRequiredProfiles(name: string): McpToolProfile[];
 export declare function getMcpToolProfileMembership(profile: McpToolProfile): McpToolName[];
+export declare function getManagedAgentMcpRuntimeProfile(_profile?: ManagedAgentMcpToolProfile): McpToolProfile;
+export declare function getManagedAgentMcpToolProfileMembership(profile?: ManagedAgentMcpToolProfile): McpToolName[];
+export declare function getManagedAgentMcpToolScopes(profile?: ManagedAgentMcpToolProfile): McpScope[];
+export declare function isMcpToolVisibleInManagedAgentProfile(name: string, profile?: ManagedAgentMcpToolProfile): boolean;
 export declare function getMcpToolSuccessor(name: string): McpToolSuccessor | null;
+export {};