@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/mcp/runtime.js

@@ -1,6 +1,5 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { Server } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash, randomUUID } from 'node:crypto';
@@ -80,7 +79,7 @@ import { createDurableTaskChecklistMutationRouter, DurableTaskChecklistRouterInP
 import { DurableTaskChecklistMutationError } from '../sync/v3/taskChecklistMutationService.js';
 import { createDurableTaskAttachmentLinksMutationRouter, DurableTaskAttachmentLinksRouterInProgressError, } from '../sync/v3/durableTaskAttachmentLinksMutationRouter.js';
 import { DurableTaskAttachmentLinksMutationError } from '../sync/v3/taskAttachmentLinksMutationService.js';
-import { createDurableWorkflowRuntimeMutationRouter, resolveWorkflowRuntimeMutationCapability, } from '../sync/v3/durableWorkflowRuntimeMutationRouter.js';
+import { areWorkflowRuntimeMutationsFenced, createDurableWorkflowRuntimeMutationRouter, resolveWorkflowRuntimeMutationCapability, } from '../sync/v3/durableWorkflowRuntimeMutationRouter.js';
 import { serializeCanonicalPlanningAttachmentLinks } from '../sync/planningCanonicalFields.js';
 import { buildCanonicalTaxonomyStateMutation, } from '../sync/v3/taxonomyStateMutation.js';
 import { buildTaskDeepLink, buildTaskforceDeepLink, normalizeTaskforceApplicationBaseUrl, } from '../shared/taskDeepLinks.js';
@@ -120,7 +119,10 @@ class ToolProfileHiddenError extends Error {
     suggestedTool;
     constructor(name, activeProfile) {
         const requiredProfiles = getMcpToolRequiredProfiles(name);
-        const suggestedTool = getMcpToolSuccessor(name);
+        const configuredSuccessor = getMcpToolSuccessor(name);
+        const suggestedTool = configuredSuccessor && isMcpToolVisibleInProfile(configuredSuccessor.name, activeProfile)
+            ? configuredSuccessor
+            : null;
         const suffix = suggestedTool ? ` Use ${suggestedTool.name} instead.` : ` Request one of these profiles to use it: ${requiredProfiles.join(', ')}.`;
         super(`Tool ${name} is not available in the ${activeProfile} MCP tool profile.${suffix}`);
         this.activeProfile = activeProfile;
@@ -747,6 +749,9 @@ function createOwnedTaskforceMcpCore(projectRoot, tenantId, localDataOwnerPermit
         },
     });
 }
+export function createStatelessTaskforceMcpServer(options = {}, factory = createTaskforceMcpServer) {
+    return factory({ ...options, resourceSubscriptionMode: 'disabled' });
+}
 export function createTaskforceMcpServer(options = {}) {
     // In dev (tsx), this module lives in src/mcp/.
     // In prod, it lives in dist/mcp/.
@@ -754,6 +759,9 @@ export function createTaskforceMcpServer(options = {}) {
     const PROJECT_NAME = path.basename(PROJECT_ROOT);
     const logStartup = options.logStartup !== false;
     const runtimeMode = options.runtimeMode === 'cloud' ? 'cloud' : 'local';
+    const modernProtocol = options.protocolEra === 'modern';
+    const supportsLegacyResourceSubscriptions = !modernProtocol
+        && options.resourceSubscriptionMode === 'legacy-long-lived';
     const applicationBaseUrl = normalizeTaskforceApplicationBaseUrl(options.applicationBaseUrl)
         || (runtimeMode === 'cloud'
             ? resolveCloudApplicationBaseUrl()
@@ -836,8 +844,6 @@ export function createTaskforceMcpServer(options = {}) {
     };
     const operationIdentityScope = options.operationIdentityScope
         ? {
-            generation: String(options.operationIdentityScope.generation || '').trim(),
-            sessionId: String(options.operationIdentityScope.sessionId || '').trim(),
             connectionInstance: String(options.operationIdentityScope.connectionInstance || '').trim(),
         }
         : null;
@@ -845,7 +851,7 @@ export function createTaskforceMcpServer(options = {}) {
         throw new Error('Shared MCP operation identity scope is incomplete.');
     }
     const runtimeRequestNamespace = operationIdentityScope
-        ? fingerprintWorkspaceSyncPayload({ kind: 'shared-mcp-session', ...operationIdentityScope })
+        ? fingerprintWorkspaceSyncPayload({ kind: 'shared-mcp-process', ...operationIdentityScope })
         : runtimeMode === 'cloud'
             ? String(options.auth?.requestId || '').trim() || randomUUID()
             : randomUUID();
@@ -1204,8 +1210,8 @@ export function createTaskforceMcpServer(options = {}) {
     }, {
         capabilities: {
             resources: {
-                subscribe: true,
-                listChanged: true,
+                ...(supportsLegacyResourceSubscriptions ? { subscribe: true } : {}),
+                ...(!modernProtocol ? { listChanged: true } : {}),
             },
             tools: {},
         },
@@ -1881,6 +1887,9 @@ export function createTaskforceMcpServer(options = {}) {
             } : {}),
             title: task?.title || null,
             status: task?.status || null,
+            isArchived: Boolean(task?.isArchived),
+            completedAt: task?.completedAt || null,
+            canceledReason: task?.canceledReason || null,
             category: task?.category || null,
             type: task?.type || null,
             priority: task?.priority ?? null,
@@ -2225,42 +2234,38 @@ export function createTaskforceMcpServer(options = {}) {
             return null;
         return resolved;
     }
-    function resolveFinishTaskReviewer(task) {
+    function resolveFinishTaskReviewer(task, reviewer) {
+        if (reviewer !== undefined) {
+            const resolvedReviewer = resolveRuntimeTaskAssigneeInput(reviewer);
+            const actor = resolvedReviewer
+                ? core.resolveWorkspaceActor(ACTIVE_WORKSPACE_ID, resolvedReviewer)
+                : null;
+            const eligible = actor?.kind === 'ai'
+                ? core.listAiProfiles(ACTIVE_WORKSPACE_ID).some((profile) => profile.id === actor.id)
+                : core.listWorkspaceUsers(ACTIVE_WORKSPACE_ID).some((user) => (user.userId === actor?.id
+                    && String(user.status || '').trim().toLowerCase() === 'active'
+                    && user.disabled !== true));
+            if (!actor || actor.meta?.unresolved === true || !eligible) {
+                throw new McpPublicError('reviewer must identify an active human or AI assignee in the current workspace. Call list_assignees and retry with an assignee ID.', 'MCP_REVIEWER_INVALID');
+            }
+            return { assignee: actor.id, source: 'explicit' };
+        }
         const existingAssignee = String(task?.assignee || '').trim();
         if (existingAssignee) {
             const existingActor = core.resolveWorkspaceActor(ACTIVE_WORKSPACE_ID, existingAssignee);
-            if (existingActor?.kind === 'human' && existingActor.meta?.unresolved !== true) {
+            const eligibleExistingHuman = existingActor?.kind === 'human'
+                && existingActor.meta?.unresolved !== true
+                && core.listWorkspaceUsers(ACTIVE_WORKSPACE_ID).some((user) => (user.userId === existingActor.id
+                    && String(user.status || '').trim().toLowerCase() === 'active'
+                    && user.disabled !== true));
+            if (eligibleExistingHuman) {
                 return {
                     assignee: existingActor.id,
                     source: 'existing_human_owner',
                 };
             }
         }
-        if (runtimeMode === 'cloud' && auditActorUserId !== 'anonymous') {
-            const currentUser = core.listWorkspaceUsers(ACTIVE_WORKSPACE_ID)
-                .find((user) => user.userId === auditActorUserId
-                && String(user.status || '').trim().toLowerCase() === 'active'
-                && user.disabled !== true);
-            if (currentUser) {
-                return { assignee: currentUser.userId, source: 'current_user' };
-            }
-        }
-        const workspaceOwner = core.listWorkspaceUsers(ACTIVE_WORKSPACE_ID)
-            .filter((user) => String(user.status || '').trim().toLowerCase() === 'active' && user.disabled !== true)
-            .sort((left, right) => {
-            const leftRank = left.role === 'owner' ? 0 : left.role === 'admin' ? 1 : 2;
-            const rightRank = right.role === 'owner' ? 0 : right.role === 'admin' ? 1 : 2;
-            if (leftRank !== rightRank)
-                return leftRank - rightRank;
-            return String(left.displayName || left.email || left.userId).localeCompare(String(right.displayName || right.email || right.userId), undefined, { sensitivity: 'base' });
-        })[0];
-        if (workspaceOwner && (workspaceOwner.role === 'owner' || workspaceOwner.role === 'admin')) {
-            return {
-                assignee: workspaceOwner.userId,
-                source: 'workspace_owner',
-            };
-        }
-        throw new McpPublicError('Could not resolve a human reviewer for review handoff. Resolve a current human user, set a human owner on the task, or ensure the workspace has an active owner/admin.', 'MCP_REVIEWER_REQUIRED');
+        throw new McpPublicError('Review handoff requires an explicit reviewer when the task has no eligible existing human reviewer. Call list_assignees and retry finish_task with reviewer set to a human or AI assignee ID.', 'MCP_REVIEWER_REQUIRED');
     }
     function getActiveMcpActorRef() {
         if (activeAiProfileId)
@@ -2301,13 +2306,19 @@ export function createTaskforceMcpServer(options = {}) {
             }).task;
         }
         if (!useStatusBoundary) {
-            return core.updateTask(input.task.id, input.updates, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
+            return core.updateTask(input.task.id, input.updates, ACTIVE_WORKSPACE_ID, {
+                actorRef: getActiveMcpActorRef(),
+                ...(input.deferNotifications ? { persistBackup: false, emitRealtime: false } : {}),
+            });
         }
         const unsupported = Object.keys(input.updates).filter((field) => (!durableStatusControlFields.has(field) && !durableTaskMetadataFieldNames.has(field)));
         if (unsupported.length > 0) {
             throw new TaskforceRuleError(`Combined durable task status update contains unsupported fields: ${unsupported.sort().join(', ')}.`, 400, 'TASK_STATUS_INVALID_PAYLOAD');
         }
         const status = String(hasStatus ? input.updates.status : input.task.status || 'task').trim();
+        if (status === 'review' && String(input.task.status || '').trim() !== 'review' && !input.reviewHandoff) {
+            throw new McpPublicError('Moving a task to review requires finish_task with a nonblank evidence comment.', 'TASK_REVIEW_HANDOFF_REQUIRED', 400);
+        }
         const metadataPatch = selectDurableTaskMetadataPatch(input.updates);
         delete metadataPatch.assignee;
         const assigneeIntent = input.assigneeIntent || (Object.prototype.hasOwnProperty.call(input.updates, 'assignee')
@@ -2322,10 +2333,73 @@ export function createTaskforceMcpServer(options = {}) {
             : null;
         return durableTaskMutationRouter.setStatus({
             taskId: input.task.id,
-            payload: { status, assigneeIntent, canceledReason, metadataPatch },
+            payload: {
+                status,
+                assigneeIntent,
+                canceledReason,
+                metadataPatch,
+                ...(input.reviewHandoff ? { reviewHandoff: input.reviewHandoff } : {}),
+            },
             actorRef: getActiveMcpActorRef(),
         }).task;
     }
+    function mutateTaskReviewHandoffThroughBoundary(input) {
+        const validation = validateStructuredCommentForAdd(input.handoffComment);
+        if (!validation.ok)
+            throw new McpPublicError(validation.message);
+        const actorRef = getActiveMcpActorRef();
+        const operationId = requireStableMcpRequestId('operation', `review-handoff-comment:${input.task.id}`);
+        const commentId = requireStableMcpRequestId('comment', `review-handoff:${input.task.id}`);
+        const comment = {
+            id: commentId,
+            author: actorRef,
+            submittedAuthor: actorRef,
+            text: input.handoffComment,
+        };
+        if (durableTaskMutationRouter.enabled) {
+            return mutateTaskThroughStatusBoundary({
+                task: input.task,
+                updates: input.updates,
+                assigneeIntent: input.assigneeIntent,
+                reviewHandoff: { comment },
+            });
+        }
+        let updated;
+        try {
+            updated = core.getDatabaseAdapter().transaction(() => {
+                mutateTaskThroughStatusBoundary({
+                    task: input.task,
+                    updates: input.updates,
+                    assigneeIntent: input.assigneeIntent,
+                    deferNotifications: true,
+                });
+                const durableRouter = getDurableTaskCommentMutationRouter(actorRef, operationId);
+                const task = durableRouter.enabled
+                    ? durableRouter.append({
+                        taskId: input.task.id,
+                        comment: { ...comment, timestamp: new Date().toISOString() },
+                    }).task
+                    : core.addComment(input.task.id, input.handoffComment, actorRef, ACTIVE_WORKSPACE_ID, {
+                        actorRef,
+                        persistBackup: false,
+                        emitRealtime: false,
+                        commentId,
+                    });
+                if (!task)
+                    throw new Error(`Task ${input.task.id} not found`);
+                return task;
+            })();
+        }
+        catch (error) {
+            try {
+                core.notifyDurableTaskMetadataCommitted(ACTIVE_WORKSPACE_ID, input.task.id);
+            }
+            catch { /* Preserve the original handoff failure. */ }
+            throw error;
+        }
+        core.notifyDurableTaskMetadataCommitted(ACTIVE_WORKSPACE_ID, input.task.id);
+        return updated;
+    }
     function mutateTaskLifecycleThroughBoundary(input) {
         if (!durableTaskMutationRouter.enabled)
             return input.legacy();
@@ -3706,7 +3780,7 @@ export function createTaskforceMcpServer(options = {}) {
         const hydratedWorkstream = core.getWorkstream(workstream.id, ACTIVE_WORKSPACE_ID) || workstream;
         return { id: hydratedWorkstream.id, workstream: hydratedWorkstream };
     }
-    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    server.setRequestHandler('resources/list', async () => {
         const resources = [
             {
                 uri: RESOURCE_CONFIG_URI,
@@ -3753,7 +3827,7 @@ export function createTaskforceMcpServer(options = {}) {
             resources,
         };
     });
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    server.setRequestHandler('resources/templates/list', async () => {
         if (!hasPermission(RESOURCE_PERMISSIONS.task)) {
             return { resourceTemplates: [] };
         }
@@ -3785,7 +3859,7 @@ export function createTaskforceMcpServer(options = {}) {
             ],
         };
     });
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    server.setRequestHandler('resources/read', async (request) => {
         const uri = request.params.uri;
         assertResourcePermission(uri);
         if (uri === RESOURCE_CONFIG_URI) {
@@ -3891,24 +3965,26 @@ export function createTaskforceMcpServer(options = {}) {
         }
         throw new Error(`Unknown resource URI: ${uri}`);
     });
-    server.setRequestHandler(SubscribeRequestSchema, async (request) => {
-        const uri = request.params.uri;
-        if (!isSupportedResourceUri(uri)) {
-            throw new Error(`Unsupported resource URI for subscribe: ${uri}`);
-        }
-        assertResourcePermission(uri);
-        resourceSubscriptions.add(uri);
-        return {};
-    });
-    server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
-        const uri = request.params.uri;
-        if (!isSupportedResourceUri(uri)) {
-            throw new Error(`Unsupported resource URI for unsubscribe: ${uri}`);
-        }
-        assertResourcePermission(uri);
-        resourceSubscriptions.delete(uri);
-        return {};
-    });
+    if (supportsLegacyResourceSubscriptions) {
+        server.setRequestHandler('resources/subscribe', async (request) => {
+            const uri = request.params.uri;
+            if (!isSupportedResourceUri(uri)) {
+                throw new Error(`Unsupported resource URI for subscribe: ${uri}`);
+            }
+            assertResourcePermission(uri);
+            resourceSubscriptions.add(uri);
+            return {};
+        });
+        server.setRequestHandler('resources/unsubscribe', async (request) => {
+            const uri = request.params.uri;
+            if (!isSupportedResourceUri(uri)) {
+                throw new Error(`Unsupported resource URI for unsubscribe: ${uri}`);
+            }
+            assertResourcePermission(uri);
+            resourceSubscriptions.delete(uri);
+            return {};
+        });
+    }
     /**
      * Tool Definitions
      */
@@ -4024,16 +4100,19 @@ export function createTaskforceMcpServer(options = {}) {
         const tool = registeredTools.find((candidate) => candidate.name === name);
         return tool ? materializeToolDescriptor(tool, buildToolDescriptorContext()) : null;
     };
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const listTools = async () => {
         const context = buildToolDescriptorContext();
         const tools = registeredTools
             .map((tool) => materializeToolDescriptor(tool, context))
             .filter((tool) => (isMcpToolVisibleInProfile(tool.name, activeToolProfile)
             && hasPermission(TOOL_PERMISSIONS[tool.name])));
         return {
-            tools,
+            // Descriptors are validated by Taskforce's JSON Schema contract before
+            // registration; v2 narrows the equivalent recursive JSON value type.
+            tools: tools,
         };
-    });
+    };
+    server.setRequestHandler('tools/list', listTools);
     const resolvePlanningAttachmentTarget = (targetType, inputId) => {
         if (targetType === 'initiative') {
             const { id, initiative } = resolveInitiativeByIdentifierOrThrow(inputId);
@@ -4953,7 +5032,9 @@ export function createTaskforceMcpServer(options = {}) {
     const taskLifecycleCommandService = createTaskLifecycleCommandService({
         formatTaskIdentifier,
         resolveAssigneeLabel: (assignee) => core.resolveWorkspaceActor(ACTIVE_WORKSPACE_ID, assignee)?.label || assignee,
-        setStatus: (input) => mutateTaskThroughStatusBoundary(input),
+        setStatus: (input) => input.handoffComment
+            ? mutateTaskReviewHandoffThroughBoundary(input)
+            : mutateTaskThroughStatusBoundary(input),
         mutateLifecycle: (input) => mutateTaskLifecycleThroughBoundary({
             taskId: input.taskId,
             mutationKind: input.mutationKind,
@@ -4973,7 +5054,7 @@ export function createTaskforceMcpServer(options = {}) {
                 });
             },
         }),
-        resolveReviewer: (task) => resolveFinishTaskReviewer(task),
+        resolveReviewer: (task, reviewer) => resolveFinishTaskReviewer(task, reviewer),
     });
     const planningCommandPreparationService = new PlanningCommandPreparationService({
         resolveOwner: resolvePlanningOwnerInput,
@@ -4986,12 +5067,17 @@ export function createTaskforceMcpServer(options = {}) {
         listItems: (taskId) => core.listChecklistItems(taskId, ACTIVE_WORKSPACE_ID),
         createId: (scope, key) => requireStableMcpRequestId(scope, key),
         now: () => new Date().toISOString(),
-        replace: ({ taskId, items, operationId }) => {
+        replace: ({ taskId, items, operationId, expectedDetailRevision, requireDurableIdempotency, itemUpdateIntent, }) => {
             const actorRef = getActiveMcpActorRef();
             const durableRouter = getDurableTaskChecklistMutationRouter(actorRef, operationId);
+            if (requireDurableIdempotency) {
+                requireDurableExplicitIdempotency(durableRouter.enabled, 'task checklist');
+            }
             return durableRouter.enabled
-                ? durableRouter.replace({ taskId, items }).task
-                : core.updateTask(taskId, { checklistItems: items }, ACTIVE_WORKSPACE_ID, { actorRef });
+                ? durableRouter.replace({ taskId, items, expectedDetailRevision, itemUpdateIntent }).task
+                : expectedDetailRevision
+                    ? core.updateTaskIfDetailRevisionMatches(taskId, expectedDetailRevision, { checklistItems: items }, ACTIVE_WORKSPACE_ID, { actorRef })
+                    : core.updateTask(taskId, { checklistItems: items }, ACTIVE_WORKSPACE_ID, { actorRef });
         },
     });
     const annotatedAttachmentCommandService = createAnnotatedAttachmentCommandService({
@@ -5014,7 +5100,7 @@ export function createTaskforceMcpServer(options = {}) {
     }
     function rethrowChecklistCommandError(error) {
         if (error instanceof TaskChecklistCommandError) {
-            if (error.code === 'TASK_NOT_FOUND') {
+            if (error.code === 'TASK_NOT_FOUND' || error.code === 'TASK_CHECKLIST_ITEM_NOT_FOUND') {
                 throw new McpPublicError(error.message, 'MCP_NOT_FOUND', error.statusCode);
             }
             throw new McpPublicError(error.message);
@@ -5247,6 +5333,7 @@ export function createTaskforceMcpServer(options = {}) {
                 const avatarSuggestion = resolved.created
                     && !configuredClientBlocksGeneration
                     && isAiProfileAvatarGenerationEligible(resolved.profile)
+                    && isMcpToolVisibleInProfile('generate_profile_avatar', activeToolProfile)
                     ? {
                         avatarSuggestion: {
                             nextTool: 'generate_profile_avatar',
@@ -5455,6 +5542,9 @@ export function createTaskforceMcpServer(options = {}) {
                         requiresCommentEvidence: step.requiresCommentEvidence,
                     } : {}),
                 }));
+                const currentStep = assignment.execution.status === 'running'
+                    ? assignment.steps.find((step) => step.id === assignment.execution.currentStepId)
+                    : undefined;
                 return {
                     content: [{ type: 'text', text: JSON.stringify({
                                 task: withTaskUrl({ id: task.id, referenceLabel: formatTaskIdentifier(task), title: task.title }),
@@ -5466,11 +5556,23 @@ export function createTaskforceMcpServer(options = {}) {
                                     currentStepId: assignment.execution.currentStepId || null,
                                     steps,
                                 },
+                                completionCall: currentStep ? {
+                                    tool: 'complete_workflow_step',
+                                    arguments: {
+                                        taskId,
+                                        executionId: assignment.execution.id,
+                                        stepId: currentStep.id,
+                                    },
+                                } : null,
                             }, null, 2) }],
                 };
             }
             case "complete_workflow_step": {
                 const { taskId, executionId, stepId, evidenceCommentId } = args;
+                const normalizedEvidenceCommentId = evidenceCommentId == null ? undefined : evidenceCommentId;
+                if (areWorkflowRuntimeMutationsFenced()) {
+                    throw new McpPublicError('Workflow execution changes are temporarily paused.', 'WORKFLOW_RUNTIME_MUTATIONS_FENCED', 503);
+                }
                 const { task } = resolveTaskByIdentifierOrThrow(taskId);
                 ensureResolvedProfileForSessionBootstrap();
                 const agentProfileId = String(activeAiProfileId || '').trim();
@@ -5483,7 +5585,7 @@ export function createTaskforceMcpServer(options = {}) {
                     throw new McpPublicError('The workflow execution does not belong to this task.', 'WORKFLOW_TASK_MISMATCH', 409);
                 }
                 const idempotencyKey = `agent-step-${createHash('sha256')
-                    .update(`${executionId}:${stepId}:${agentProfileId}:${String(evidenceCommentId || '')}`)
+                    .update(`${executionId}:${stepId}:${agentProfileId}:${String(normalizedEvidenceCommentId || '')}`)
                     .digest('hex')
                     .slice(0, 32)}`;
                 let result;
@@ -5505,7 +5607,7 @@ export function createTaskforceMcpServer(options = {}) {
                         }).completeStep({
                             executionId,
                             expectedStepId: stepId,
-                            evidenceCommentId,
+                            evidenceCommentId: normalizedEvidenceCommentId,
                         })
                         : executionService.completeCurrentStep({
                             workspaceId: ACTIVE_WORKSPACE_ID,
@@ -5513,7 +5615,7 @@ export function createTaskforceMcpServer(options = {}) {
                             actorId: agentProfileId,
                             actorType: 'agent',
                             expectedStepId: stepId,
-                            evidenceCommentId,
+                            evidenceCommentId: normalizedEvidenceCommentId,
                             idempotencyKey,
                         });
                 }
@@ -6170,12 +6272,14 @@ export function createTaskforceMcpServer(options = {}) {
                 const { taskId } = args;
                 const { id: resolvedTaskId } = resolveTaskByIdentifierOrThrow(taskId);
                 const checklist = core.listChecklistItems(resolvedTaskId, ACTIVE_WORKSPACE_ID);
+                const detailRevision = core.getTaskDetailRevision(resolvedTaskId, ACTIVE_WORKSPACE_ID);
                 return {
                     content: [{
                             type: "text",
                             text: JSON.stringify({
                                 taskId: resolvedTaskId,
                                 ...(buildTaskUrl({ id: resolvedTaskId }) ? { url: buildTaskUrl({ id: resolvedTaskId }) } : {}),
+                                detailRevision,
                                 items: checklist,
                             }, null, 2),
                         }],
@@ -6245,6 +6349,49 @@ export function createTaskforceMcpServer(options = {}) {
                         }],
                 };
             }
+            case "update_task_checklist_item": {
+                const { taskId, itemId, text, done, order, expectedDetailRevision, idempotencyKey: rawIdempotencyKey, } = args;
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const operationId = idempotencyKey
+                    ? stableExplicitMutationId('operation', 'update_task_checklist_item', idempotencyKey)
+                    : requireStableMcpRequestId('operation', 'task-checklist-update');
+                let result;
+                try {
+                    result = taskChecklistCommandService.update({
+                        taskId,
+                        itemId,
+                        text,
+                        done,
+                        order,
+                        expectedDetailRevision,
+                        operationId,
+                        requireDurableIdempotency: Boolean(idempotencyKey),
+                    });
+                }
+                catch (error) {
+                    rethrowChecklistCommandError(error);
+                }
+                const detailRevision = core.getTaskDetailRevision(result.taskId, ACTIVE_WORKSPACE_ID);
+                recordMcpWriteAudit('update_task_checklist_item', {
+                    taskId: result.taskId,
+                    itemId: result.item.id,
+                });
+                await notifyResourceMutation({
+                    includeTasks: true,
+                    taskIds: [result.taskId],
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                taskId: result.taskId,
+                                ...(buildTaskUrl({ id: result.taskId }) ? { url: buildTaskUrl({ id: result.taskId }) } : {}),
+                                detailRevision,
+                                item: result.item,
+                            }, null, 2),
+                        }],
+                };
+            }
             case "get_task_attachments": {
                 const { id, taskId, attachmentId } = args;
                 const taskIdentifier = taskId ?? id;
@@ -6978,14 +7125,40 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "review_document": {
-                const { id, documentId, sessionId, title, comments, prompt } = args;
+                const { id, documentId, sessionId, title, comments, prompt, parentCommentId, threadCommentId, threadStatus, } = args;
                 const asset = resolveDocumentAssetByIdentifierOrThrow(documentId ?? id);
                 const normalizedComments = Array.isArray(comments)
                     ? comments
                     : (typeof prompt === 'string' && prompt.trim()
                         ? [{ body: prompt.trim() }]
                         : []);
-                if (normalizedComments.length === 0) {
+                const normalizedSessionId = typeof sessionId === 'string' ? sessionId.trim() : '';
+                const normalizedParentCommentId = typeof parentCommentId === 'string' ? parentCommentId.trim() : '';
+                const normalizedThreadCommentId = typeof threadCommentId === 'string' ? threadCommentId.trim() : '';
+                const hasThreadStatus = threadStatus !== undefined;
+                const hasThreadUpdate = Boolean(normalizedThreadCommentId) || hasThreadStatus;
+                const hasCommentsArgument = Object.prototype.hasOwnProperty.call(args, 'comments');
+                const hasPromptArgument = Object.prototype.hasOwnProperty.call(args, 'prompt');
+                const hasTitleArgument = Object.prototype.hasOwnProperty.call(args, 'title');
+                if (hasThreadUpdate && (!normalizedThreadCommentId || (threadStatus !== 'open' && threadStatus !== 'resolved'))) {
+                    throw new McpPublicError('threadCommentId and threadStatus are required together');
+                }
+                if ((normalizedParentCommentId || hasThreadUpdate) && !normalizedSessionId) {
+                    throw new McpPublicError('sessionId is required for reply and thread-status updates');
+                }
+                if (hasThreadUpdate && (normalizedParentCommentId || hasCommentsArgument || hasPromptArgument || hasTitleArgument)) {
+                    throw new McpPublicError('Thread-status updates cannot be combined with comments, replies, or a session title');
+                }
+                if (normalizedParentCommentId && hasTitleArgument) {
+                    throw new McpPublicError('Replies cannot set a session title');
+                }
+                if (hasCommentsArgument && hasPromptArgument) {
+                    throw new McpPublicError('comments and prompt cannot be combined');
+                }
+                if (normalizedParentCommentId && normalizedComments.length !== 1) {
+                    throw new McpPublicError('Replies require exactly one comment or prompt');
+                }
+                if (!hasThreadUpdate && normalizedComments.length === 0) {
                     throw new McpPublicError('comments array is required');
                 }
                 for (const comment of normalizedComments) {
@@ -6997,13 +7170,115 @@ export function createTaskforceMcpServer(options = {}) {
                         throw new McpPublicError(anchorError);
                     }
                 }
+                if (normalizedParentCommentId && normalizedComments[0]?.anchor !== undefined && normalizedComments[0]?.anchor !== null) {
+                    throw new McpPublicError('Replies cannot have anchors');
+                }
+                if (hasThreadUpdate) {
+                    const existingSession = core.getDocumentReviewSession({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                    });
+                    if (!existingSession) {
+                        throw new McpPublicError(`Document review session ${normalizedSessionId} not found.`, 'MCP_NOT_FOUND', 404);
+                    }
+                    if (existingSession.assetId !== asset.assetId) {
+                        throw new McpPublicError(`Document review session ${normalizedSessionId} is not linked to document ${getDocumentReferenceLabel(asset) || asset.assetId}.`, 'MCP_ATTACHMENT_CONFLICT', 409);
+                    }
+                    const updatedSession = core.updateDocumentReviewThreadStatus({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                        commentId: normalizedThreadCommentId,
+                        status: threadStatus,
+                        actorId: getActiveMcpActorRef(),
+                    });
+                    const updatedThread = updatedSession.comments.find((entry) => entry.id === normalizedThreadCommentId) || null;
+                    const sessionSummary = buildDocumentReviewSessionSummary(updatedSession);
+                    recordMcpWriteAudit('review_document', {
+                        documentAssetId: asset.assetId,
+                        sessionId: updatedSession.id,
+                        sessionAction: 'reused',
+                        threadCommentId: normalizedThreadCommentId,
+                        threadStatus,
+                    });
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    document: {
+                                        assetId: asset.assetId,
+                                        referenceLabel: getDocumentReferenceLabel(asset),
+                                    },
+                                    sessionId: updatedSession.id,
+                                    sessionAction: 'reused',
+                                    postedCommentIds: [],
+                                    commentCount: 0,
+                                    thread: buildCompactDocumentReviewComment(updatedThread),
+                                    unresolvedThreadCount: sessionSummary.unresolvedThreadCount,
+                                    nextTool: 'get_document_reviews',
+                                    suggestedArgs: {
+                                        documentId: getDocumentReferenceLabel(asset) || asset.assetId,
+                                        sessionId: updatedSession.id,
+                                    },
+                                }, null, 2),
+                            }],
+                    };
+                }
+                if (normalizedParentCommentId) {
+                    const existingSession = core.getDocumentReviewSession({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                    });
+                    if (!existingSession) {
+                        throw new McpPublicError(`Document review session ${normalizedSessionId} not found.`, 'MCP_NOT_FOUND', 404);
+                    }
+                    if (existingSession.assetId !== asset.assetId) {
+                        throw new McpPublicError(`Document review session ${normalizedSessionId} is not linked to document ${getDocumentReferenceLabel(asset) || asset.assetId}.`, 'MCP_ATTACHMENT_CONFLICT', 409);
+                    }
+                    const repliedSession = core.addDocumentReviewReply({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                        parentCommentId: normalizedParentCommentId,
+                        body: normalizedComments[0].body,
+                        actorId: getActiveMcpActorRef(),
+                    });
+                    const postedReply = repliedSession.comments.at(-1) || null;
+                    recordMcpWriteAudit('review_document', {
+                        documentAssetId: asset.assetId,
+                        sessionId: repliedSession.id,
+                        sessionAction: 'reused',
+                        parentCommentId: normalizedParentCommentId,
+                        commentCount: 1,
+                    });
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    document: {
+                                        assetId: asset.assetId,
+                                        referenceLabel: getDocumentReferenceLabel(asset),
+                                    },
+                                    sessionId: repliedSession.id,
+                                    sessionAction: 'reused',
+                                    postedCommentIds: postedReply ? [postedReply.id] : [],
+                                    commentCount: postedReply ? 1 : 0,
+                                    reply: buildCompactDocumentReviewComment(postedReply),
+                                    nextTool: 'get_document_reviews',
+                                    suggestedArgs: {
+                                        documentId: getDocumentReferenceLabel(asset) || asset.assetId,
+                                        sessionId: repliedSession.id,
+                                    },
+                                }, null, 2),
+                            }],
+                    };
+                }
                 let commandResult;
                 try {
                     commandResult = documentReviewCommandService.review({
                         workspaceId: ACTIVE_WORKSPACE_ID,
                         assetId: asset.assetId,
+                        documentVersion: asset.version,
                         documentLabel: getDocumentReferenceLabel(asset) || asset.assetId,
-                        sessionId: sessionId && typeof sessionId === 'string' ? sessionId : null,
+                        sessionId: normalizedSessionId || null,
                         title: typeof title === 'string' ? title : null,
                         comments: normalizedComments,
                         actorId: getActiveMcpActorRef(),
@@ -7029,6 +7304,7 @@ export function createTaskforceMcpServer(options = {}) {
                                 },
                                 sessionId: currentSession.id,
                                 sessionAction,
+                                documentVersion: currentSession.documentVersion,
                                 postedCommentIds,
                                 commentCount: postedCommentIds.length,
                                 nextTool: 'get_document_reviews',
@@ -7353,13 +7629,6 @@ export function createTaskforceMcpServer(options = {}) {
                                 actorRef: getActiveMcpActorRef(),
                                 provisionalLocalReference: shouldUseProvisionalTaskReferences(runtimeMode)
                             }), replayed: false };
-                    if ('operationId' in task) {
-                        options.onOperationAccepted?.({
-                            operationId: task.operationId,
-                            mutationKind: 'create',
-                            payloadFingerprint: fingerprintWorkspaceSyncPayload(prepared.durableTask || {}),
-                        });
-                    }
                     recordMcpWriteAudit('create_task', {
                         taskId: task.task?.id || null,
                         title: task.task?.title || null,
@@ -7478,6 +7747,9 @@ export function createTaskforceMcpServer(options = {}) {
                     const inputId = args.id;
                     const { id, task: existingTask } = resolveTaskByIdentifierOrThrow(inputId);
                     const prepared = taskRootCommandPreparationService.prepareUpdate(args);
+                    if (prepared.updates.status === 'review' && existingTask.status !== 'review') {
+                        throw new McpPublicError('update_task cannot move a task to review. Use finish_task with outcome=\'review\' and a nonblank evidence comment so the handoff commits atomically.', 'TASK_REVIEW_HANDOFF_REQUIRED', 400);
+                    }
                     const updated = mutateTaskThroughStatusBoundary({ task: existingTask, updates: prepared.updates });
                     if (!updated) {
                         throw new Error(`Task ${id} not found`);
@@ -7516,13 +7788,13 @@ export function createTaskforceMcpServer(options = {}) {
             }
             case "finish_task": {
                 try {
-                    const { id: inputId, outcome, comment } = args;
+                    const { id: inputId, outcome, comment, reviewer } = args;
                     const normalizedOutcome = String(outcome || '').trim().toLowerCase();
                     if (normalizedOutcome !== 'done' && normalizedOutcome !== 'review') {
                         throw new McpPublicError("outcome must be 'done' or 'review'");
                     }
                     const { id, task: existingTask } = resolveTaskByIdentifierOrThrow(inputId);
-                    const result = taskLifecycleCommandService.finish(existingTask, { outcome: normalizedOutcome, comment });
+                    const result = taskLifecycleCommandService.finish(existingTask, { outcome: normalizedOutcome, comment, reviewer });
                     recordMcpWriteAudit('finish_task', {
                         taskId: id,
                         outcome: normalizedOutcome,
@@ -7560,7 +7832,7 @@ export function createTaskforceMcpServer(options = {}) {
                 const { id: inputId, status, reason } = args;
                 const { id, task } = resolveTaskByIdentifierOrThrow(inputId);
                 const isCancelled = status === 'cancelled';
-                taskLifecycleCommandService.archive(task, { status, reason });
+                const result = taskLifecycleCommandService.archive(task, { status, reason });
                 recordMcpWriteAudit('archive_task', { taskId: id, status, cancelled: isCancelled });
                 await notifyResourceMutation({
                     taskIds: [id],
@@ -7568,7 +7840,15 @@ export function createTaskforceMcpServer(options = {}) {
                     includeStats: true,
                 });
                 return {
-                    content: [{ type: "text", text: `Task ${formatTaskIdentifier(task)} archived as ${status}` }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                task: buildTaskWriteSummary(result.task),
+                                archive: {
+                                    archived: true,
+                                    status: result.status,
+                                    cancelled: result.cancelled,
+                                    reason: isCancelled ? String(reason || '').trim() || null : null,
+                                },
+                            }, null, 2) }],
                 };
             }
             case "get_config": {
@@ -7791,8 +8071,9 @@ export function createTaskforceMcpServer(options = {}) {
             case "unarchive_task": {
                 const { id: inputId } = args;
                 const { id, task: existingTask } = resolveTaskByIdentifierOrThrow(inputId, { notFoundMessage: buildTaskLookupFailureMessage(String(inputId || '').trim()) });
+                let result;
                 try {
-                    taskLifecycleCommandService.unarchive(existingTask);
+                    result = taskLifecycleCommandService.unarchive(existingTask);
                 }
                 catch (error) {
                     if (error instanceof TaskLifecycleCommandError && error.code === 'TASK_NOT_FOUND') {
@@ -7807,7 +8088,10 @@ export function createTaskforceMcpServer(options = {}) {
                     includeStats: true,
                 });
                 return {
-                    content: [{ type: "text", text: `Task ${formatTaskIdentifier(existingTask)} unarchived` }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                task: buildTaskWriteSummary(result.task),
+                                unarchive: { unarchived: true },
+                            }, null, 2) }],
                 };
             }
             case "bulk_archive": {
@@ -7906,6 +8190,14 @@ export function createTaskforceMcpServer(options = {}) {
                     update.complexity = resolveNumberOption('complexity', update.complexity, COMPLEXITY_OPTIONS);
                 }
                 const preview = core.bulkUpdateFieldsPreview(resolvedList, ACTIVE_WORKSPACE_ID);
+                for (const item of preview.toApply) {
+                    if (item.fields.status !== 'review')
+                        continue;
+                    const existingTask = core.getTask(item.id, ACTIVE_WORKSPACE_ID);
+                    if (existingTask?.status !== 'review') {
+                        throw new McpPublicError('bulk_update_fields cannot move a task to review. Use finish_task with outcome=\'review\' and a nonblank evidence comment.', 'TASK_REVIEW_HANDOFF_REQUIRED', 400);
+                    }
+                }
                 const forceStatusBoundary = (durableTaskMutationRouter.enabled
                     && preview.toApply.some((item) => Object.prototype.hasOwnProperty.call(item.fields, 'status')));
                 const durableBatch = forceStatusBoundary || durableTaskRootMutationRouter.metadataEnabled;
@@ -8029,8 +8321,8 @@ export function createTaskforceMcpServer(options = {}) {
     };
     const toolHandlers = new Map(registeredTools.map((tool) => [tool.name, tool.handler]));
     const mcpInputValidator = createMcpInputValidator();
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-        const { name, arguments: args } = resolveMcpToolCallCompatibility(request.params.name, request.params.arguments);
+    const callTool = async (params, context = {}) => {
+        const { name, arguments: args } = resolveMcpToolCallCompatibility(params.name, params.arguments);
         const toolStartedAtMs = Date.now();
         let preparationMs = 0;
         let validationMs = 0;
@@ -8073,11 +8365,11 @@ export function createTaskforceMcpServer(options = {}) {
                 }
             });
             let result;
-            if (extra.requestId === undefined || extra.requestId === null) {
+            if (context.requestId === undefined || context.requestId === null) {
                 result = await execute();
             }
             else {
-                const transportSessionId = String(extra.sessionId || '').trim();
+                const transportSessionId = String(context.sessionId || '').trim();
                 const requestIdentity = operationIdentityScope
                     ? fingerprintWorkspaceSyncPayload({
                         kind: 'shared-mcp-request',
@@ -8086,18 +8378,18 @@ export function createTaskforceMcpServer(options = {}) {
                             || options.auth?.mcpConnectionId
                             || options.auth?.mcpClientId
                             || 'mcp',
-                        requestId: { type: typeof extra.requestId, value: extra.requestId },
+                        requestId: { type: typeof context.requestId, value: context.requestId },
                         tool: name,
                     })
                     : [
                         ...(runtimeMode === 'local' || !transportSessionId ? [runtimeRequestNamespace] : []),
                         String(transportSessionId || options.auth?.mcpConnectionId || options.auth?.mcpClientId || 'mcp'),
-                        String(extra.requestId),
+                        String(context.requestId),
                         name,
                     ].join(':');
                 const logicalCloudCreateIdentity = [
                     String(transportSessionId || options.auth?.mcpConnectionId || options.auth?.mcpClientId || 'mcp'),
-                    String(extra.requestId),
+                    String(context.requestId),
                     name,
                 ].join(':');
                 result = await cloudCreateRequestIdentity.run(logicalCloudCreateIdentity, () => mcpRequestIdentity.run(requestIdentity, execute));
@@ -8116,14 +8408,14 @@ export function createTaskforceMcpServer(options = {}) {
                 responseBytes = measureToolResultBytes(result);
                 return result;
             }
-            const result = buildUnexpectedToolErrorResult(auditRequestId || extra.requestId);
+            const result = buildUnexpectedToolErrorResult(auditRequestId || context.requestId);
             responseBytes = measureToolResultBytes(result);
             return result;
         }
         finally {
             try {
                 options.onToolCallTiming?.({
-                    requestId: String(auditRequestId || extra.requestId || '').trim() || null,
+                    requestId: String(auditRequestId || context.requestId || '').trim() || null,
                     toolName: name,
                     isWrite: isMcpWriteToolName(name),
                     outcome: timingOutcome,
@@ -8139,7 +8431,11 @@ export function createTaskforceMcpServer(options = {}) {
                 // Observability must never change tool behavior.
             }
         }
-    });
+    };
+    server.setRequestHandler('tools/call', (request, ctx) => callTool(request.params, {
+        requestId: ctx.mcpReq.id,
+        sessionId: ctx.sessionId,
+    }));
     return {
         server,
         core,
@@ -8149,6 +8445,16 @@ export function createTaskforceMcpServer(options = {}) {
         tenantId,
         version: MCP_SERVER_VERSION,
         toolProfile: activeToolProfile,
+        listTools,
+        callTool,
+    };
+}
+export async function connectMcpRuntimeToStdio(runtime, transport = new StdioServerTransport()) {
+    await runtime.server.connect(transport);
+    return {
+        ...runtime,
+        transport,
+        close: () => runtime.server.close(),
     };
 }
 export async function startTaskforceMcpStdioServer(options = {}) {
@@ -8164,18 +8470,18 @@ export async function startTaskforceMcpStdioServer(options = {}) {
             projectRoot,
             tenantId,
             core,
+            resourceSubscriptionMode: options.resourceSubscriptionMode ?? 'legacy-long-lived',
             auth: {
                 ...envAuth,
                 ...(options.auth || {}),
             },
         });
-        const transport = new StdioServerTransport();
-        await runtime.server.connect(transport);
+        const connected = await connectMcpRuntimeToStdio(runtime);
         const close = createTaskforceMcpStdioClose({
-            closeServer: () => runtime.server.close(),
+            closeServer: connected.close,
             ...(ownsCore ? { closeOwnedCore: () => core.close() } : {}),
         });
-        return { ...runtime, transport, close };
+        return { ...runtime, transport: connected.transport, close };
     }
     catch (error) {
         try {