@taskforcehq/taskforce 0.3.328 → 0.3.330

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';
@@ -32,7 +31,8 @@ import { WorkspaceSyncContentVersionStore, } from '../sync/engine/workspaceSyncC
 import { WorkspaceSyncPublishedContentResolver } from '../sync/engine/workspaceSyncPublishedContentResolver.js';
 import { createWorkspaceSyncServerContentRuntime } from '../sync/engine/workspaceSyncServerContentRuntime.js';
 import { resolveVirusScanConfigFromEnv, scanBufferForThreats } from '../security/virusScan.js';
-import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../runtime/appGates.js';
+import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, } from '../runtime/appGates.js';
+import { resolveNodeAppGateAccess } from '../runtime/nodeAppGates.js';
 import { getDocumentReferenceLabel, parseDocumentReference } from '../utils/documentReferences.js';
 import { getImageReferenceLabel, parseImageReference } from '../utils/imageReferences.js';
 import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils/canonicalAssetKind.js';
@@ -79,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';
@@ -746,6 +746,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/.
@@ -753,6 +756,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()
@@ -835,8 +841,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;
@@ -844,7 +848,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();
@@ -1203,12 +1207,14 @@ export function createTaskforceMcpServer(options = {}) {
     }, {
         capabilities: {
             resources: {
-                subscribe: true,
-                listChanged: true,
+                ...(supportsLegacyResourceSubscriptions ? { subscribe: true } : {}),
+                ...(!modernProtocol ? { listChanged: true } : {}),
             },
             tools: {},
         },
-        instructions: `Before writes, check get_current_profile; if unbound, use resolve_profile. Keep profileToken private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`,
+        instructions: runtimeMode === 'cloud' && options.auth?.actorType === 'token'
+            ? `Cloud access-token clients must pass profileToken on every write; obtain it from resolve_profile and keep it private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`
+            : `Before writes, check get_current_profile; if unbound, use resolve_profile. Keep profileToken private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`,
     });
     const TOOL_PERMISSIONS = MCP_TOOL_PERMISSIONS;
     const RESOURCE_PERMISSIONS = {
@@ -1311,9 +1317,10 @@ export function createTaskforceMcpServer(options = {}) {
     function buildBoundedTextContent(content, maxChars) {
         const requestedMaxChars = Number(maxChars);
         const hasRequestedMaxChars = maxChars !== undefined && maxChars !== null && maxChars !== '';
-        const resolvedMaxChars = hasRequestedMaxChars && Number.isFinite(requestedMaxChars)
-            ? Math.max(1, Math.floor(requestedMaxChars))
-            : 200000;
+        if (hasRequestedMaxChars && (!Number.isInteger(requestedMaxChars) || requestedMaxChars < 1)) {
+            throw new McpPublicError('maxChars must be a positive integer');
+        }
+        const resolvedMaxChars = hasRequestedMaxChars ? requestedMaxChars : 200000;
         const characters = Array.from(content);
         const totalChars = characters.length;
         const boundedContent = totalChars > resolvedMaxChars
@@ -1405,8 +1412,10 @@ export function createTaskforceMcpServer(options = {}) {
         }
         const requestedLimit = Number(options?.limit);
         const limit = Number.isFinite(requestedLimit)
-            ? Math.max(1, Math.min(50, Math.trunc(requestedLimit)))
+            ? Math.max(1, Math.min(51, Math.trunc(requestedLimit)))
             : 10;
+        const requestedOffset = Number(options?.offset);
+        const offset = Number.isFinite(requestedOffset) ? Math.max(0, Math.trunc(requestedOffset)) : 0;
         const normalize = (value) => typeof value === 'string' ? value.trim().toLowerCase() : '';
         const tokenize = (value) => normalize(value).split(/[^a-z0-9]+/i).filter(Boolean);
         const allImages = workspaceAssetStore.listAllByWorkspace(ACTIVE_WORKSPACE_ID, { kind: 'image' });
@@ -1450,8 +1459,10 @@ export function createTaskforceMcpServer(options = {}) {
             return [{ asset, matchedOn: Array.from(matchedOn), score }];
         });
         return scoredMatches
-            .sort((a, b) => b.score - a.score || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || '')))
-            .slice(0, limit);
+            .sort((a, b) => b.score - a.score
+            || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || ''))
+            || a.asset.assetId.localeCompare(b.asset.assetId))
+            .slice(offset, offset + limit);
     }
     const searchDocumentAssets = documentHelpers.searchDocumentAssets;
     function buildImageDescriptor(asset) {
@@ -1465,7 +1476,9 @@ export function createTaskforceMcpServer(options = {}) {
             sizeBytes: typeof asset.sizeBytes === 'number' ? asset.sizeBytes : null,
             ...(runtimeMode === 'local' ? { storageKey: asset.storageKey ?? null } : {}),
             updatedAt: asset.updatedAt ?? null,
-            apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}`,
+            ...(runtimeMode === 'local'
+                ? { apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}` }
+                : {}),
         };
         return withAttachmentUrl({ ...descriptor, kind: 'image' });
     }
@@ -1518,6 +1531,7 @@ export function createTaskforceMcpServer(options = {}) {
             || `Image ${normalizedValue} not found in workspace ${ACTIVE_WORKSPACE_ID}. If you only know a keyword, filename, or rough title, call search_images first.`, 'MCP_NOT_FOUND', 404);
     }
     const auditActorType = options.auth?.actorType || (runtimeMode === 'cloud' ? 'user' : 'local');
+    const requiresExplicitTokenAuthorship = runtimeMode === 'cloud' && auditActorType === 'token';
     const auditActorUserId = String(options.auth?.userId || (runtimeMode === 'cloud' ? 'anonymous' : 'local-mcp')).trim() || 'anonymous';
     const auditTokenId = options.auth?.tokenId ? String(options.auth.tokenId).trim() : null;
     const configuredAiProfileId = options.auth?.aiProfileId ? String(options.auth.aiProfileId).trim() || null : null;
@@ -1591,7 +1605,7 @@ export function createTaskforceMcpServer(options = {}) {
         const shouldBindOAuthGrant = auditActorType === 'oauth'
             && Boolean(auditTokenId)
             && configuredAiProfileId !== profileId;
-        const shouldApplyClientContext = Boolean((configuredMcpClientId && configuredMcpClientId !== 'general')
+        const shouldApplyClientContext = auditActorType !== 'token' && Boolean((configuredMcpClientId && configuredMcpClientId !== 'general')
             || configuredMcpConnectionId);
         if (!shouldBindOAuthGrant && !shouldApplyClientContext)
             return;
@@ -1755,6 +1769,10 @@ export function createTaskforceMcpServer(options = {}) {
         return resolved;
     }
     function findTrustedBoundProfile(options) {
+        // A generic access token proves workspace/tool authorization, not which AI
+        // is acting. Never use its historical connection row as authorship proof.
+        if (requiresExplicitTokenAuthorship)
+            return null;
         const grantProfile = findProfileForConfiguredGrant();
         const connectionProfile = findProfileForConfiguredConnection(options);
         if (grantProfile && connectionProfile && grantProfile.id !== connectionProfile.id) {
@@ -1771,6 +1789,19 @@ export function createTaskforceMcpServer(options = {}) {
         }
         return profile;
     }
+    function assertOAuthProfileClientCompatibility(profile) {
+        if (auditActorType !== 'oauth' || !configuredMcpClientId)
+            return;
+        const connection = profile.providerMetadata?.connection;
+        const storedClientId = connection && typeof connection === 'object' && !Array.isArray(connection)
+            ? parseMcpClientId(connection.clientId)
+            : null;
+        const inferredClientId = inferLegacyMcpClientIdFromProfile(profile);
+        const profileClientId = storedClientId || inferredClientId;
+        if (!profileClientId || profileClientId === configuredMcpClientId)
+            return;
+        throw new TaskforceRuleError('The supplied AI profile is not compatible with this OAuth client product.', 409, 'AI_PROFILE_SELECTION_INVALID', { profileId: profile.id, profileClientId, configuredClientId: configuredMcpClientId });
+    }
     function listSelectableOAuthProfiles(profileName) {
         if (auditActorType !== 'oauth')
             return [];
@@ -2197,42 +2228,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)
@@ -2273,13 +2300,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')
@@ -2294,10 +2327,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();
@@ -2383,6 +2479,8 @@ export function createTaskforceMcpServer(options = {}) {
     function ensureResolvedProfileFromConnection(defaults) {
         if (activeAiProfileId)
             return;
+        if (requiresExplicitTokenAuthorship)
+            return;
         const boundProfile = findTrustedBoundProfile({ repairConnection: false });
         if (boundProfile) {
             if (configuredAiProfileIdentityAsserted) {
@@ -2457,6 +2555,25 @@ export function createTaskforceMcpServer(options = {}) {
             throw new TaskforceRuleError('Writes are blocked because this MCP session requested an identity that conflicts with its OAuth-bound profile. Reconnect with the intended profile and retry resolve_profile.', 409, 'AI_PROFILE_BINDING_CONFLICT', { reason: 'session_identity_quarantined', nextTool: 'resolve_profile' });
         }
         const profileToken = resolveProfileTokenFromArgs(args);
+        if (requiresExplicitTokenAuthorship) {
+            if (!profileToken) {
+                throw new McpPublicError('Cloud access-token clients must pass profileToken on every mutating call. Call resolve_profile to obtain it, keep it private, and retry this write.', 'AI_PROFILE_PROOF_REQUIRED', 401);
+            }
+            const tokenProfile = core.getAiProfileByToken({
+                workspaceId: ACTIVE_WORKSPACE_ID,
+                profileToken,
+                seatScope: configuredAiProfileSeatScope,
+            });
+            if (!tokenProfile) {
+                throw new McpPublicError('Invalid AI profile token. Call resolve_profile again and retry.', 'INVALID_AI_PROFILE_TOKEN', 401);
+            }
+            if (activeAiProfileId && activeAiProfileId !== tokenProfile.id) {
+                failAiProfileBindingConflict('The supplied profile token conflicts with the AI profile already active for this request.', { reason: 'request_token_mismatch', boundProfileId: activeAiProfileId, suppliedProfileId: tokenProfile.id });
+            }
+            if (!activeAiProfileId)
+                activateAiProfile(tokenProfile.id, 'token_lookup');
+            return;
+        }
         if (activeAiProfileId) {
             if (!profileToken)
                 return;
@@ -2491,6 +2608,8 @@ export function createTaskforceMcpServer(options = {}) {
                     suppliedProfileId: profile.id,
                 });
             }
+            if (!trustedBoundProfile)
+                assertOAuthProfileClientCompatibility(profile);
             if (trustedBoundProfile && configuredAiProfileIdentityAsserted) {
                 assertRequestedIdentityMatchesBoundProfile(trustedBoundProfile, {
                     name: configuredAiProfileName,
@@ -2525,7 +2644,7 @@ export function createTaskforceMcpServer(options = {}) {
         throw new McpPublicError('This tool requires an AI profile. Call resolve_profile first, then retry. If your MCP client is stateless, pass profileToken on mutating calls.', 'AI_PROFILE_REQUIRED');
     }
     function assertAnnotatedAttachmentReadAccess() {
-        const gate = resolveAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
+        const gate = resolveNodeAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
         if (!gate.allowed) {
             throw new TaskforceRuleError('Annotated attachments are unavailable for this workspace.', 403, gate.code || 'ANNOTATED_ATTACHMENTS_UNAVAILABLE');
         }
@@ -3340,6 +3459,17 @@ export function createTaskforceMcpServer(options = {}) {
             offset: Number(normalizedOffset),
         };
     }
+    function normalizeSearchReadPage(limit, offset, defaultLimit) {
+        const normalizedLimit = limit === undefined ? defaultLimit : limit;
+        const normalizedOffset = offset === undefined ? 0 : offset;
+        if (!Number.isInteger(normalizedLimit) || Number(normalizedLimit) < 1 || Number(normalizedLimit) > 50) {
+            throw new McpPublicError('limit must be an integer from 1 to 50');
+        }
+        if (!Number.isInteger(normalizedOffset) || Number(normalizedOffset) < 0) {
+            throw new McpPublicError('offset must be a non-negative integer');
+        }
+        return { limit: Number(normalizedLimit), offset: Number(normalizedOffset) };
+    }
     function buildCompactPlanningHistory(targetType, entity) {
         const duplicatedCommentAction = `${targetType}-comment-added`;
         const activity = Array.isArray(entity?.activity) ? entity.activity : [];
@@ -3516,17 +3646,26 @@ export function createTaskforceMcpServer(options = {}) {
             workstreamsByInitiativeId.set(normalizedInitiativeId, current);
         }
         const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
-        const initiatives = core.listInitiatives(ACTIVE_WORKSPACE_ID)
-            .filter((initiative) => matchesInitiativePlanningQuery(initiative, query, workstreamsByInitiativeId.get(initiative.id) || []))
-            .map((initiative) => buildInitiativeResourcePayload(initiative, {
-            workstreamsByInitiativeId,
-            taskCountsByWorkstreamId,
-            detail: 'compact',
-        }));
+        const matches = core.listInitiatives(ACTIVE_WORKSPACE_ID)
+            .filter((initiative) => matchesInitiativePlanningQuery(initiative, query, workstreamsByInitiativeId.get(initiative.id) || []));
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? 25;
+        const initiatives = matches.slice(offset, offset + limit).map((initiative) => {
+            const compact = buildInitiativeResourcePayload(initiative, {
+                workstreamsByInitiativeId,
+                taskCountsByWorkstreamId,
+                detail: 'compact',
+            });
+            const { nextDetailOption: _nextDetailOption, ...summary } = compact;
+            return summary;
+        });
+        const pagination = buildPlanningPagination(matches.length, offset, limit, initiatives.length);
         return {
-            total: initiatives.length,
+            total: matches.length,
             ...(query ? { query } : {}),
             initiatives,
+            pagination,
+            guidance: 'Use get_initiative with the initiative ID or reference for details.',
         };
     }
     function buildWorkstreamsResourcePayload(options) {
@@ -3536,13 +3675,22 @@ export function createTaskforceMcpServer(options = {}) {
             initiativesById.set(initiative.id, initiative);
         }
         const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
-        const workstreams = core.listWorkstreams(ACTIVE_WORKSPACE_ID)
-            .filter((workstream) => matchesWorkstreamPlanningQuery(workstream, query, initiativesById.get(workstream.initiativeId || '')))
-            .map((workstream) => buildWorkstreamResourcePayload(workstream, { taskCountsByWorkstreamId, detail: 'compact' }));
+        const matches = core.listWorkstreams(ACTIVE_WORKSPACE_ID)
+            .filter((workstream) => matchesWorkstreamPlanningQuery(workstream, query, initiativesById.get(workstream.initiativeId || '')));
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? 25;
+        const workstreams = matches.slice(offset, offset + limit).map((workstream) => {
+            const compact = buildWorkstreamResourcePayload(workstream, { taskCountsByWorkstreamId, detail: 'compact' });
+            const { nextDetailOption: _nextDetailOption, nextTaskTool: _nextTaskTool, suggestedTaskArgs: _suggestedTaskArgs, ...summary } = compact;
+            return summary;
+        });
+        const pagination = buildPlanningPagination(matches.length, offset, limit, workstreams.length);
         return {
-            total: workstreams.length,
+            total: matches.length,
             ...(query ? { query } : {}),
             workstreams,
+            pagination,
+            guidance: 'Use get_workstream for details or list_tasks with workstreamId for active tasks.',
         };
     }
     function buildPlanningWriteEntitySummary(targetType, entity) {
@@ -3626,7 +3774,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,
@@ -3673,7 +3821,7 @@ export function createTaskforceMcpServer(options = {}) {
             resources,
         };
     });
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    server.setRequestHandler('resources/templates/list', async () => {
         if (!hasPermission(RESOURCE_PERMISSIONS.task)) {
             return { resourceTemplates: [] };
         }
@@ -3705,7 +3853,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) {
@@ -3811,24 +3959,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
      */
@@ -3843,7 +3993,9 @@ export function createTaskforceMcpServer(options = {}) {
     registerAdminWorkspaceTools(registerTool, (name, args) => executeRegisteredTool(name, args));
     const mutatingProfileTokenProperty = {
         type: 'string',
-        description: 'Optional profileToken from resolve_profile for stateless MCP clients.'
+        description: requiresExplicitTokenAuthorship
+            ? 'Required authorship proof for cloud access-token clients; obtain from resolve_profile.'
+            : 'Optional profileToken from resolve_profile for stateless MCP clients.'
     };
     const nonDestructiveWriteTools = new Set([
         'add_annotated_attachment_marker',
@@ -3876,6 +4028,9 @@ export function createTaskforceMcpServer(options = {}) {
             get priorityDesc() {
                 return `Priority level: ${getActivePriorities().map((priority) => `${priority.value} (${priority.label})`).join(', ')}`;
             },
+            get priorityEnum() {
+                return getActivePriorities().map((priority) => priority.value);
+            },
             get typeEnum() {
                 return getActiveTypes().map((type) => type.value);
             },
@@ -3916,6 +4071,11 @@ export function createTaskforceMcpServer(options = {}) {
             inputSchema: {
                 ...descriptor.inputSchema,
                 properties,
+                ...(requiresExplicitTokenAuthorship
+                    && descriptor.name !== 'resolve_profile'
+                    && isMcpWriteToolName(descriptor.name)
+                    ? { required: Array.from(new Set([...(descriptor.inputSchema.required || []), 'profileToken'])) }
+                    : {}),
                 additionalProperties: false,
             },
             annotations: {
@@ -3934,16 +4094,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);
@@ -4863,7 +5026,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,
@@ -4883,7 +5048,7 @@ export function createTaskforceMcpServer(options = {}) {
                 });
             },
         }),
-        resolveReviewer: (task) => resolveFinishTaskReviewer(task),
+        resolveReviewer: (task, reviewer) => resolveFinishTaskReviewer(task, reviewer),
     });
     const planningCommandPreparationService = new PlanningCommandPreparationService({
         resolveOwner: resolvePlanningOwnerInput,
@@ -4896,12 +5061,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({
@@ -4924,7 +5094,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);
@@ -4992,15 +5162,15 @@ export function createTaskforceMcpServer(options = {}) {
                     : resolveWorkstreamByIdentifierOrThrow(workstreamId).id;
                 const paginated = resolvedWorkstreamId !== undefined || offset !== undefined;
                 const parsedOffset = offset === undefined ? 0 : Number(offset);
-                if (!Number.isFinite(parsedOffset) || parsedOffset < 0)
-                    throw new McpPublicError('offset must be a non-negative number');
-                const normalizedOffset = Math.floor(parsedOffset);
+                if (!Number.isInteger(parsedOffset) || parsedOffset < 0)
+                    throw new McpPublicError('offset must be a non-negative integer');
+                const normalizedOffset = parsedOffset;
                 const parsedLimit = limit === undefined ? (paginated ? 50 : 0) : Number(limit);
-                if (!Number.isFinite(parsedLimit) || parsedLimit < 0)
-                    throw new McpPublicError('limit must be a non-negative number');
+                if (!Number.isInteger(parsedLimit) || parsedLimit < 0 || parsedLimit > 200)
+                    throw new McpPublicError('limit must be an integer from 1 to 200');
                 const normalizedLimit = paginated
-                    ? Math.min(200, Math.max(1, Math.floor(parsedLimit || 50)))
-                    : Math.floor(parsedLimit);
+                    ? (parsedLimit || 50)
+                    : parsedLimit;
                 const queriedTasks = core.listTasksSlim(ACTIVE_WORKSPACE_ID, {
                     category,
                     status,
@@ -5087,6 +5257,15 @@ export function createTaskforceMcpServer(options = {}) {
                     failAiProfileBindingConflict('The selected AI profile conflicts with the profile already bound to this MCP session or authenticated connection.', { reason: 'selected_profile_mismatch', boundProfileId: alreadyBoundProfile.id, selectedProfileId: explicitlySelectedProfile.id });
                 }
                 const boundProfile = alreadyBoundProfile || explicitlySelectedProfile;
+                if (!boundProfile && suppliedProfileToken) {
+                    const suppliedProfile = core.getAiProfileByToken({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        profileToken: suppliedProfileToken,
+                        seatScope: configuredAiProfileSeatScope,
+                    });
+                    if (suppliedProfile)
+                        assertOAuthProfileClientCompatibility(suppliedProfile);
+                }
                 if (boundProfile && suppliedProfileToken) {
                     const tokenProfile = core.getAiProfileByToken({
                         workspaceId: ACTIVE_WORKSPACE_ID,
@@ -5291,10 +5470,19 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "search_tasks": {
-                const { query, scope = "all" } = args;
-                const results = core.searchTaskSummaries(query, scope, ACTIVE_WORKSPACE_ID);
+                const { query, scope = "all", limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 25);
+                const queried = core.searchTaskSummaries(query, scope, ACTIVE_WORKSPACE_ID, {
+                    limit: page.limit + 1,
+                    offset: page.offset,
+                });
+                const hasMore = queried.length > page.limit;
+                const results = hasMore ? queried.slice(0, page.limit) : queried;
                 return {
-                    content: [{ type: "text", text: renderTaskTable(results) }],
+                    content: [{
+                            type: "text",
+                            text: `${renderTaskTable(results)}\n\nPage: offset ${page.offset}, limit ${page.limit}, returned ${results.length}, hasMore ${hasMore}${hasMore ? `, nextOffset ${page.offset + results.length}` : ''}`,
+                        }],
                 };
             }
             case "get_task": {
@@ -5347,6 +5535,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 }),
@@ -5358,11 +5549,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();
@@ -5375,7 +5578,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;
@@ -5397,7 +5600,7 @@ export function createTaskforceMcpServer(options = {}) {
                         }).completeStep({
                             executionId,
                             expectedStepId: stepId,
-                            evidenceCommentId,
+                            evidenceCommentId: normalizedEvidenceCommentId,
                         })
                         : executionService.completeCurrentStep({
                             workspaceId: ACTIVE_WORKSPACE_ID,
@@ -5405,7 +5608,7 @@ export function createTaskforceMcpServer(options = {}) {
                             actorId: agentProfileId,
                             actorType: 'agent',
                             expectedStepId: stepId,
-                            evidenceCommentId,
+                            evidenceCommentId: normalizedEvidenceCommentId,
                             idempotencyKey,
                         });
                 }
@@ -5498,9 +5701,10 @@ export function createTaskforceMcpServer(options = {}) {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case "list_initiatives": {
-                const { query } = args;
+                const { query, limit, offset } = args;
+                const page = normalizePlanningReadPage(limit, offset);
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativesResourcePayload({ query }), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildInitiativesResourcePayload({ query, ...page }), null, 2) }],
                 };
             }
             case "get_initiative": {
@@ -5771,9 +5975,10 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "list_workstreams": {
-                const { query } = args;
+                const { query, limit, offset } = args;
+                const page = normalizePlanningReadPage(limit, offset);
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamsResourcePayload({ query }), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamsResourcePayload({ query, ...page }), null, 2) }],
                 };
             }
             case "get_workstream": {
@@ -6060,12 +6265,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),
                         }],
@@ -6135,6 +6342,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;
@@ -6190,8 +6440,11 @@ export function createTaskforceMcpServer(options = {}) {
             }
             case "search_images": {
                 assertAnnotatedAttachmentReadAccess();
-                const { query, limit } = args;
-                const results = searchImageAssets(query, { limit }).map(({ asset, matchedOn, score }) => ({
+                const { query, limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 10);
+                const queried = searchImageAssets(query, { limit: page.limit + 1, offset: page.offset });
+                const hasMore = queried.length > page.limit;
+                const results = (hasMore ? queried.slice(0, page.limit) : queried).map(({ asset, matchedOn, score }) => ({
                     image: buildImageDescriptor(asset),
                     matchedOn,
                     score,
@@ -6207,6 +6460,13 @@ export function createTaskforceMcpServer(options = {}) {
                                 workspaceId: ACTIVE_WORKSPACE_ID,
                                 query: typeof query === 'string' ? query.trim() : '',
                                 results,
+                                pagination: {
+                                    offset: page.offset,
+                                    limit: page.limit,
+                                    returned: results.length,
+                                    hasMore,
+                                    ...(hasMore ? { nextOffset: page.offset + results.length } : {}),
+                                },
                                 guidance: results.length > 0
                                     ? 'After picking a match, call get_image with the suggestedArgs.imageId to inspect linked tasks and image notes.'
                                     : 'No matching canonical images were found. Try an I-123 reference, title keyword, or filename fragment.',
@@ -6277,8 +6537,11 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "search_documents": {
-                const { query, limit } = args;
-                const results = searchDocumentAssets(query, { limit }).map(({ asset, matchedOn, score }) => ({
+                const { query, limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 10);
+                const queried = searchDocumentAssets(query, { limit: page.limit + 1, offset: page.offset });
+                const hasMore = queried.length > page.limit;
+                const results = (hasMore ? queried.slice(0, page.limit) : queried).map(({ asset, matchedOn, score }) => ({
                     document: buildDocumentDescriptor(asset),
                     matchedOn,
                     score,
@@ -6295,6 +6558,13 @@ export function createTaskforceMcpServer(options = {}) {
                                 workspaceId: ACTIVE_WORKSPACE_ID,
                                 query: typeof query === 'string' ? query.trim() : '',
                                 results,
+                                pagination: {
+                                    offset: page.offset,
+                                    limit: page.limit,
+                                    returned: results.length,
+                                    hasMore,
+                                    ...(hasMore ? { nextOffset: page.offset + results.length } : {}),
+                                },
                                 guidance: results.length > 0
                                     ? 'After picking a match, call get_document with the suggestedArgs.documentId. Pass includeContent=true when you need the body.'
                                     : 'No matching canonical documents were found. Try a D-123 reference, document id, title keyword, or filename fragment.',
@@ -6848,14 +7118,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) {
@@ -6867,13 +7163,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(),
@@ -6899,6 +7297,7 @@ export function createTaskforceMcpServer(options = {}) {
                                 },
                                 sessionId: currentSession.id,
                                 sessionAction,
+                                documentVersion: currentSession.documentVersion,
                                 postedCommentIds,
                                 commentCount: postedCommentIds.length,
                                 nextTool: 'get_document_reviews',
@@ -7223,13 +7622,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,
@@ -7348,6 +7740,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`);
@@ -7386,13 +7781,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,
@@ -7776,6 +8171,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;
@@ -7899,8 +8302,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;
@@ -7943,11 +8346,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',
@@ -7956,18 +8359,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));
@@ -7986,14 +8389,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,
@@ -8009,7 +8412,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,
@@ -8019,6 +8426,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 = {}) {
@@ -8034,18 +8451,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 {