@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/mcp/runtime.js

@@ -16,7 +16,7 @@ import { AnnotatedAttachmentCommandError, createAnnotatedAttachmentCommandServic
 import { createDocumentReviewCommandService, DocumentReviewCommandError, } from '../documentReviews/commandService.js';
 import { COMPLEXITY_OPTIONS, resolveNumberOption, resolveStringOption, STATUS_OPTIONS } from './optionResolution.js';
 import { buildResolveAiProfileInputFromBootstrap } from './aiProfileBootstrap.js';
-import { createCanonicalAssetHelpers } from './canonicalAssetHelpers.js';
+import { CanonicalDocumentHeadStaleError, createCanonicalAssetHelpers } from './canonicalAssetHelpers.js';
 import { createDocumentHelpers } from './documentHelpers.js';
 import { createTaskAttachmentHelpers } from './taskAttachmentHelpers.js';
 import { listRegisteredGitWorktreeRoots } from './gitWorktreeRoots.js';
@@ -59,7 +59,7 @@ import { createTaskPlanCommand } from './taskPlanCommand.js';
 import { WorkflowAssignmentService } from '../core/WorkflowAssignmentService.js';
 import { WorkflowExecutionService, WorkflowExecutionServiceError, } from '../core/WorkflowExecutionService.js';
 import { WorkflowStore } from '../storage/workflowStore.js';
-import { getMcpClientRegistryEntry, normalizeMcpConnectionId, parseMcpClientId } from './clientRegistry.js';
+import { getMcpClientRegistryEntry, inferLegacyMcpClientIdFromProfile, normalizeMcpConnectionId, parseMcpClientId } from './clientRegistry.js';
 import { BedrockAvatarImageProvider } from '../services/avatarImageProvider.js';
 import { AiProfileAvatarGenerationError, checkAiProfileAvatarGenerationRateLimit, generateAiProfileAvatar, } from '../services/aiProfileAvatarGenerationService.js';
 import { isAiProfileAvatarGenerationEligible } from '../shared/aiProfileAvatarEligibility.js';
@@ -410,6 +410,22 @@ function resolveRecoverableToolError(error, context) {
         };
     }
     if (error instanceof TaskforceRuleError) {
+        if (code === 'AI_PROFILE_SELECTION_REQUIRED') {
+            const selectionDetails = details && typeof details === 'object' && !Array.isArray(details)
+                ? details
+                : {};
+            const suggestedArgs = selectionDetails.suggestedArgs;
+            return {
+                message,
+                code,
+                details,
+                nextTool: 'resolve_profile',
+                ...(suggestedArgs && typeof suggestedArgs === 'object' && !Array.isArray(suggestedArgs)
+                    ? { suggestedArgs: suggestedArgs }
+                    : {}),
+                retryHint: 'Choose the intended compatible profile candidate and retry resolve_profile with the same name plus its profileId. If more than one candidate is present and the intended identity is unclear, ask the user before selecting.',
+            };
+        }
         if (code === 'AI_PROFILE_AVATAR_PROVIDER_FAILED' || code === 'AI_PROFILE_AVATAR_PERSISTENCE_FAILED') {
             return {
                 message,
@@ -677,6 +693,14 @@ export function buildUnexpectedToolErrorResult(requestId) {
         isError: true,
     };
 }
+function measureToolResultBytes(result) {
+    try {
+        return Buffer.byteLength(JSON.stringify(result), 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
 export function buildBatchToolError(error, fallbackStatusCode) {
     const resolved = resolveRecoverableToolError(error);
     if (!resolved) {
@@ -786,6 +810,29 @@ export function createTaskforceMcpServer(options = {}) {
     }
     const mcpRequestIdentity = new AsyncLocalStorage();
     const cloudCreateRequestIdentity = new AsyncLocalStorage();
+    const mcpToolSubphaseTimings = new AsyncLocalStorage();
+    const measureToolSubphase = (phase, operation) => {
+        const startedAtMs = Date.now();
+        try {
+            return operation();
+        }
+        finally {
+            const timings = mcpToolSubphaseTimings.getStore();
+            if (timings)
+                timings[phase] = (timings[phase] || 0) + (Date.now() - startedAtMs);
+        }
+    };
+    const measureToolSubphaseAsync = async (phase, operation) => {
+        const startedAtMs = Date.now();
+        try {
+            return await operation();
+        }
+        finally {
+            const timings = mcpToolSubphaseTimings.getStore();
+            if (timings)
+                timings[phase] = (timings[phase] || 0) + (Date.now() - startedAtMs);
+        }
+    };
     const operationIdentityScope = options.operationIdentityScope
         ? {
             generation: String(options.operationIdentityScope.generation || '').trim(),
@@ -824,28 +871,34 @@ export function createTaskforceMcpServer(options = {}) {
             return null;
         return `${kind}-${createHash('sha256').update(`${kind}:${requestIdentity}:${discriminator || ''}`).digest('hex').slice(0, 32)}`;
     };
-    const stableTaskCreateIdempotencyId = (kind, idempotencyKey, discriminator) => {
-        const fingerprint = operationIdentityScope
-            ? fingerprintWorkspaceSyncPayload({
-                kind,
-                tenantId,
-                workspaceId: ACTIVE_WORKSPACE_ID,
-                actorRef: getActiveMcpActorRef(),
-                tool: 'create_task',
-                idempotencyKey,
-                discriminator: discriminator || '',
-            })
-            : createHash('sha256').update(JSON.stringify([
-                kind,
-                tenantId,
-                ACTIVE_WORKSPACE_ID,
-                getActiveMcpActorRef(),
-                'create_task',
-                idempotencyKey,
-                discriminator || '',
-            ])).digest('hex');
+    const normalizeExplicitIdempotencyKey = (value) => {
+        if (value === undefined || value === null)
+            return null;
+        const key = String(value).trim();
+        if (!key)
+            throw new McpPublicError('idempotencyKey must contain non-whitespace text.');
+        if (key.length > 128)
+            throw new McpPublicError('idempotencyKey must contain at most 128 characters.');
+        return key;
+    };
+    const stableExplicitMutationId = (kind, tool, idempotencyKey, discriminator) => {
+        const fingerprint = createHash('sha256').update(JSON.stringify([
+            kind,
+            tenantId,
+            ACTIVE_WORKSPACE_ID,
+            getActiveMcpActorRef(),
+            tool,
+            idempotencyKey,
+            discriminator || '',
+        ])).digest('hex');
         return `${kind}-${fingerprint.slice(0, 32)}`;
     };
+    const stableTaskCreateIdempotencyId = (kind, idempotencyKey, discriminator) => stableExplicitMutationId(kind, 'create_task', idempotencyKey, discriminator);
+    const requireDurableExplicitIdempotency = (enabled, tool) => {
+        if (enabled)
+            return;
+        throw new McpPublicError(`idempotencyKey requires the durable ${tool} mutation boundary, which is unavailable for this runtime.`, 'MCP_IDEMPOTENCY_UNAVAILABLE', 503);
+    };
     const durableTaskMutationRouter = options.durableTaskMutationRouter || createDurableTaskMutationRouter({
         core,
         runtimeMode,
@@ -929,7 +982,8 @@ export function createTaskforceMcpServer(options = {}) {
             cloudClientId: 'mcp-cloud',
             createOperationId: () => mutationOptions?.operationId
                 || requireStableMcpRequestId('operation', 'initiative'),
-            createCommentId: () => requireStableMcpRequestId('comment', 'initiative-comment'),
+            createCommentId: () => mutationOptions?.commentId
+                || requireStableMcpRequestId('comment', 'initiative-comment'),
             deferPostCommitNotification: mutationOptions?.deferPostCommitNotification,
         });
     const initiativeFromDurableResult = (result) => result.state === 'pending' ? result.provisionalInitiative : result.authoritativeInitiative;
@@ -946,7 +1000,8 @@ export function createTaskforceMcpServer(options = {}) {
             cloudClientId: 'mcp-cloud',
             createOperationId: () => mutationOptions?.operationId
                 || requireStableMcpRequestId('operation', 'workstream'),
-            createCommentId: () => requireStableMcpRequestId('comment', 'workstream-comment'),
+            createCommentId: () => mutationOptions?.commentId
+                || requireStableMcpRequestId('comment', 'workstream-comment'),
             deferPostCommitNotification: mutationOptions?.deferPostCommitNotification,
         });
     const workstreamFromDurableResult = (result) => result.state === 'pending' ? result.provisionalWorkstream : result.authoritativeWorkstream;
@@ -1049,7 +1104,9 @@ export function createTaskforceMcpServer(options = {}) {
                 legacyProvider: asset.storageProvider,
             });
             return resolved.source === 'versioned'
-                && resolved.contentSha256 === asset.contentSha256;
+                && resolved.storageProvider === asset.storageProvider
+                && resolved.contentSha256 === asset.contentSha256
+                && resolved.sizeBytes === asset.sizeBytes;
         }
         catch {
             return false;
@@ -1243,7 +1300,13 @@ export function createTaskforceMcpServer(options = {}) {
         }
         return { id: task.id, task };
     }
-    const buildDocumentDescriptor = (asset, options) => (withDocumentUrl(documentHelpers.buildDocumentDescriptor(asset, options)));
+    const buildDocumentDescriptor = (asset, options) => {
+        const descriptor = withDocumentUrl(documentHelpers.buildDocumentDescriptor(asset, options));
+        if (runtimeMode === 'local')
+            return descriptor;
+        const { storageKey: _storageKey, ...cloudDescriptor } = descriptor;
+        return cloudDescriptor;
+    };
     const buildCanonicalDocumentAttachmentHint = documentHelpers.buildCanonicalDocumentAttachmentHint;
     function buildBoundedTextContent(content, maxChars) {
         const requestedMaxChars = Number(maxChars);
@@ -1271,7 +1334,19 @@ export function createTaskforceMcpServer(options = {}) {
                 format: "metadata"
             };
         }
+        const assertCurrentHead = () => {
+            try {
+                canonicalAssetHelpers.assertCanonicalDocumentHeadCurrent(asset);
+            }
+            catch (error) {
+                if (error instanceof CanonicalDocumentHeadStaleError) {
+                    throw new McpPublicError(error.message, error.code, error.statusCode, error.details);
+                }
+                throw error;
+            }
+        };
         if (format === "download") {
+            assertCurrentHead();
             return {
                 format: "download",
                 downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
@@ -1279,6 +1354,7 @@ export function createTaskforceMcpServer(options = {}) {
             };
         }
         if (!isTextReadableMimeType(asset.mimeType || '')) {
+            assertCurrentHead();
             return {
                 format: "download",
                 downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
@@ -1290,6 +1366,9 @@ export function createTaskforceMcpServer(options = {}) {
             buffer = await canonicalAssetHelpers.readCanonicalDocumentBuffer(asset);
         }
         catch (error) {
+            if (error instanceof CanonicalDocumentHeadStaleError) {
+                throw new McpPublicError(error.message, error.code, error.statusCode, error.details);
+            }
             const message = error instanceof Error ? String(error.message || '').trim() : '';
             if (/^Document .+ not found in workspace /i.test(message)) {
                 throw new McpPublicError(message, 'MCP_NOT_FOUND', 404);
@@ -1384,7 +1463,7 @@ export function createTaskforceMcpServer(options = {}) {
             originalFilename: asset.originalFilename ?? null,
             mimeType: asset.mimeType ?? null,
             sizeBytes: typeof asset.sizeBytes === 'number' ? asset.sizeBytes : null,
-            storageKey: asset.storageKey ?? null,
+            ...(runtimeMode === 'local' ? { storageKey: asset.storageKey ?? null } : {}),
             updatedAt: asset.updatedAt ?? null,
             apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}`,
         };
@@ -1396,6 +1475,9 @@ export function createTaskforceMcpServer(options = {}) {
         }
         catch (error) {
             const requestedIdentifier = typeof documentIdentifier === 'string' ? documentIdentifier.trim() : '';
+            if (!requestedIdentifier) {
+                throw new McpPublicError('documentId is required', 'MCP_INVALID_ARGUMENT', 400);
+            }
             if (requestedIdentifier && /not found in workspace/i.test(String(error?.message || error))) {
                 throw new TaskforceRuleError(String(error?.message || error), 404, 'DOCUMENT_NOT_FOUND', {
                     requestedIdentifier,
@@ -1439,6 +1521,7 @@ export function createTaskforceMcpServer(options = {}) {
     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;
+    const configuredAiProfileIdentityAsserted = options.auth?.aiProfileIdentityAsserted === true;
     const configuredAiProfileToken = options.auth?.aiProfileToken ? String(options.auth.aiProfileToken).trim() || null : null;
     const configuredAiProfileName = options.auth?.aiProfileName ? String(options.auth.aiProfileName).trim() || null : null;
     const configuredAiProfileIcon = options.auth?.aiProfileIcon ? String(options.auth.aiProfileIcon).trim() || null : null;
@@ -1456,6 +1539,54 @@ export function createTaskforceMcpServer(options = {}) {
     const auditUserAgent = options.auth?.userAgent ? String(options.auth.userAgent).trim() || null : null;
     let activeAiProfileId = null;
     let activeAiBindingSource = null;
+    let aiProfileIdentityConflictDetected = false;
+    function failAiProfileBindingConflict(message, details) {
+        aiProfileIdentityConflictDetected = true;
+        let credentialRevoked = false;
+        if (auditActorType === 'oauth' && auditTokenId) {
+            core.revokeMcpOAuthConnectorGrant({
+                actorUserId: auditActorUserId,
+                workspaceId: ACTIVE_WORKSPACE_ID,
+                grantId: auditTokenId,
+            });
+            credentialRevoked = true;
+        }
+        throw new TaskforceRuleError(credentialRevoked ? `${message} The conflicting credential was revoked; reconnect before retrying.` : message, 409, 'AI_PROFILE_BINDING_CONFLICT', { ...details, credentialRevoked, nextTool: 'resolve_profile' });
+    }
+    function assertRequestedIdentityMatchesBoundProfile(profile, input) {
+        if (auditActorType !== 'oauth')
+            return;
+        const requestedName = String(input.name || '').trim();
+        const requestedNameKey = requestedName.toLowerCase();
+        const requestedUsernameKey = normalizeConfiguredAiProfileUsername(undefined, requestedName).toLowerCase();
+        const boundNameKey = String(profile.name || '').trim().toLowerCase();
+        const boundUsernameKey = String(profile.username || '').trim().toLowerCase();
+        const nameMatches = Boolean(requestedNameKey) && (requestedNameKey === boundNameKey
+            || requestedNameKey === boundUsernameKey
+            || requestedUsernameKey === boundUsernameKey);
+        const normalizeProvider = (value) => String(value || '')
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '');
+        const requestedProvider = normalizeProvider(input.provider);
+        const boundProvider = normalizeProvider(profile.provider);
+        const providerConflicts = Boolean(requestedProvider && boundProvider && requestedProvider !== boundProvider);
+        if (nameMatches && !providerConflicts)
+            return;
+        failAiProfileBindingConflict('The requested AI identity conflicts with the profile already bound to this OAuth connection.', {
+            reason: 'requested_identity_mismatch',
+            boundProfile: {
+                id: profile.id,
+                name: profile.name,
+                username: profile.username,
+                provider: profile.provider || null,
+            },
+            requestedIdentity: {
+                name: requestedName || null,
+                provider: String(input.provider || '').trim() || null,
+            },
+        });
+    }
     function applyConfiguredMcpClientContext(profileId) {
         const shouldBindOAuthGrant = auditActorType === 'oauth'
             && Boolean(auditTokenId)
@@ -1541,6 +1672,7 @@ export function createTaskforceMcpServer(options = {}) {
             workspaceId: ACTIVE_WORKSPACE_ID,
             connectionId: configuredMcpConnectionId,
             seatScope: configuredAiProfileSeatScope,
+            repairLegacyBinding: options?.repairConnection !== false,
         });
         if (!match && auditActorType !== 'oauth' && configuredMcpClientId && configuredMcpClientId !== 'general') {
             const candidates = core.listAiProfiles(ACTIVE_WORKSPACE_ID).filter((profile) => {
@@ -1551,12 +1683,14 @@ export function createTaskforceMcpServer(options = {}) {
                     && connection.clientId === configuredMcpClientId);
             });
             if (candidates.length === 1) {
-                match = core.bindAiProfileConnection({
-                    workspaceId: ACTIVE_WORKSPACE_ID,
-                    profileId: candidates[0].id,
-                    connectionId: configuredMcpConnectionId,
-                    clientId: configuredMcpClientId,
-                });
+                match = options?.repairConnection === false
+                    ? candidates[0]
+                    : core.bindAiProfileConnection({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        profileId: candidates[0].id,
+                        connectionId: configuredMcpConnectionId,
+                        clientId: configuredMcpClientId,
+                    });
             }
         }
         if (match?.archivedAt) {
@@ -1575,6 +1709,8 @@ export function createTaskforceMcpServer(options = {}) {
                 mergeTarget = next;
             }
             if (!mergeTarget.archivedAt) {
+                if (options?.repairConnection === false)
+                    return mergeTarget;
                 return core.bindAiProfileConnection({
                     workspaceId: ACTIVE_WORKSPACE_ID,
                     profileId: mergeTarget.id,
@@ -1622,7 +1758,7 @@ export function createTaskforceMcpServer(options = {}) {
         const grantProfile = findProfileForConfiguredGrant();
         const connectionProfile = findProfileForConfiguredConnection(options);
         if (grantProfile && connectionProfile && grantProfile.id !== connectionProfile.id) {
-            throw new TaskforceRuleError('The authenticated OAuth grant and MCP connection are bound to different AI profiles. Select the intended profile in Taskforce before retrying.', 409, 'AI_PROFILE_BINDING_CONFLICT', { grantProfileId: grantProfile.id, connectionProfileId: connectionProfile.id });
+            failAiProfileBindingConflict('The authenticated OAuth grant and MCP connection are bound to different AI profiles. Select the intended profile in Taskforce before retrying.', { reason: 'grant_connection_mismatch', grantProfileId: grantProfile.id, connectionProfileId: connectionProfile.id });
         }
         const profile = grantProfile || connectionProfile;
         if (profile && configuredMcpConnectionId && !connectionProfile && options?.repairConnection !== false) {
@@ -1635,6 +1771,38 @@ export function createTaskforceMcpServer(options = {}) {
         }
         return profile;
     }
+    function listSelectableOAuthProfiles(profileName) {
+        if (auditActorType !== 'oauth')
+            return [];
+        const requestedName = String(profileName || '').trim().toLowerCase();
+        if (!requestedName)
+            return [];
+        const requestedUsername = normalizeConfiguredAiProfileUsername(undefined, requestedName).toLowerCase();
+        const restorableProfileIds = !configuredMcpClientId && auditTokenId
+            ? new Set(core.listMcpOAuthRestorableAiProfileIds({
+                grantId: auditTokenId,
+                workspaceId: ACTIVE_WORKSPACE_ID,
+            }))
+            : null;
+        return core.listAiProfiles(ACTIVE_WORKSPACE_ID).filter((profile) => {
+            if ((profile.seatScope ?? null) !== configuredAiProfileSeatScope)
+                return false;
+            const profileNameMatches = profile.name.trim().toLowerCase() === requestedName
+                || profile.username.trim().toLowerCase() === requestedUsername;
+            if (!profileNameMatches)
+                return false;
+            const connection = profile.providerMetadata?.connection;
+            const storedClientId = connection && typeof connection === 'object' && !Array.isArray(connection)
+                ? parseMcpClientId(connection.clientId)
+                : null;
+            const inferredClientId = inferLegacyMcpClientIdFromProfile(profile);
+            if (!configuredMcpClientId)
+                return restorableProfileIds?.has(profile.id) === true;
+            return storedClientId
+                ? storedClientId === configuredMcpClientId
+                : inferredClientId === configuredMcpClientId;
+        });
+    }
     function getEligibleAssigneeActors() {
         return core.listAssignableActors(ACTIVE_WORKSPACE_ID)
             .filter((actor) => String(actor.id || '').trim().toLowerCase() !== 'agent')
@@ -1646,7 +1814,7 @@ export function createTaskforceMcpServer(options = {}) {
             .filter((actor) => Boolean(actor.id));
     }
     function describeEligibleAssignees() {
-        return "Use 'self' for the active AI profile, 'unassigned' to clear ownership, or an eligible ID from list_assignees.";
+        return "Use 'self', 'unassigned', or an ID from list_assignees.";
     }
     function buildEligibleAssigneePayload() {
         return core.listAssignableActors(ACTIVE_WORKSPACE_ID)
@@ -2215,8 +2383,14 @@ export function createTaskforceMcpServer(options = {}) {
     function ensureResolvedProfileFromConnection(defaults) {
         if (activeAiProfileId)
             return;
-        const boundProfile = findTrustedBoundProfile();
+        const boundProfile = findTrustedBoundProfile({ repairConnection: false });
         if (boundProfile) {
+            if (configuredAiProfileIdentityAsserted) {
+                assertRequestedIdentityMatchesBoundProfile(boundProfile, {
+                    name: configuredAiProfileName,
+                    provider: configuredAiProfileProvider,
+                });
+            }
             const configuredClientEntry = getMcpClientRegistryEntry(configuredMcpClientId);
             const resolved = core.resolveAiProfile({
                 workspaceId: ACTIVE_WORKSPACE_ID,
@@ -2279,6 +2453,9 @@ export function createTaskforceMcpServer(options = {}) {
             return;
         if (!isMcpWriteToolName(name))
             return;
+        if (aiProfileIdentityConflictDetected) {
+            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 (activeAiProfileId) {
             if (!profileToken)
@@ -2292,7 +2469,7 @@ export function createTaskforceMcpServer(options = {}) {
                 throw new McpPublicError('Invalid AI profile token. Call resolve_profile again and retry.', 'INVALID_AI_PROFILE_TOKEN', 401);
             }
             if (tokenProfile.id !== activeAiProfileId) {
-                throw new TaskforceRuleError('The supplied profile token conflicts with the AI profile already bound to this MCP session.', 409, 'AI_PROFILE_BINDING_CONFLICT', { boundProfileId: activeAiProfileId, suppliedProfileId: tokenProfile.id });
+                failAiProfileBindingConflict('The supplied profile token conflicts with the AI profile already bound to this MCP session.', { reason: 'session_token_mismatch', boundProfileId: activeAiProfileId, suppliedProfileId: tokenProfile.id });
             }
             return;
         }
@@ -2306,6 +2483,20 @@ export function createTaskforceMcpServer(options = {}) {
             seatScope: configuredAiProfileSeatScope,
         });
         if (profile) {
+            const trustedBoundProfile = findTrustedBoundProfile({ repairConnection: false });
+            if (trustedBoundProfile && trustedBoundProfile.id !== profile.id) {
+                failAiProfileBindingConflict('The supplied profile token conflicts with the profile already bound to this OAuth grant or MCP connection.', {
+                    reason: 'stateless_token_mismatch',
+                    boundProfileId: trustedBoundProfile.id,
+                    suppliedProfileId: profile.id,
+                });
+            }
+            if (trustedBoundProfile && configuredAiProfileIdentityAsserted) {
+                assertRequestedIdentityMatchesBoundProfile(trustedBoundProfile, {
+                    name: configuredAiProfileName,
+                    provider: configuredAiProfileProvider,
+                });
+            }
             activateAiProfile(profile.id, 'token_lookup');
             return;
         }
@@ -3049,15 +3240,11 @@ export function createTaskforceMcpServer(options = {}) {
             || planningSearchIncludes(initiative?.referenceLabel || formatInitiativeReference(initiative?.referenceNumber), query)
             || planningSearchIncludes(initiative?.title, query);
     }
-    function buildHistoricalWorkspaceTaskSnapshot() {
-        const activeTasks = core.listTasks(ACTIVE_WORKSPACE_ID).tasks;
-        const archivedTasks = core.listArchive(ACTIVE_WORKSPACE_ID).archived;
-        const byId = new Map();
-        for (const task of activeTasks)
-            byId.set(task.id, task);
-        for (const task of archivedTasks)
-            byId.set(task.id, task);
-        const tasks = Array.from(byId.values());
+    function buildHistoricalWorkspaceTaskSnapshot(workstreamId) {
+        const tasks = core.listTasksSlim(ACTIVE_WORKSPACE_ID, {
+            ...(workstreamId ? { workstreamId } : {}),
+            includeArchived: true,
+        });
         const tasksByWorkstreamId = new Map();
         for (const task of tasks) {
             const normalizedWorkstreamId = String(task.workstreamId || '').trim();
@@ -3090,6 +3277,34 @@ export function createTaskforceMcpServer(options = {}) {
             semantics: 'historical: active + archived',
         };
     }
+    function emptyPlanningTaskCounts() {
+        return buildPlanningTaskCounts([]);
+    }
+    function buildHistoricalTaskCountSnapshot(workstreamId) {
+        return new Map(core.listTaskCountsByWorkstream(ACTIVE_WORKSPACE_ID, workstreamId).map((entry) => [
+            entry.workstreamId,
+            {
+                total: entry.total,
+                active: entry.active,
+                archived: entry.archived,
+                semantics: 'historical: active + archived',
+            },
+        ]));
+    }
+    function sumPlanningTaskCounts(workstreams, countsByWorkstreamId) {
+        let total = 0;
+        let active = 0;
+        let archived = 0;
+        for (const workstream of workstreams) {
+            const counts = countsByWorkstreamId.get(workstream.id);
+            if (!counts)
+                continue;
+            total += counts.total;
+            active += counts.active;
+            archived += counts.archived;
+        }
+        return { total, active, archived, semantics: 'historical: active + archived' };
+    }
     function buildPlanningWorkstreamCounts(workstreams) {
         const active = workstreams.filter((workstream) => !workstream?.isArchived).length;
         const archived = workstreams.length - active;
@@ -3192,16 +3407,19 @@ export function createTaskforceMcpServer(options = {}) {
         };
     }
     function buildInitiativeResourcePayload(initiative, options) {
-        const tasksByWorkstreamId = options?.tasksByWorkstreamId || buildHistoricalWorkspaceTaskSnapshot().tasksByWorkstreamId;
+        if (options?.detail === 'history') {
+            return buildPlanningHistoryPayload('initiative', initiative, options.offset ?? 0, options.limit ?? 25);
+        }
         const workstreams = options?.workstreamsByInitiativeId?.get(initiative.id)
             || core.listWorkstreams(ACTIVE_WORKSPACE_ID)
                 .filter((workstream) => workstream.initiativeId === initiative.id);
-        const tasks = workstreams.flatMap((workstream) => tasksByWorkstreamId.get(workstream.id) || []);
+        const taskCountsByWorkstreamId = options?.taskCountsByWorkstreamId || buildHistoricalTaskCountSnapshot();
+        const taskCounts = sumPlanningTaskCounts(workstreams, taskCountsByWorkstreamId);
         if (options?.detail === 'compact') {
             return {
                 initiative: buildPlanningInitiativeSummary(initiative),
                 workstreamCount: workstreams.length,
-                taskCount: tasks.length,
+                taskCount: taskCounts.total,
                 nextDetailOption: 'full',
             };
         }
@@ -3215,13 +3433,12 @@ export function createTaskforceMcpServer(options = {}) {
                 initiative: withPlanningEntityUrl('initiative', buildPlanningEntityMetadata('initiative', initiative)),
                 attachments: listPlanningAttachmentDescriptors({ id: initiative.id, entity: initiative }),
                 workstreamCounts: buildPlanningWorkstreamCounts(workstreams),
-                taskCounts: buildPlanningTaskCounts(tasks),
+                taskCounts,
                 workstreams: page.map((workstream) => {
-                    const workstreamTasks = tasksByWorkstreamId.get(workstream.id) || [];
                     return {
                         workstream: buildPlanningWorkstreamSummary(workstream),
                         attachments: listPlanningAttachmentDescriptors({ id: workstream.id, entity: workstream }),
-                        taskCounts: buildPlanningTaskCounts(workstreamTasks),
+                        taskCounts: taskCountsByWorkstreamId.get(workstream.id) || emptyPlanningTaskCounts(),
                     };
                 }),
                 pagination,
@@ -3237,27 +3454,38 @@ export function createTaskforceMcpServer(options = {}) {
                 } : { truncated: false }),
             };
         }
-        if (options?.detail === 'history') {
-            return buildPlanningHistoryPayload('initiative', initiative, options.offset ?? 0, options.limit ?? 25);
-        }
         return {
             initiative: buildPlanningInitiativeDetail(initiative),
             workstreamCount: workstreams.length,
-            taskCount: tasks.length,
+            taskCount: taskCounts.total,
             workstreams: workstreams.map((workstream) => buildPlanningWorkstreamSummary(workstream)),
         };
     }
     function buildWorkstreamResourcePayload(workstream, options) {
-        const tasksByWorkstreamId = options?.tasksByWorkstreamId || buildHistoricalWorkspaceTaskSnapshot().tasksByWorkstreamId;
-        const tasks = tasksByWorkstreamId.get(workstream.id)
-            || [];
+        if (options?.detail === 'history') {
+            return buildPlanningHistoryPayload('workstream', workstream, options.offset ?? 0, options.limit ?? 25);
+        }
         const workstreamReference = typeof workstream.referenceLabel === 'string'
             ? workstream.referenceLabel
             : formatWorkstreamReference(workstream);
+        if (options?.detail !== 'compact' && options?.detail !== 'planning') {
+            const tasksByWorkstreamId = options?.tasksByWorkstreamId
+                || buildHistoricalWorkspaceTaskSnapshot(workstream.id).tasksByWorkstreamId;
+            const tasks = tasksByWorkstreamId.get(workstream.id) || [];
+            return {
+                workstream: buildPlanningWorkstreamDetail(workstream),
+                taskCount: tasks.length,
+                tasks,
+                nextTaskTool: 'list_tasks',
+                suggestedTaskArgs: { workstreamId: workstreamReference, format: 'json', limit: 50, offset: 0 },
+            };
+        }
+        const taskCounts = (options?.taskCountsByWorkstreamId || buildHistoricalTaskCountSnapshot(workstream.id))
+            .get(workstream.id) || emptyPlanningTaskCounts();
         if (options?.detail === 'compact') {
             return {
                 workstream: buildPlanningWorkstreamSummary(workstream),
-                taskCount: tasks.length,
+                taskCount: taskCounts.total,
                 nextDetailOption: 'full',
                 nextTaskTool: 'list_tasks',
                 suggestedTaskArgs: { workstreamId: workstreamReference, format: 'json', limit: 50, offset: 0 },
@@ -3267,22 +3495,13 @@ export function createTaskforceMcpServer(options = {}) {
             return {
                 workstream: withPlanningEntityUrl('workstream', buildPlanningEntityMetadata('workstream', workstream)),
                 attachments: listPlanningAttachmentDescriptors({ id: workstream.id, entity: workstream }),
-                taskCounts: buildPlanningTaskCounts(tasks),
+                taskCounts,
                 nextTaskTool: 'list_tasks',
                 suggestedTaskArgs: { workstreamId: workstreamReference, format: 'json', limit: 50, offset: 0 },
                 guidance: 'taskCounts are historical (active + archived). list_tasks returns bounded active task rows; use search_tasks with scope=archive for archived task discovery.',
             };
         }
-        if (options?.detail === 'history') {
-            return buildPlanningHistoryPayload('workstream', workstream, options.offset ?? 0, options.limit ?? 25);
-        }
-        return {
-            workstream: buildPlanningWorkstreamDetail(workstream),
-            taskCount: tasks.length,
-            tasks,
-            nextTaskTool: 'list_tasks',
-            suggestedTaskArgs: { workstreamId: workstreamReference, format: 'json', limit: 50, offset: 0 },
-        };
+        throw new Error(`Unhandled workstream detail: ${options?.detail}`);
     }
     function buildInitiativesResourcePayload(options) {
         const query = normalizePlanningSearchQuery(options?.query);
@@ -3296,12 +3515,12 @@ export function createTaskforceMcpServer(options = {}) {
             current.push(workstream);
             workstreamsByInitiativeId.set(normalizedInitiativeId, current);
         }
-        const { tasksByWorkstreamId } = buildHistoricalWorkspaceTaskSnapshot();
+        const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
         const initiatives = core.listInitiatives(ACTIVE_WORKSPACE_ID)
             .filter((initiative) => matchesInitiativePlanningQuery(initiative, query, workstreamsByInitiativeId.get(initiative.id) || []))
             .map((initiative) => buildInitiativeResourcePayload(initiative, {
             workstreamsByInitiativeId,
-            tasksByWorkstreamId,
+            taskCountsByWorkstreamId,
             detail: 'compact',
         }));
         return {
@@ -3316,10 +3535,10 @@ export function createTaskforceMcpServer(options = {}) {
         for (const initiative of core.listInitiatives(ACTIVE_WORKSPACE_ID)) {
             initiativesById.set(initiative.id, initiative);
         }
-        const { tasksByWorkstreamId } = buildHistoricalWorkspaceTaskSnapshot();
+        const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
         const workstreams = core.listWorkstreams(ACTIVE_WORKSPACE_ID)
             .filter((workstream) => matchesWorkstreamPlanningQuery(workstream, query, initiativesById.get(workstream.initiativeId || '')))
-            .map((workstream) => buildWorkstreamResourcePayload(workstream, { tasksByWorkstreamId, detail: 'compact' }));
+            .map((workstream) => buildWorkstreamResourcePayload(workstream, { taskCountsByWorkstreamId, detail: 'compact' }));
         return {
             total: workstreams.length,
             ...(query ? { query } : {}),
@@ -3631,6 +3850,7 @@ export function createTaskforceMcpServer(options = {}) {
         'add_comment',
         'add_document_review_comment',
         'add_initiative_comment',
+        'add_task_checklist_item',
         'add_workstream_comment',
         'bulk_add_annotated_attachment_markers',
         'create_annotated_attachment_session',
@@ -3639,6 +3859,7 @@ export function createTaskforceMcpServer(options = {}) {
         'create_task',
         'create_workstream',
         'link_document',
+        'link_task_relationship',
         'rehome_document',
         'link_task_context',
         'resolve_profile',
@@ -3662,7 +3883,7 @@ export function createTaskforceMcpServer(options = {}) {
             get assigneeHint() {
                 return describeEligibleAssignees();
             },
-            describeTool: (text) => `[Project: ${PROJECT_NAME}] ${text}`,
+            describeTool: (text) => text,
         };
     };
     const titleForTool = (name) => String(name || '')
@@ -4529,6 +4750,7 @@ export function createTaskforceMcpServer(options = {}) {
                                     uploadDraftId: result.uploadDraftId,
                                     mimeType: result.mimeType,
                                     uploadedPath: result.uploadedPath,
+                                    ...(result.displayName ? { displayName: result.displayName } : {}),
                                     ...(result.caption ? { caption: result.caption } : {}),
                                     ...(result.overwrite ? { overwrite: true } : {}),
                                     ...(result.expectedSizeBytes !== undefined ? { expectedSizeBytes: result.expectedSizeBytes } : {}),
@@ -4827,8 +5049,12 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "resolve_profile": {
-                const { name: profileName, icon, color, description, role, provider, model, surfaceType, profileToken } = args;
+                const { name: profileName, icon, color, description, role, provider, model, surfaceType, profileId, profileToken } = args;
+                if (aiProfileIdentityConflictDetected) {
+                    throw new TaskforceRuleError('This MCP session is quarantined after a profile identity conflict. Reconnect with the intended profile before retrying.', 409, 'AI_PROFILE_BINDING_CONFLICT', { reason: 'session_identity_quarantined', nextTool: 'resolve_profile' });
+                }
                 const suppliedProfileToken = typeof profileToken === 'string' ? profileToken.trim() : '';
+                const selectedProfileId = typeof profileId === 'string' ? profileId.trim() : '';
                 const sessionBoundProfile = activeAiProfileId
                     ? core.listAiProfiles(ACTIVE_WORKSPACE_ID, { includeArchived: true })
                         .find((profile) => profile.id === activeAiProfileId) || null
@@ -4841,9 +5067,26 @@ export function createTaskforceMcpServer(options = {}) {
                     repairConnection: false,
                 });
                 if (sessionBoundProfile && trustedBoundProfile && sessionBoundProfile.id !== trustedBoundProfile.id) {
-                    throw new TaskforceRuleError('The MCP session and authenticated connection are bound to different AI profiles. Reconnect before retrying.', 409, 'AI_PROFILE_BINDING_CONFLICT', { sessionProfileId: sessionBoundProfile.id, trustedProfileId: trustedBoundProfile.id });
+                    failAiProfileBindingConflict('The MCP session and authenticated connection are bound to different AI profiles. Reconnect before retrying.', { reason: 'session_connection_mismatch', sessionProfileId: sessionBoundProfile.id, trustedProfileId: trustedBoundProfile.id });
+                }
+                const selectableProfiles = listSelectableOAuthProfiles(profileName);
+                const explicitlySelectedProfile = selectedProfileId
+                    ? selectableProfiles.find((profile) => profile.id === selectedProfileId) || null
+                    : null;
+                if (selectedProfileId && !explicitlySelectedProfile) {
+                    throw new TaskforceRuleError('The selected AI profile is not an active compatible identity for this OAuth client and requested name.', 409, 'AI_PROFILE_SELECTION_INVALID', { selectedProfileId });
+                }
+                const alreadyBoundProfile = sessionBoundProfile || trustedBoundProfile;
+                if (alreadyBoundProfile) {
+                    assertRequestedIdentityMatchesBoundProfile(alreadyBoundProfile, {
+                        name: profileName,
+                        provider,
+                    });
                 }
-                const boundProfile = sessionBoundProfile || trustedBoundProfile;
+                if (alreadyBoundProfile && explicitlySelectedProfile && alreadyBoundProfile.id !== explicitlySelectedProfile.id) {
+                    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 tokenProfile = core.getAiProfileByToken({
                         workspaceId: ACTIVE_WORKSPACE_ID,
@@ -4851,7 +5094,7 @@ export function createTaskforceMcpServer(options = {}) {
                         seatScope: configuredAiProfileSeatScope,
                     });
                     if (!tokenProfile || tokenProfile.id !== boundProfile.id) {
-                        throw new TaskforceRuleError('The supplied profile token conflicts with the AI profile already bound to this MCP session or authenticated connection.', 409, 'AI_PROFILE_BINDING_CONFLICT', { boundProfileId: boundProfile.id, ...(tokenProfile ? { suppliedProfileId: tokenProfile.id } : {}) });
+                        failAiProfileBindingConflict('The supplied profile token conflicts with the AI profile already bound to this MCP session or authenticated connection.', { reason: 'bound_token_mismatch', boundProfileId: boundProfile.id, ...(tokenProfile ? { suppliedProfileId: tokenProfile.id } : {}) });
                     }
                 }
                 if (!boundProfile && !suppliedProfileToken && auditActorType === 'oauth') {
@@ -4860,7 +5103,16 @@ export function createTaskforceMcpServer(options = {}) {
                     const hasIdentityCandidate = core.listAiProfiles(ACTIVE_WORKSPACE_ID).some((profile) => ((profile.seatScope ?? null) === configuredAiProfileSeatScope
                         && (profile.name.trim().toLowerCase() === requestedName || profile.username.trim().toLowerCase() === requestedUsername)));
                     if (hasIdentityCandidate) {
-                        throw new TaskforceRuleError('An AI profile with this identity already exists, but it is not bound to this OAuth client. Select the intended profile in Taskforce before retrying.', 409, 'AI_PROFILE_SELECTION_REQUIRED');
+                        const candidates = selectableProfiles.map((profile) => buildAiProfileDescriptor(profile));
+                        const suggestedArgs = candidates.length === 1
+                            ? { name: profileName, profileId: candidates[0].id }
+                            : undefined;
+                        throw new TaskforceRuleError(candidates.length > 0
+                            ? 'An AI profile with this identity already exists but is not bound to this OAuth client. Select a compatible candidate explicitly and retry resolve_profile.'
+                            : 'An AI profile with this identity already exists but is not compatible with this OAuth client. Select the intended profile in Taskforce settings before retrying.', 409, 'AI_PROFILE_SELECTION_REQUIRED', {
+                            candidates,
+                            ...(suggestedArgs ? { suggestedArgs } : {}),
+                        });
                     }
                 }
                 const configuredClientEntry = getMcpClientRegistryEntry(configuredMcpClientId);
@@ -5040,7 +5292,7 @@ export function createTaskforceMcpServer(options = {}) {
             }
             case "search_tasks": {
                 const { query, scope = "all" } = args;
-                const results = core.searchTasks(query, scope, ACTIVE_WORKSPACE_ID);
+                const results = core.searchTaskSummaries(query, scope, ACTIVE_WORKSPACE_ID);
                 return {
                     content: [{ type: "text", text: renderTaskTable(results) }],
                 };
@@ -5200,9 +5452,11 @@ export function createTaskforceMcpServer(options = {}) {
             case "list_task_relationships": {
                 const { taskId, type, direction = 'both' } = args;
                 const { id } = resolveTaskByIdentifierOrThrow(taskId);
-                const relationships = core.listTaskRelationships(id, ACTIVE_WORKSPACE_ID, { type, direction }).map((relationship) => {
-                    const source = core.getTask(relationship.sourceTaskId, ACTIVE_WORKSPACE_ID);
-                    const target = core.getTask(relationship.targetTaskId, ACTIVE_WORKSPACE_ID);
+                const relationshipRows = core.listTaskRelationships(id, ACTIVE_WORKSPACE_ID, { type, direction });
+                const taskSummariesById = new Map(core.listTaskReferenceSummaries(relationshipRows.flatMap((relationship) => [relationship.sourceTaskId, relationship.targetTaskId]), ACTIVE_WORKSPACE_ID).map((task) => [task.id, task]));
+                const relationships = relationshipRows.map((relationship) => {
+                    const source = taskSummariesById.get(relationship.sourceTaskId) || null;
+                    const target = taskSummariesById.get(relationship.targetTaskId) || null;
                     const perspectiveType = relationship.kind === 'dependency'
                         ? (relationship.sourceTaskId === id ? 'depends_on' : 'blocks')
                         : relationship.kind === 'related' ? 'related_to' : 'supersedes';
@@ -5367,12 +5621,21 @@ export function createTaskforceMcpServer(options = {}) {
                 return { content: [{ type: 'text', text: JSON.stringify(linkedResult, null, 2) }] };
             }
             case "create_initiative": {
-                const router = getDurableInitiativeMutationRouter();
+                const { idempotencyKey: rawIdempotencyKey, ...initiativeArgs } = args;
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const operationId = idempotencyKey
+                    ? stableExplicitMutationId('operation', 'create_initiative', idempotencyKey)
+                    : undefined;
+                const router = getDurableInitiativeMutationRouter(operationId ? { operationId } : undefined);
+                if (idempotencyKey)
+                    requireDurableExplicitIdempotency(router.enabled, 'initiative');
                 let prepared;
                 try {
-                    prepared = planningCommandPreparationService.prepareInitiativeCreate(args, {
+                    prepared = planningCommandPreparationService.prepareInitiativeCreate(initiativeArgs, {
                         durable: router.enabled,
-                        entityId: requireStableMcpRequestId('initiative', 'create'),
+                        entityId: idempotencyKey
+                            ? stableExplicitMutationId('initiative', 'create_initiative', idempotencyKey)
+                            : requireStableMcpRequestId('initiative', 'create'),
                         createdAt: new Date().toISOString(),
                     });
                 }
@@ -5421,14 +5684,23 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "add_initiative_comment": {
-                const { id, text } = args;
+                const { id, text, idempotencyKey: rawIdempotencyKey } = args;
                 const { id: initiativeId } = resolveInitiativeByIdentifierOrThrow(id);
                 const validation = validateStructuredCommentForAdd(text);
                 if (!validation.ok) {
                     throw new McpPublicError(validation.message);
                 }
                 const effectiveAuthor = getActiveMcpActorRef();
-                const router = getDurableInitiativeMutationRouter();
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const explicitCommentId = idempotencyKey
+                    ? stableExplicitMutationId('comment', 'add_initiative_comment', idempotencyKey)
+                    : null;
+                const router = getDurableInitiativeMutationRouter(idempotencyKey ? {
+                    operationId: stableExplicitMutationId('operation', 'add_initiative_comment', idempotencyKey),
+                    commentId: explicitCommentId,
+                } : undefined);
+                if (idempotencyKey)
+                    requireDurableExplicitIdempotency(router.enabled, 'initiative comment');
                 const updated = router.enabled
                     ? initiativeFromDurableResult(router.appendComment(initiativeId, {
                         author: effectiveAuthor,
@@ -5440,7 +5712,11 @@ export function createTaskforceMcpServer(options = {}) {
                 if (!updated) {
                     throw new McpPublicError(buildInitiativeLookupFailureMessage(String(id || '').trim()), 'MCP_NOT_FOUND', 404);
                 }
-                const persistedComment = Array.isArray(updated.comments) ? updated.comments.at(-1) : null;
+                const persistedComment = Array.isArray(updated.comments)
+                    ? (explicitCommentId
+                        ? updated.comments.find((candidate) => candidate.id === explicitCommentId) || null
+                        : updated.comments.at(-1) || null)
+                    : null;
                 recordMcpWriteAudit('add_initiative_comment', {
                     entityType: 'initiative',
                     initiativeId: updated.id,
@@ -5454,7 +5730,7 @@ export function createTaskforceMcpServer(options = {}) {
                 return {
                     content: [{ type: "text", text: JSON.stringify(buildPlanningWriteAcknowledgement('initiative', updated, 'add_initiative_comment', {
                                 changedFields: ['comments'],
-                                comment: Array.isArray(updated.comments) ? updated.comments.at(-1) : null,
+                                comment: persistedComment,
                             }), null, 2) }],
                 };
             }
@@ -5515,12 +5791,21 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "create_workstream": {
-                const router = getDurableWorkstreamMutationRouter();
+                const { idempotencyKey: rawIdempotencyKey, ...workstreamArgs } = args;
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const operationId = idempotencyKey
+                    ? stableExplicitMutationId('operation', 'create_workstream', idempotencyKey)
+                    : undefined;
+                const router = getDurableWorkstreamMutationRouter(operationId ? { operationId } : undefined);
+                if (idempotencyKey)
+                    requireDurableExplicitIdempotency(router.enabled, 'workstream');
                 let prepared;
                 try {
-                    prepared = planningCommandPreparationService.prepareWorkstreamCreate(args, {
+                    prepared = planningCommandPreparationService.prepareWorkstreamCreate(workstreamArgs, {
                         durable: router.enabled,
-                        entityId: requireStableMcpRequestId('workstream', 'create'),
+                        entityId: idempotencyKey
+                            ? stableExplicitMutationId('workstream', 'create_workstream', idempotencyKey)
+                            : requireStableMcpRequestId('workstream', 'create'),
                         createdAt: new Date().toISOString(),
                     });
                 }
@@ -5576,43 +5861,64 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "add_workstream_comment": {
-                const { id, text } = args;
-                const { id: workstreamId } = resolveWorkstreamByIdentifierOrThrow(id);
-                const validation = validateStructuredCommentForAdd(text);
-                if (!validation.ok) {
-                    throw new McpPublicError(validation.message);
-                }
-                const effectiveAuthor = getActiveMcpActorRef();
-                const router = getDurableWorkstreamMutationRouter();
-                const updated = router.enabled
-                    ? workstreamFromDurableResult(router.appendComment(workstreamId, {
-                        author: effectiveAuthor,
-                        submittedAuthor: effectiveAuthor,
-                        text,
-                        timestamp: new Date().toISOString(),
-                    }))
-                    : core.addWorkstreamComment(workstreamId, text, effectiveAuthor, ACTIVE_WORKSPACE_ID, { actorRef: effectiveAuthor });
+                const { id, text, idempotencyKey: rawIdempotencyKey } = args;
+                const { id: workstreamId } = measureToolSubphase('lookup', () => resolveWorkstreamByIdentifierOrThrow(id));
+                const { effectiveAuthor, router, comment, explicitCommentId } = measureToolSubphase('prepare', () => {
+                    const validation = validateStructuredCommentForAdd(text);
+                    if (!validation.ok) {
+                        throw new McpPublicError(validation.message);
+                    }
+                    const effectiveAuthor = getActiveMcpActorRef();
+                    const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                    const explicitCommentId = idempotencyKey
+                        ? stableExplicitMutationId('comment', 'add_workstream_comment', idempotencyKey)
+                        : null;
+                    const router = getDurableWorkstreamMutationRouter(idempotencyKey ? {
+                        operationId: stableExplicitMutationId('operation', 'add_workstream_comment', idempotencyKey),
+                        commentId: explicitCommentId,
+                    } : undefined);
+                    if (idempotencyKey)
+                        requireDurableExplicitIdempotency(router.enabled, 'workstream comment');
+                    return {
+                        effectiveAuthor,
+                        router,
+                        explicitCommentId,
+                        comment: {
+                            author: effectiveAuthor,
+                            submittedAuthor: effectiveAuthor,
+                            text,
+                            timestamp: new Date().toISOString(),
+                        },
+                    };
+                });
+                const updated = measureToolSubphase('durable-write', () => router.enabled
+                    ? workstreamFromDurableResult(router.appendComment(workstreamId, comment))
+                    : core.addWorkstreamComment(workstreamId, text, effectiveAuthor, ACTIVE_WORKSPACE_ID, { actorRef: effectiveAuthor }));
                 if (!updated) {
                     throw new McpPublicError(buildWorkstreamLookupFailureMessage(String(id || '').trim()), 'MCP_NOT_FOUND', 404);
                 }
-                const persistedComment = Array.isArray(updated.comments) ? updated.comments.at(-1) : null;
-                recordMcpWriteAudit('add_workstream_comment', {
+                const persistedComment = Array.isArray(updated.comments)
+                    ? (explicitCommentId
+                        ? updated.comments.find((candidate) => candidate.id === explicitCommentId) || null
+                        : updated.comments.at(-1) || null)
+                    : null;
+                measureToolSubphase('audit', () => recordMcpWriteAudit('add_workstream_comment', {
                     entityType: 'workstream',
                     workstreamId: updated.id,
                     commentId: persistedComment?.id || null,
                     contentActorId: effectiveAuthor,
-                });
-                await notifyResourceMutation({
+                }));
+                await measureToolSubphaseAsync('notify', () => notifyResourceMutation({
                     includeWorkstreams: true,
                     workstreamIds: [updated.id],
                     ...(updated.initiativeId ? { includeInitiatives: true, initiativeIds: [updated.initiativeId] } : {}),
-                });
-                return {
+                }));
+                return measureToolSubphase('serialize', () => ({
                     content: [{ type: "text", text: JSON.stringify(buildPlanningWriteAcknowledgement('workstream', updated, 'add_workstream_comment', {
                                 changedFields: ['comments'],
-                                comment: Array.isArray(updated.comments) ? updated.comments.at(-1) : null,
+                                comment: persistedComment,
                             }), null, 2) }],
-                };
+                }));
             }
             case "archive_workstream": {
                 const { id } = args;
@@ -5655,34 +5961,54 @@ export function createTaskforceMcpServer(options = {}) {
             case "update_task_workstream": {
                 const { id: legacyInputId, taskId, workstreamId } = args;
                 const inputId = taskId ?? legacyInputId;
-                const { task } = resolveTaskByIdentifierOrThrow(inputId);
-                let prepared;
-                try {
-                    prepared = planningCommandPreparationService.prepareTaskWorkstreamPlacement(task, workstreamId);
-                }
-                catch (error) {
-                    rethrowPlanningPreparationError(error);
+                const { task } = measureToolSubphase('lookup', () => resolveTaskByIdentifierOrThrow(inputId));
+                const prepared = measureToolSubphase('prepare', () => {
+                    try {
+                        return planningCommandPreparationService.prepareTaskWorkstreamPlacement(task, workstreamId);
+                    }
+                    catch (error) {
+                        return rethrowPlanningPreparationError(error);
+                    }
+                });
+                if (prepared.nextWorkstreamId === prepared.previousWorkstreamId) {
+                    measureToolSubphase('audit', () => recordMcpWriteAudit('update_task_workstream', {
+                        taskId: task.id,
+                        workstreamId: prepared.nextWorkstreamId,
+                        previousWorkstreamId: prepared.previousWorkstreamId,
+                        noOp: true,
+                    }));
+                    return measureToolSubphase('serialize', () => ({
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    task: buildTaskWriteSummary(task),
+                                    workstreamId: prepared.nextWorkstreamId,
+                                    previousWorkstreamId: prepared.previousWorkstreamId,
+                                    noOp: true,
+                                }, null, 2)
+                            }],
+                    }));
                 }
-                const updated = mutateTaskThroughStatusBoundary({
+                const updated = measureToolSubphase('durable-write', () => mutateTaskThroughStatusBoundary({
                     task,
                     updates: { workstreamId: prepared.nextWorkstreamId },
-                });
+                }));
                 if (!updated) {
                     throw new McpPublicError(buildTaskLookupFailureMessage(String(inputId || '').trim()), 'MCP_NOT_FOUND', 404);
                 }
-                recordMcpWriteAudit('update_task_workstream', {
+                measureToolSubphase('audit', () => recordMcpWriteAudit('update_task_workstream', {
                     taskId: updated.id,
                     workstreamId: prepared.nextWorkstreamId,
                     previousWorkstreamId: prepared.previousWorkstreamId,
-                });
-                await notifyResourceMutation({
+                }));
+                await measureToolSubphaseAsync('notify', () => notifyResourceMutation({
                     includeTasks: true,
                     taskIds: [updated.id],
                     ...(prepared.affectedWorkstreamIds.length > 0
                         ? { includeWorkstreams: true, workstreamIds: prepared.affectedWorkstreamIds }
                         : {}),
-                });
-                return {
+                }));
+                return measureToolSubphase('serialize', () => ({
                     content: [{
                             type: "text",
                             text: JSON.stringify({
@@ -5691,7 +6017,7 @@ export function createTaskforceMcpServer(options = {}) {
                                 previousWorkstreamId: prepared.previousWorkstreamId,
                             }, null, 2)
                         }],
-                };
+                }));
             }
             case "update_workstream_initiative": {
                 const { id: legacyInputId, workstreamId, initiativeId } = args;
@@ -6585,7 +6911,7 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "add_document_review_comment": {
-                const { sessionId, body, anchor, parentCommentId } = args;
+                const { sessionId, body, anchor, parentCommentId, idempotencyKey: rawIdempotencyKey } = args;
                 if (!sessionId || typeof sessionId !== 'string') {
                     throw new McpPublicError('sessionId is required');
                 }
@@ -6596,6 +6922,10 @@ export function createTaskforceMcpServer(options = {}) {
                     && Object.prototype.hasOwnProperty.call(args, 'anchor') && anchor !== null && anchor !== undefined) {
                     throw new McpPublicError('Replies cannot have anchors');
                 }
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const idempotentCommentId = idempotencyKey
+                    ? stableExplicitMutationId('comment', 'add_document_review_comment', idempotencyKey)
+                    : null;
                 const session = typeof parentCommentId === 'string' && parentCommentId.trim()
                     ? core.addDocumentReviewReply({
                         workspaceId: ACTIVE_WORKSPACE_ID,
@@ -6603,6 +6933,8 @@ export function createTaskforceMcpServer(options = {}) {
                         parentCommentId: parentCommentId.trim(),
                         body,
                         actorId: getActiveMcpActorRef(),
+                        idempotencyKey,
+                        commentId: idempotentCommentId,
                     })
                     : core.addDocumentReviewComment({
                         workspaceId: ACTIVE_WORKSPACE_ID,
@@ -6610,9 +6942,13 @@ export function createTaskforceMcpServer(options = {}) {
                         body,
                         anchor: anchor ?? null,
                         actorId: getActiveMcpActorRef(),
+                        idempotencyKey,
+                        commentId: idempotentCommentId,
                     });
                 const asset = workspaceAssetStore?.getDocument(session.assetId, ACTIVE_WORKSPACE_ID) || null;
-                const comment = session.comments.at(-1) || null;
+                const comment = idempotentCommentId
+                    ? session.comments.find((candidate) => candidate.id === idempotentCommentId) || null
+                    : session.comments.at(-1) || null;
                 recordMcpWriteAudit('add_document_review_comment', {
                     sessionId: session.id,
                     documentAssetId: session.assetId,
@@ -7150,17 +7486,24 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "add_comment": {
-                const { id: inputId, text } = args;
+                const { id: inputId, text, idempotencyKey: rawIdempotencyKey } = args;
                 const { id, task } = resolveTaskByIdentifierOrThrow(inputId);
                 const validation = validateStructuredCommentForAdd(text);
                 if (!validation.ok) {
                     throw new McpPublicError(validation.message);
                 }
                 const effectiveAuthor = getActiveMcpActorRef();
-                const operationId = requireStableMcpRequestId('operation', `task-comment:${id}`);
-                const commentId = requireStableMcpRequestId('comment', id);
+                const idempotencyKey = normalizeExplicitIdempotencyKey(rawIdempotencyKey);
+                const operationId = idempotencyKey
+                    ? stableExplicitMutationId('operation', 'add_comment', idempotencyKey)
+                    : requireStableMcpRequestId('operation', `task-comment:${id}`);
+                const commentId = idempotencyKey
+                    ? stableExplicitMutationId('comment', 'add_comment', idempotencyKey)
+                    : requireStableMcpRequestId('comment', id);
                 const existingCommentIds = new Set((task.comments || []).map((comment) => comment.id));
                 const durableRouter = getDurableTaskCommentMutationRouter(effectiveAuthor, operationId);
+                if (idempotencyKey)
+                    requireDurableExplicitIdempotency(durableRouter.enabled, 'task comment');
                 const updated = durableRouter.enabled
                     ? durableRouter.append({
                         taskId: id,
@@ -7558,61 +7901,113 @@ export function createTaskforceMcpServer(options = {}) {
     const mcpInputValidator = createMcpInputValidator();
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = resolveMcpToolCallCompatibility(request.params.name, request.params.arguments);
+        const toolStartedAtMs = Date.now();
+        let preparationMs = 0;
+        let validationMs = 0;
+        let handlerMs = 0;
+        let responseBytes = 0;
+        let timingOutcome = 'success';
+        const subphases = {};
         try {
-            assertToolProfile(name);
-            assertToolPermission(name);
-            const handler = toolHandlers.get(name);
-            if (!handler) {
-                throw new Error(`Unknown tool: ${name}`);
+            const preparationStartedAtMs = Date.now();
+            let handler;
+            try {
+                assertToolProfile(name);
+                assertToolPermission(name);
+                handler = toolHandlers.get(name);
+                if (!handler) {
+                    throw new Error(`Unknown tool: ${name}`);
+                }
+                ensureResolvedProfileForTool(name, args);
+                assertResolvedProfileForMutatingTool(name);
+            }
+            finally {
+                preparationMs = Date.now() - preparationStartedAtMs;
             }
-            ensureResolvedProfileForTool(name, args);
-            assertResolvedProfileForMutatingTool(name);
             const execute = () => executeMcpToolWithReadRetry(name, (args || {}), async (validatedArgs) => {
+                const validationStartedAtMs = Date.now();
                 const descriptor = getCurrentToolDescriptor(name);
                 if (!descriptor)
                     throw new Error(`Unknown tool: ${name}`);
                 const validation = mcpInputValidator.validate(name, descriptor.inputSchema, validatedArgs);
+                validationMs += Date.now() - validationStartedAtMs;
                 if (!validation.valid) {
                     throw new McpPublicError(`Arguments for ${name} do not match the declared input schema.`, 'MCP_INVALID_ARGUMENT', 400, { issues: validation.issues });
                 }
-                return await handler(stripMcpEnvelopeArgsForHandler(name, validatedArgs));
+                const handlerStartedAtMs = Date.now();
+                try {
+                    return await mcpToolSubphaseTimings.run(subphases, () => handler(stripMcpEnvelopeArgsForHandler(name, validatedArgs)));
+                }
+                finally {
+                    handlerMs += Date.now() - handlerStartedAtMs;
+                }
             });
-            if (extra.requestId === undefined || extra.requestId === null)
-                return await execute();
-            const transportSessionId = String(extra.sessionId || '').trim();
-            const requestIdentity = operationIdentityScope
-                ? fingerprintWorkspaceSyncPayload({
-                    kind: 'shared-mcp-request',
-                    operationIdentityScope,
-                    transportSessionId: transportSessionId
-                        || options.auth?.mcpConnectionId
-                        || options.auth?.mcpClientId
-                        || 'mcp',
-                    requestId: { type: typeof extra.requestId, value: extra.requestId },
-                    tool: name,
-                })
-                : [
-                    ...(runtimeMode === 'local' || !transportSessionId ? [runtimeRequestNamespace] : []),
+            let result;
+            if (extra.requestId === undefined || extra.requestId === null) {
+                result = await execute();
+            }
+            else {
+                const transportSessionId = String(extra.sessionId || '').trim();
+                const requestIdentity = operationIdentityScope
+                    ? fingerprintWorkspaceSyncPayload({
+                        kind: 'shared-mcp-request',
+                        operationIdentityScope,
+                        transportSessionId: transportSessionId
+                            || options.auth?.mcpConnectionId
+                            || options.auth?.mcpClientId
+                            || 'mcp',
+                        requestId: { type: typeof extra.requestId, value: extra.requestId },
+                        tool: name,
+                    })
+                    : [
+                        ...(runtimeMode === 'local' || !transportSessionId ? [runtimeRequestNamespace] : []),
+                        String(transportSessionId || options.auth?.mcpConnectionId || options.auth?.mcpClientId || 'mcp'),
+                        String(extra.requestId),
+                        name,
+                    ].join(':');
+                const logicalCloudCreateIdentity = [
                     String(transportSessionId || options.auth?.mcpConnectionId || options.auth?.mcpClientId || 'mcp'),
                     String(extra.requestId),
                     name,
                 ].join(':');
-            const logicalCloudCreateIdentity = [
-                String(transportSessionId || options.auth?.mcpConnectionId || options.auth?.mcpClientId || 'mcp'),
-                String(extra.requestId),
-                name,
-            ].join(':');
-            return await cloudCreateRequestIdentity.run(logicalCloudCreateIdentity, () => mcpRequestIdentity.run(requestIdentity, execute));
+                result = await cloudCreateRequestIdentity.run(logicalCloudCreateIdentity, () => mcpRequestIdentity.run(requestIdentity, execute));
+            }
+            responseBytes = measureToolResultBytes(result);
+            return result;
         }
         catch (error) {
+            timingOutcome = 'failure';
             const recoverable = buildRecoverableToolErrorResult(error, auditRequestId);
             if (recoverable) {
-                return {
+                const result = {
                     ...recoverable,
                     isError: true,
                 };
+                responseBytes = measureToolResultBytes(result);
+                return result;
+            }
+            const result = buildUnexpectedToolErrorResult(auditRequestId || extra.requestId);
+            responseBytes = measureToolResultBytes(result);
+            return result;
+        }
+        finally {
+            try {
+                options.onToolCallTiming?.({
+                    requestId: String(auditRequestId || extra.requestId || '').trim() || null,
+                    toolName: name,
+                    isWrite: isMcpWriteToolName(name),
+                    outcome: timingOutcome,
+                    totalMs: Date.now() - toolStartedAtMs,
+                    preparationMs,
+                    validationMs,
+                    handlerMs,
+                    responseBytes,
+                    subphases: { ...subphases },
+                });
+            }
+            catch {
+                // Observability must never change tool behavior.
             }
-            return buildUnexpectedToolErrorResult(auditRequestId || extra.requestId);
         }
     });
     return {