@taskforcehq/taskforce 0.3.323 → 0.3.326

package/dist/mcp/runtime.js

@@ -28,7 +28,8 @@ import { resolveStorageKeyPathInsideRoot } from '../utils/pathSafety.js';
 import { parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { parseAiProfileSeatScope } from '../shared/aiProfileSeatScope.js';
 import { formatInitiativeReference, formatWorkstreamReference, resolveInitiativeReference, parseWorkstreamReference, } from '../utils/planningReferences.js';
-import { MCP_TOOL_PERMISSIONS, MCP_WRITE_TOOL_NAMES } from './toolRegistry.js';
+import { MCP_TOOL_PERMISSIONS, MCP_TOOL_REGISTRY, MCP_WRITE_TOOL_NAMES } from './toolRegistry.js';
+import { getDefaultMcpToolProfile, getMcpToolRequiredProfiles, getMcpToolSuccessor, isMcpToolVisibleInProfile, normalizeMcpToolProfile, } from './toolProfiles.js';
 import { registerAdminWorkspaceTools } from './adminWorkspaceRegistrar.js';
 import { registerCollaborationTools } from './collaborationRegistrar.js';
 import { registerDocumentAssetTools } from './documentAssetRegistrar.js';
@@ -51,6 +52,21 @@ function buildStdioAuthFromEnv() {
         aiProfileSeatScope: parseAiProfileSeatScope(readEnvValue('TASKFORCE_AI_SEAT_SCOPE')),
     };
 }
+class ToolProfileHiddenError extends Error {
+    code = 'TOOL_PROFILE_HIDDEN';
+    activeProfile;
+    requiredProfiles;
+    suggestedTool;
+    constructor(name, activeProfile) {
+        const requiredProfiles = getMcpToolRequiredProfiles(name);
+        const suggestedTool = getMcpToolSuccessor(name);
+        const suffix = suggestedTool ? ` Use ${suggestedTool.name} instead.` : ` Request one of these profiles to use it: ${requiredProfiles.join(', ')}.`;
+        super(`Tool ${name} is not available in the ${activeProfile} MCP tool profile.${suffix}`);
+        this.activeProfile = activeProfile;
+        this.requiredProfiles = requiredProfiles;
+        this.suggestedTool = suggestedTool;
+    }
+}
 export function isMcpWriteToolName(name) {
     return MCP_WRITE_TOOL_NAMES.has(String(name || '').trim());
 }
@@ -154,6 +170,21 @@ function resolveRecoverableToolError(error) {
     const code = error instanceof TaskforceRuleError ? error.code : undefined;
     const statusCode = error instanceof TaskforceRuleError ? error.statusCode : undefined;
     const details = error instanceof TaskforceRuleError ? redactRecoverableErrorDetails(error.details) : undefined;
+    if (error instanceof ToolProfileHiddenError) {
+        return {
+            message,
+            code: error.code,
+            details: {
+                activeProfile: error.activeProfile,
+                requiredProfiles: error.requiredProfiles,
+                ...(error.suggestedTool ? { suggestedTool: error.suggestedTool } : {}),
+            },
+            ...(error.suggestedTool ? {
+                nextTool: error.suggestedTool.name,
+                suggestedArgs: error.suggestedTool.argumentHint || {},
+            } : {}),
+        };
+    }
     if (/^This tool requires an AI profile\./i.test(message)) {
         return {
             message,
@@ -272,6 +303,13 @@ function classifyTransientMcpError(error) {
             retryHint: 'The tool transport failed before Taskforce could return a stable tool response. Retry the same read once; if it repeats, inspect the cloud MCP route logs with this requestId.'
         };
     }
+    if (/(EOF while parsing|Unexpected end of JSON|SyntaxError.*JSON|Unexpected token .*JSON|invalid json response body|non-JSON response|text\/plain|502 Bad Gateway|522 Connection Timed Out|bad gateway|upstream connect error)/i.test(combined)) {
+        return {
+            kind: 'transport_failure',
+            code: 'MCP_TRANSPORT_FAILURE',
+            retryHint: 'The tool transport received an empty or non-JSON response, likely from a gateway interruption. Retry the same read once; if it repeats, inspect the cloud MCP route logs with this requestId.',
+        };
+    }
     if (/(timed out|timeout|ETIMEDOUT|query canceled|statement timeout|database timeout|postgres worker)/i.test(combined)) {
         return {
             kind: 'backend_timeout',
@@ -393,12 +431,16 @@ export function createTaskforceMcpServer(options = {}) {
     const PROJECT_NAME = path.basename(PROJECT_ROOT);
     const logStartup = options.logStartup !== false;
     const runtimeMode = options.runtimeMode === 'cloud' ? 'cloud' : 'local';
+    const defaultToolProfile = getDefaultMcpToolProfile(runtimeMode);
+    const envToolProfile = runtimeMode === 'local' ? readEnvValue('TASKFORCE_MCP_TOOL_PROFILE') : null;
+    const activeToolProfile = normalizeMcpToolProfile(options.toolProfile ?? envToolProfile, defaultToolProfile);
     const allowedScopes = Array.isArray(options.auth?.scopes)
         ? Array.from(new Set(options.auth.scopes))
         : null;
     const configuredAiProfileSeatScope = runtimeMode === 'cloud' ? 'cloud_metered' : 'local_unmetered';
     if (logStartup) {
         console.error(`[Taskforce MCP] Starting for project: ${PROJECT_NAME} at ${PROJECT_ROOT}`);
+        console.error(`[Taskforce MCP] Tool profile: ${activeToolProfile}`);
     }
     const tenantId = String(options.tenantId || options.core?.getTenantId() || process.env.TASKFORCE_TENANT_ID || 'default').trim() || 'default';
     const MCP_SERVER_VERSION = (() => {
@@ -505,7 +547,7 @@ export function createTaskforceMcpServer(options = {}) {
             },
             tools: {},
         },
-        instructions: `You are an AI collaborator connected to Taskforce, a shared task management system for AI-developer pairs.\n\nIMPORTANT: Before mutating Taskforce data, ensure Taskforce knows which AI profile you are acting as. The preferred path is ambient session binding: if your MCP connection is configured with x-taskforce-ai-name and optionally x-taskforce-ai-profile-token headers, Taskforce can auto-bind that AI identity for get_current_profile and later writes. If no AI identity is currently bound, call resolve_profile with your name. Reuse the returned profileToken across sessions, especially for stateless clients.\n\nStateless client pattern: call resolve_profile, save the returned profileToken only in private agent/client state, and include profileToken on later mutating tool calls only when your MCP client does not preserve session identity between calls. Never write profileToken values to repos, task comments, task attachments, logs, generated docs, or shared output.\n\nTo inspect your current attribution state before writes, call get_current_profile. It reports whether identity is bound, how it was resolved, and the suggested args to use with list_tasks.\n\nWhen setting resolve_profile.surfaceType, classify yourself by the kind of identity you are registering: use agent for a persistent named AI collaborator in Taskforce, cli for terminal-native coding agents, coding_tool for coding surfaces that are not specifically CLI or IDE-native, chat_app for a conversational app identity, and ide for an IDE-native copilot identity. If you are unsure or none of those fit, choose agent.\n\nTo get tasks assigned to yourself, call get_current_profile, then use the returned suggestedArgs with list_tasks. When you begin active work on a tracked task, prefer start_task. It sets the task to in-progress and claims it for your AI profile when the task is currently unassigned. When work on a tracked task is complete, prefer finish_task for the final handoff: use outcome='review' when the next step is human validation or approval, and use outcome='done' only when no explicit human action is requested. Do not leave a task in-progress after reporting completed implementation unless the user explicitly wants more work to continue in the same task.\n\nTaxonomy rule: always call get_config before setting category, type, priority, approach, status, or complexity. Do not rely on remembered enum values.\n\nUse identifier prefixes to choose the correct retrieval path: T-123 goes to task tools such as get_task, IN-123 goes to initiative tools such as get_initiative, WS-123 goes to workstream tools such as get_workstream, I-123 goes to image tools such as get_image, and D-123 goes to document tools such as get_document. Do not send I-123 or D-123 identifiers to get_task.\n\nFor annotated images, use search_images first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_image, then use get_annotated_attachment_sessions to list saved sessions, then use read_annotated_attachment_payload for the structured annotation payload. If an image reference is being used for UI, placement, or visual correction feedback, treat the saved annotation payload as the source of truth and do not infer intent from the screenshot alone.\n\nFor documents, use search_documents first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_document, then read_document_content to inspect the document body. For a lower-friction review flow, prefer review_document; otherwise use get_document_review_sessions or create_document_review_session, then add_document_review_comment to record review feedback.`,
+        instructions: `You are an AI collaborator connected to Taskforce, a shared task management system for AI-developer pairs.\n\nIMPORTANT: Before mutating Taskforce data, ensure Taskforce knows which AI profile you are acting as. The preferred path is ambient session binding: if your MCP connection is configured with x-taskforce-ai-name and optionally x-taskforce-ai-profile-token headers, Taskforce can auto-bind that AI identity for get_current_profile and later writes. If no AI identity is currently bound, call resolve_profile with your name. Reuse the returned profileToken across sessions, especially for stateless clients.\n\nStateless client pattern: call resolve_profile, save the returned profileToken only in private agent/client state, and include profileToken on later mutating tool calls only when your MCP client does not preserve session identity between calls. Never write profileToken values to repos, task comments, task attachments, logs, generated docs, or shared output.\n\nTo inspect your current attribution state before writes, call get_current_profile. It reports whether identity is bound, how it was resolved, and the suggested args to use with list_tasks.\n\nWhen setting resolve_profile.surfaceType, classify yourself by the kind of identity you are registering: use agent for a persistent named AI collaborator in Taskforce, cli for terminal-native coding agents, coding_tool for coding surfaces that are not specifically CLI or IDE-native, chat_app for a conversational app identity, and ide for an IDE-native copilot identity. If you are unsure or none of those fit, choose agent.\n\nTo get tasks assigned to yourself, call get_current_profile, then use the returned suggestedArgs with list_tasks. When you begin active work on a tracked task, prefer start_task. It sets the task to in-progress and claims it for your AI profile when the task is currently unassigned. When work on a tracked task is complete, prefer finish_task for the final handoff: use outcome='review' when the next step is human validation or approval, and use outcome='done' only when no explicit human action is requested. Do not leave a task in-progress after reporting completed implementation unless the user explicitly wants more work to continue in the same task.\n\nTaxonomy rule: always call get_config before setting category, type, priority, approach, status, or complexity. Do not rely on remembered enum values.\n\nUse identifier prefixes to choose the correct retrieval path: T-123 goes to task tools such as get_task, IN-123 goes to initiative tools such as get_initiative, WS-123 goes to workstream tools such as get_workstream, I-123 goes to image tools such as get_image, and D-123 goes to document tools such as get_document. Do not send I-123 or D-123 identifiers to get_task.\n\nFor annotated images, use search_images first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_image, then use get_image_annotations to list saved sessions or read a structured annotation payload. If an image reference is being used for UI, placement, or visual correction feedback, treat the saved annotation payload as the source of truth and do not infer intent from the screenshot alone.\n\nFor documents, use search_documents first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_document; pass includeContent=true when you need the document body. For a lower-friction review flow, prefer review_document; otherwise use get_document_reviews or create_document_review_session, then add_document_review_comment to record review feedback.`,
     });
     const TOOL_PERMISSIONS = MCP_TOOL_PERMISSIONS;
     const RESOURCE_PERMISSIONS = {
@@ -532,6 +574,13 @@ export function createTaskforceMcpServer(options = {}) {
             return;
         throw new Error(`Tool ${name} is not available for this MCP session.`);
     }
+    function assertToolProfile(name) {
+        if (!MCP_TOOL_REGISTRY[name])
+            return;
+        if (isMcpToolVisibleInProfile(name, activeToolProfile))
+            return;
+        throw new ToolProfileHiddenError(name, activeToolProfile);
+    }
     function resolveResourcePermissionKey(uri) {
         if (uri === RESOURCE_CONFIG_URI)
             return 'config';
@@ -590,6 +639,45 @@ export function createTaskforceMcpServer(options = {}) {
     const buildDocumentDescriptor = documentHelpers.buildDocumentDescriptor;
     const buildDocumentReadHint = documentHelpers.buildDocumentReadHint;
     const buildCanonicalDocumentAttachmentHint = documentHelpers.buildCanonicalDocumentAttachmentHint;
+    async function buildDocumentContentPayload(asset, options) {
+        const document = buildDocumentDescriptor(asset);
+        const formatRaw = typeof options?.format === 'string' ? options.format.trim().toLowerCase() : '';
+        const format = formatRaw === 'content' || formatRaw === 'full' ? 'text' : formatRaw;
+        if (format === "metadata") {
+            return {
+                document,
+                format: "metadata"
+            };
+        }
+        if (format === "download") {
+            return {
+                document,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
+                reason: "requested_download"
+            };
+        }
+        if (!isTextReadableMimeType(asset.mimeType || '')) {
+            return {
+                document,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
+                reason: "binary_file"
+            };
+        }
+        const resolvedMaxChars = Math.max(1, Math.floor(Number(options?.maxChars || 200000)));
+        const buffer = await canonicalAssetHelpers.readCanonicalDocumentBuffer(asset);
+        const content = buffer.toString('utf8');
+        if (content.length > resolvedMaxChars) {
+            throw new Error('Document exceeds maxChars limit for inline read');
+        }
+        return {
+            document,
+            format: "text",
+            truncated: false,
+            content
+        };
+    }
     function searchImageAssets(queryRaw, options) {
         const query = typeof queryRaw === 'string' ? queryRaw.trim().toLowerCase() : '';
         if (!query) {
@@ -773,12 +861,59 @@ export function createTaskforceMcpServer(options = {}) {
             lastActiveAt: profile.lastActiveAt ?? null,
         };
     }
+    /**
+     * Build the common attribution payload used by both resolve_profile and get_current_profile.
+     * When profile is null, bindingSource is always 'none' (the parameter is ignored in the null path).
+     */
+    function buildAiProfileAttribution(profile, bindingSource) {
+        if (!profile) {
+            return {
+                identityBound: false,
+                bindingSource: 'none',
+                writeReady: false,
+                profileToken: null,
+                profile: null,
+                taskFilter: null,
+                nextTool: 'resolve_profile',
+                suggestedArgs: { name: 'Your AI name' },
+                guidance: "No AI profile is currently bound. Call resolve_profile first, then use the returned profile id as the assignee filter for list_tasks."
+            };
+        }
+        return {
+            identityBound: true,
+            bindingSource,
+            writeReady: true,
+            profileToken: profile.profileToken ?? null,
+            profile: buildAiProfileDescriptor(profile),
+            taskFilter: { assignee: profile.id },
+            nextTool: 'list_tasks',
+            suggestedArgs: { assignee: profile.id, format: 'json' },
+            guidance: "Use suggestedArgs with list_tasks to get tasks assigned to this AI profile."
+        };
+    }
     function resolveRuntimeTaskAssigneeInput(value) {
+        if (isCurrentAiAssigneeInput(value)) {
+            const currentAiAssignee = String(activeAiProfileId || '').trim();
+            if (!currentAiAssignee) {
+                throw new Error('This tool requires an AI profile. Call resolve_profile first, then retry.');
+            }
+            return currentAiAssignee;
+        }
         const resolved = resolveTaskAssigneeInput(value);
         if (resolved === 'agent')
             return 'unassigned';
         return resolved;
     }
+    function resolveListTasksAssigneeInput(value) {
+        if (!isCurrentAiAssigneeInput(value))
+            return value;
+        ensureResolvedProfileForSessionBootstrap();
+        const currentAiAssignee = String(activeAiProfileId || '').trim();
+        if (!currentAiAssignee) {
+            throw new Error('This tool requires an AI profile. Call get_current_profile or resolve_profile first, then retry.');
+        }
+        return currentAiAssignee;
+    }
     function resolvePlanningOwnerInput(value) {
         const resolved = resolveRuntimeTaskAssigneeInput(value);
         if (resolved === undefined)
@@ -1294,7 +1429,7 @@ export function createTaskforceMcpServer(options = {}) {
     function logMcpReadObservation(toolName, startedAtMs, details = {}) {
         const durationMs = Date.now() - startedAtMs;
         const shouldLog = runtimeMode === 'cloud'
-            ? toolName === 'get_current_profile' || toolName === 'list_tasks' || durationMs >= 150
+            ? toolName === 'get_config' || toolName === 'get_current_profile' || toolName === 'list_tasks' || durationMs >= 150
             : durationMs >= 250;
         if (!shouldLog)
             return;
@@ -1304,7 +1439,24 @@ export function createTaskforceMcpServer(options = {}) {
             ...details,
         });
     }
-    const burstyQaReadToolNames = new Set([
+    // Tools eligible for bounded server-side retry on classified transient read failures.
+    const retryableReadToolNames = new Set([
+        // Safe reads called on every agent polling cycle
+        'get_config',
+        'get_current_profile',
+        'list_tasks',
+        // Bursty QA reads that can encounter transient DB contention
+        'get_initiative',
+        'get_workstream',
+        'list_initiatives',
+        'list_workstreams',
+        'get_workstream_attachments',
+        'get_initiative_attachments',
+        'get_document',
+    ]);
+    // Subset of retryable reads that use wrapper-level success logging.
+    // Excluded: get_config, get_current_profile, list_tasks log from their own handlers.
+    const wrapperObservedReadToolNames = new Set([
         'get_initiative',
         'get_workstream',
         'list_initiatives',
@@ -1312,16 +1464,15 @@ export function createTaskforceMcpServer(options = {}) {
         'get_workstream_attachments',
         'get_initiative_attachments',
         'get_document',
-        'read_document_content',
     ]);
-    const burstyQaReadRetryDelaysMs = [125, 350];
+    const retryableReadRetryDelaysMs = [125, 350];
     async function executeMcpToolWithReadRetry(toolName, args, handler) {
         const startedAtMs = Date.now();
         let attempt = 0;
         for (;;) {
             try {
                 const result = await handler(args);
-                if (burstyQaReadToolNames.has(toolName)) {
+                if (wrapperObservedReadToolNames.has(toolName)) {
                     logMcpReadObservation(toolName, startedAtMs, {
                         attempts: attempt + 1,
                         retried: attempt > 0,
@@ -1331,8 +1482,8 @@ export function createTaskforceMcpServer(options = {}) {
             }
             catch (error) {
                 const transient = classifyTransientMcpError(error);
-                if (!burstyQaReadToolNames.has(toolName) || !transient || attempt >= burstyQaReadRetryDelaysMs.length) {
-                    if (burstyQaReadToolNames.has(toolName) && transient) {
+                if (!retryableReadToolNames.has(toolName) || !transient || attempt >= retryableReadRetryDelaysMs.length) {
+                    if (retryableReadToolNames.has(toolName) && transient) {
                         logMcpStructuredEvent('warn', 'tool_read_retry_exhausted', {
                             toolName,
                             attempts: attempt + 1,
@@ -1343,7 +1494,7 @@ export function createTaskforceMcpServer(options = {}) {
                     }
                     throw error;
                 }
-                const delayMs = burstyQaReadRetryDelaysMs[attempt];
+                const delayMs = retryableReadRetryDelaysMs[attempt];
                 attempt += 1;
                 logMcpStructuredEvent('warn', 'tool_read_retry', {
                     toolName,
@@ -1598,17 +1749,24 @@ export function createTaskforceMcpServer(options = {}) {
             return 'unassigned';
         return raw;
     }
+    function isCurrentAiAssigneeInput(value) {
+        if (value === undefined || value === null)
+            return false;
+        const normalized = String(value).trim().toLowerCase();
+        return normalized === 'self';
+    }
     function formatEligibleAssigneeHint(actors) {
         const eligible = actors.filter((actor) => String(actor.id || '').trim() && String(actor.id || '').trim().toLowerCase() !== 'agent');
+        const selfHint = "Use 'self' to assign to the active AI profile, use 'unassigned' to clear ownership";
         if (eligible.length === 0) {
-            return "Use 'unassigned' to clear ownership, or pass a workspace member user ID or AI profile ID.";
+            return `${selfHint}, or pass a workspace member user ID or AI profile ID.`;
         }
         const preview = eligible
             .slice(0, 8)
             .map((actor) => `${actor.id} (${actor.label})`)
             .join(', ');
         const remainder = eligible.length > 8 ? `, plus ${eligible.length - 8} more` : '';
-        return `Use 'unassigned' to clear ownership, or pass an eligible assignee ID from this workspace: ${preview}${remainder}.`;
+        return `${selfHint}, or pass an eligible assignee ID from this workspace: ${preview}${remainder}.`;
     }
     function taskUriFor(id) {
         return `${RESOURCE_URI_PREFIX}/tasks/${encodeURIComponent(id)}`;
@@ -1742,6 +1900,13 @@ export function createTaskforceMcpServer(options = {}) {
                 name: options.serverName || (runtimeMode === 'cloud' ? 'taskforce-cloud' : PROJECT_NAME),
                 version: MCP_SERVER_VERSION,
                 runtimeMode,
+                toolProfile: activeToolProfile,
+            },
+            mcpToolProfile: {
+                active: activeToolProfile,
+                available: ['default', 'extended', 'full'],
+                defaultForRuntime: defaultToolProfile,
+                guidance: 'Cloud sessions default to the default profile. Local/dev sessions default to full. Use TASKFORCE_MCP_TOOL_PROFILE=default|extended|full for local stdio, or pass an explicit toolProfile runtime option where supported.',
             },
             scope: {
                 workspaceId: ACTIVE_WORKSPACE_ID,
@@ -2193,13 +2358,10 @@ export function createTaskforceMcpServer(options = {}) {
         const assigneeHint = describeEligibleAssignees();
         const mutatingProfileTokenProperty = {
             type: "string",
-            description: "Optional AI profile token returned by resolve_profile. Pass this when your MCP client does not preserve session identity between calls. In stateless/cloud MCP clients without ambient AI binding, this is usually required on mutating calls after bootstrap."
+            description: "Optional profileToken from resolve_profile for stateless MCP clients."
         };
         const prefix = `[Project: ${PROJECT_NAME}] `;
-        const agentNote = runtimeMode === 'local'
-            ? " NOTE: Use this tool instead of editing files directly to ensure data integrity."
-            : "";
-        const describeTool = (text) => prefix + text + agentNote;
+        const describeTool = (text) => prefix + text;
         const titleForTool = (name) => String(name || '')
             .split('_')
             .filter(Boolean)
@@ -2261,7 +2423,8 @@ export function createTaskforceMcpServer(options = {}) {
                     }
                 }
             };
-        }).filter((tool) => hasPermission(TOOL_PERMISSIONS[tool.name]));
+        }).filter((tool) => (isMcpToolVisibleInProfile(tool.name, activeToolProfile)
+            && hasPermission(TOOL_PERMISSIONS[tool.name])));
         return {
             tools,
         };
@@ -2314,58 +2477,82 @@ export function createTaskforceMcpServer(options = {}) {
             ...(entity?.initiativeId ? { includeInitiatives: true, initiativeIds: [entity.initiativeId] } : {}),
         });
     };
-    const buildPlanningAttachmentListPayload = (targetType, target) => ({
-        [`${targetType}Id`]: target.id,
-        referenceLabel: target.referenceLabel,
-        attachments: listPlanningAttachmentDescriptors(target),
-    });
-    const readPlanningAttachment = async (targetType, args) => {
-        const inputId = targetType === 'initiative' ? args.initiativeId : args.workstreamId;
+    const buildTaskAttachmentContentPayload = async (task, args) => {
+        const { attachmentId, format = "text", maxChars = 200000 } = args;
+        const attachments = taskAttachmentHelpers.listTaskAttachmentDescriptors(task);
+        const attachment = attachments.find((entry) => entry.attachmentId === attachmentId);
+        if (!attachment) {
+            throw new Error(`Attachment ${attachmentId} not found on task ${task.referenceLabel || task.id}`);
+        }
+        if (format === "metadata") {
+            return {
+                taskId: task.id,
+                attachment,
+                format: "metadata"
+            };
+        }
+        if (format === "download") {
+            return {
+                taskId: task.id,
+                attachment,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
+                reason: attachment.source === 'external' ? 'external_reference' : 'requested_download'
+            };
+        }
+        if (!attachment.readableAsText) {
+            return {
+                taskId: task.id,
+                attachment,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
+                reason: attachment.source === 'external' ? 'external_reference' : 'binary_file'
+            };
+        }
+        const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
+        const buffer = await canonicalAssetHelpers.readCanonicalAttachmentBuffer(task.id, attachment);
+        const content = buffer.toString('utf8');
+        if (content.length > resolvedMaxChars) {
+            throw new Error('Attachment exceeds maxChars limit for inline read');
+        }
+        return {
+            taskId: task.id,
+            attachment,
+            format: "text",
+            truncated: false,
+            content
+        };
+    };
+    const buildPlanningAttachmentContentPayload = async (targetType, target, args) => {
         const { attachmentId, format = "text", maxChars = 200000 } = args;
-        const target = resolvePlanningAttachmentTarget(targetType, inputId);
         const attachments = listPlanningAttachmentDescriptors(target);
         const attachment = attachments.find((entry) => entry.attachmentId === attachmentId);
         if (!attachment) {
-            throw new Error(`Attachment ${attachmentId} not found on ${targetType} ${String(inputId || '').trim() || target.id}`);
+            throw new Error(`Attachment ${attachmentId} not found on ${targetType} ${formatPlanningAttachmentTarget(target)}`);
         }
         if (format === "metadata") {
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            [`${targetType}Id`]: target.id,
-                            attachment,
-                            format: "metadata"
-                        }, null, 2)
-                    }],
+                [`${targetType}Id`]: target.id,
+                attachment,
+                format: "metadata"
             };
         }
         if (format === "download") {
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            [`${targetType}Id`]: target.id,
-                            attachment,
-                            format: "download",
-                            downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
-                            reason: attachment.source === 'external' ? 'external_reference' : 'requested_download'
-                        }, null, 2)
-                    }],
+                [`${targetType}Id`]: target.id,
+                attachment,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
+                reason: attachment.source === 'external' ? 'external_reference' : 'requested_download'
             };
         }
         if (!attachment.readableAsText) {
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify({
-                            [`${targetType}Id`]: target.id,
-                            attachment,
-                            format: "download",
-                            downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
-                            reason: attachment.source === 'external' ? 'external_reference' : 'binary_file'
-                        }, null, 2)
-                    }],
+                [`${targetType}Id`]: target.id,
+                attachment,
+                format: "download",
+                downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
+                reason: attachment.source === 'external' ? 'external_reference' : 'binary_file'
             };
         }
         const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
@@ -2375,16 +2562,24 @@ export function createTaskforceMcpServer(options = {}) {
             throw new Error('Attachment exceeds maxChars limit for inline read');
         }
         return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        [`${targetType}Id`]: target.id,
-                        attachment,
-                        format: "text",
-                        truncated: false,
-                        content
-                    }, null, 2)
-                }],
+            [`${targetType}Id`]: target.id,
+            attachment,
+            format: "text",
+            truncated: false,
+            content
+        };
+    };
+    const buildPlanningAttachmentListPayload = async (targetType, target, args = {}) => {
+        const attachmentId = typeof args.attachmentId === 'string' && args.attachmentId.trim().length > 0
+            ? args.attachmentId
+            : null;
+        return {
+            [`${targetType}Id`]: target.id,
+            referenceLabel: target.referenceLabel,
+            attachments: listPlanningAttachmentDescriptors(target),
+            ...(attachmentId
+                ? { attachmentContent: await buildPlanningAttachmentContentPayload(targetType, target, { ...args, attachmentId }) }
+                : {}),
         };
     };
     const savePlanningAttachment = async (targetType, args) => {
@@ -2582,11 +2777,12 @@ export function createTaskforceMcpServer(options = {}) {
             case "list_tasks": {
                 const startedAtMs = Date.now();
                 const { format = "markdown", category, status, openOnly = false, assignee, priority, type, sort = "created", order = "desc", limit } = args;
+                const resolvedAssignee = resolveListTasksAssigneeInput(assignee);
                 const slimTasks = core.listTasksSlim(ACTIVE_WORKSPACE_ID, {
                     category,
                     status,
                     openOnly: Boolean(openOnly),
-                    assignee,
+                    assignee: resolvedAssignee,
                     priority: priority !== undefined ? Number(priority) : undefined,
                     type,
                     sort,
@@ -2597,7 +2793,7 @@ export function createTaskforceMcpServer(options = {}) {
                     format,
                     returnedTasks: slimTasks.length,
                     openOnly,
-                    hasAssigneeFilter: Boolean(assignee),
+                    hasAssigneeFilter: Boolean(resolvedAssignee),
                     hasStatusFilter: Boolean(status),
                     hasCategoryFilter: Boolean(category),
                     hasTypeFilter: Boolean(type),
@@ -2645,28 +2841,13 @@ export function createTaskforceMcpServer(options = {}) {
                     profileId: resolved.profile.id,
                     created: resolved.created
                 });
+                const attribution = buildAiProfileAttribution(resolved.profile, 'session');
                 return {
                     content: [{
                             type: "text",
                             text: JSON.stringify({
                                 created: resolved.created,
-                                profileToken: resolved.profile.profileToken,
-                                profile: {
-                                    id: resolved.profile.id,
-                                    workspaceId: resolved.profile.workspaceId,
-                                    profileToken: resolved.profile.profileToken,
-                                    name: resolved.profile.name,
-                                    username: resolved.profile.username,
-                                    icon: resolved.profile.icon,
-                                    color: resolved.profile.color,
-                                    description: resolved.profile.description ?? null,
-                                    role: resolved.profile.role ?? null,
-                                    provider: resolved.profile.provider ?? null,
-                                    model: resolved.profile.model ?? null,
-                                    surfaceType: resolved.profile.surfaceType ?? null,
-                                    seatScope: resolved.profile.seatScope ?? null,
-                                    lastActiveAt: resolved.profile.lastActiveAt
-                                },
+                                ...attribution,
                                 ...(resolved.duplicateWarning && { duplicateWarning: resolved.duplicateWarning })
                             }, null, 2)
                         }],
@@ -2702,10 +2883,11 @@ export function createTaskforceMcpServer(options = {}) {
                     }
                     bindingSource = 'token_lookup';
                 }
+                const attribution = buildAiProfileAttribution(profile, bindingSource);
                 logMcpReadObservation('get_current_profile', startedAtMs, {
-                    identityBound: Boolean(activeAiProfileId),
-                    bindingSource,
-                    writeReady: Boolean(profile),
+                    identityBound: attribution.identityBound,
+                    bindingSource: attribution.bindingSource,
+                    writeReady: attribution.writeReady,
                     profileResolved: Boolean(profile),
                     usedProfileTokenLookup: !activeAiProfileId && typeof profileToken === 'string' && profileToken.trim().length > 0,
                 });
@@ -2714,19 +2896,7 @@ export function createTaskforceMcpServer(options = {}) {
                             type: "text",
                             text: JSON.stringify({
                                 workspaceId: ACTIVE_WORKSPACE_ID,
-                                identityBound: Boolean(activeAiProfileId),
-                                bindingSource,
-                                writeReady: Boolean(profile),
-                                profileToken: profile?.profileToken ?? null,
-                                profile: profile ? buildAiProfileDescriptor(profile) : null,
-                                taskFilter: profile ? { assignee: profile.id } : null,
-                                nextTool: profile ? 'list_tasks' : 'resolve_profile',
-                                suggestedArgs: profile
-                                    ? { assignee: profile.id, format: 'json' }
-                                    : { name: 'Your AI name' },
-                                guidance: profile
-                                    ? "Use suggestedArgs with list_tasks to get tasks assigned to this AI profile."
-                                    : "No AI profile is currently bound. Call resolve_profile first, then use the returned profile id as the assignee filter for list_tasks.",
+                                ...attribution,
                             }, null, 2)
                         }],
                 };
@@ -2933,92 +3103,78 @@ export function createTaskforceMcpServer(options = {}) {
                     content: [{ type: "text", text: JSON.stringify(buildPostWriteWorkstreamResourcePayload(unarchived, 'unarchive_workstream:response'), null, 2) }],
                 };
             }
-            case "set_task_workstream": {
-                const { taskId, workstreamId } = args;
-                const { id: resolvedTaskId } = resolveTaskByIdentifierOrThrow(taskId);
-                const { id: resolvedWorkstreamId } = resolveWorkstreamByIdentifierOrThrow(workstreamId);
-                const updated = core.updateTask(resolvedTaskId, {
-                    workstreamId: resolvedWorkstreamId,
-                }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
-                if (!updated) {
-                    throw new Error(buildTaskLookupFailureMessage(String(taskId || '').trim()));
+            case "update_task_workstream": {
+                const { id: legacyInputId, taskId, workstreamId } = args;
+                const inputId = taskId ?? legacyInputId;
+                const { id: resolvedTaskId, task } = resolveTaskByIdentifierOrThrow(inputId);
+                if (workstreamId === undefined) {
+                    throw new Error('workstreamId is required; pass null or an empty string to unlink the task.');
                 }
-                recordMcpWriteAudit('set_task_workstream', { taskId: updated.id, workstreamId: resolvedWorkstreamId });
-                await notifyResourceMutation({
-                    includeTasks: true,
-                    taskIds: [updated.id],
-                    includeWorkstreams: true,
-                    workstreamIds: [resolvedWorkstreamId],
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                task: buildTaskWriteSummary(updated),
-                                workstreamId: resolvedWorkstreamId,
-                            }, null, 2)
-                        }],
-                };
-            }
-            case "clear_task_workstream": {
-                const { taskId } = args;
-                const { id: resolvedTaskId, task } = resolveTaskByIdentifierOrThrow(taskId);
-                const priorWorkstreamId = task.workstreamId || null;
+                const normalizedWorkstreamId = typeof workstreamId === 'string' ? workstreamId.trim() : workstreamId;
+                const nextWorkstreamId = normalizedWorkstreamId === null || normalizedWorkstreamId === ''
+                    ? null
+                    : resolveWorkstreamByIdentifierOrThrow(normalizedWorkstreamId).id;
+                const previousWorkstreamId = task.workstreamId || null;
                 const updated = core.updateTask(resolvedTaskId, {
-                    workstreamId: null,
+                    workstreamId: nextWorkstreamId,
                 }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
                 if (!updated) {
-                    throw new Error(buildTaskLookupFailureMessage(String(taskId || '').trim()));
+                    throw new Error(buildTaskLookupFailureMessage(String(inputId || '').trim()));
                 }
-                recordMcpWriteAudit('clear_task_workstream', { taskId: updated.id, previousWorkstreamId: priorWorkstreamId });
+                const relatedWorkstreamIds = new Set();
+                if (previousWorkstreamId)
+                    relatedWorkstreamIds.add(previousWorkstreamId);
+                if (nextWorkstreamId)
+                    relatedWorkstreamIds.add(nextWorkstreamId);
+                recordMcpWriteAudit('update_task_workstream', {
+                    taskId: updated.id,
+                    workstreamId: nextWorkstreamId,
+                    previousWorkstreamId,
+                });
                 await notifyResourceMutation({
                     includeTasks: true,
                     taskIds: [updated.id],
-                    ...(priorWorkstreamId ? { includeWorkstreams: true, workstreamIds: [priorWorkstreamId] } : {}),
+                    ...(relatedWorkstreamIds.size > 0 ? { includeWorkstreams: true, workstreamIds: Array.from(relatedWorkstreamIds) } : {}),
                 });
                 return {
                     content: [{
                             type: "text",
                             text: JSON.stringify({
                                 task: buildTaskWriteSummary(updated),
-                                workstreamId: null,
-                                previousWorkstreamId: priorWorkstreamId,
+                                workstreamId: nextWorkstreamId,
+                                previousWorkstreamId,
                             }, null, 2)
                         }],
                 };
             }
-            case "set_workstream_initiative": {
-                const { workstreamId, initiativeId } = args;
-                const { id: resolvedWorkstreamId, workstream: existingWorkstream } = resolveWorkstreamByIdentifierOrThrow(workstreamId);
-                const { id: resolvedInitiativeId } = resolveInitiativeByIdentifierOrThrow(initiativeId);
+            case "update_workstream_initiative": {
+                const { id: legacyInputId, workstreamId, initiativeId } = args;
+                const inputId = workstreamId ?? legacyInputId;
+                const { id: resolvedWorkstreamId, workstream: existingWorkstream } = resolveWorkstreamByIdentifierOrThrow(inputId);
+                if (initiativeId === undefined) {
+                    throw new Error('initiativeId is required; pass null or an empty string to unlink the workstream.');
+                }
+                const normalizedInitiativeId = typeof initiativeId === 'string' ? initiativeId.trim() : initiativeId;
+                const nextInitiativeId = normalizedInitiativeId === null || normalizedInitiativeId === ''
+                    ? null
+                    : resolveInitiativeByIdentifierOrThrow(normalizedInitiativeId).id;
                 const updated = core.updateWorkstream(resolvedWorkstreamId, {
-                    initiativeId: resolvedInitiativeId,
+                    initiativeId: nextInitiativeId,
                 }, ACTIVE_WORKSPACE_ID);
-                const relatedInitiativeIds = new Set([resolvedInitiativeId]);
+                const relatedInitiativeIds = new Set();
                 if (existingWorkstream.initiativeId)
                     relatedInitiativeIds.add(existingWorkstream.initiativeId);
-                recordMcpWriteAudit('set_workstream_initiative', { workstreamId: updated.id, initiativeId: resolvedInitiativeId });
-                await notifyResourceMutation({
-                    includeWorkstreams: true,
-                    workstreamIds: [updated.id],
-                    includeInitiatives: true,
-                    initiativeIds: Array.from(relatedInitiativeIds),
+                if (nextInitiativeId)
+                    relatedInitiativeIds.add(nextInitiativeId);
+                recordMcpWriteAudit('update_workstream_initiative', {
+                    workstreamId: updated.id,
+                    initiativeId: nextInitiativeId,
+                    previousInitiativeId: existingWorkstream.initiativeId || null,
                 });
-                return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(updated), null, 2) }],
-                };
-            }
-            case "clear_workstream_initiative": {
-                const { workstreamId } = args;
-                const { id: resolvedWorkstreamId, workstream: existingWorkstream } = resolveWorkstreamByIdentifierOrThrow(workstreamId);
-                const updated = core.updateWorkstream(resolvedWorkstreamId, {
-                    initiativeId: null,
-                }, ACTIVE_WORKSPACE_ID);
-                recordMcpWriteAudit('clear_workstream_initiative', { workstreamId: updated.id, previousInitiativeId: existingWorkstream.initiativeId || null });
                 await notifyResourceMutation({
                     includeWorkstreams: true,
                     workstreamIds: [updated.id],
-                    ...(existingWorkstream.initiativeId ? { includeInitiatives: true, initiativeIds: [existingWorkstream.initiativeId] } : {}),
+                    ...(relatedInitiativeIds.size > 0 ? { includeInitiatives: true, initiativeIds: Array.from(relatedInitiativeIds) } : {}),
                 });
                 return {
                     content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(updated), null, 2) }],
@@ -3079,7 +3235,7 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "get_task_attachments": {
-                const { id, taskId } = args;
+                const { id, taskId, attachmentId } = args;
                 const taskIdentifier = taskId ?? id;
                 const task = core.resolveTaskIdentifier(taskIdentifier, ACTIVE_WORKSPACE_ID);
                 if (!task) {
@@ -3091,77 +3247,10 @@ export function createTaskforceMcpServer(options = {}) {
                             text: JSON.stringify({
                                 taskId: task.id,
                                 referenceLabel: task.referenceLabel || getTaskReferenceLabel(task),
-                                attachments: taskAttachmentHelpers.listTaskAttachmentDescriptors(task)
-                            }, null, 2)
-                        }],
-                };
-            }
-            case "read_task_attachment": {
-                const { taskId, attachmentId, format = "text", maxChars = 200000 } = args;
-                const task = core.resolveTaskIdentifier(taskId, ACTIVE_WORKSPACE_ID);
-                if (!task) {
-                    throw new Error(`Task ${taskId} not found`);
-                }
-                const attachments = taskAttachmentHelpers.listTaskAttachmentDescriptors(task);
-                const attachment = attachments.find((entry) => entry.attachmentId === attachmentId);
-                if (!attachment) {
-                    throw new Error(`Attachment ${attachmentId} not found on task ${taskId}`);
-                }
-                if (format === "metadata") {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: JSON.stringify({
-                                    taskId: task.id,
-                                    attachment,
-                                    format: "metadata"
-                                }, null, 2)
-                            }],
-                    };
-                }
-                if (format === "download") {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: JSON.stringify({
-                                    taskId: task.id,
-                                    attachment,
-                                    format: "download",
-                                    downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
-                                    reason: attachment.source === 'external' ? 'external_reference' : 'requested_download'
-                                }, null, 2)
-                            }],
-                    };
-                }
-                if (!attachment.readableAsText) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: JSON.stringify({
-                                    taskId: task.id,
-                                    attachment,
-                                    format: "download",
-                                    downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
-                                    reason: attachment.source === 'external' ? 'external_reference' : 'binary_file'
-                                }, null, 2)
-                            }],
-                    };
-                }
-                const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
-                const buffer = await canonicalAssetHelpers.readCanonicalAttachmentBuffer(task.id, attachment);
-                const content = buffer.toString('utf8');
-                if (content.length > resolvedMaxChars) {
-                    throw new Error('Attachment exceeds maxChars limit for inline read');
-                }
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                taskId: task.id,
-                                attachment,
-                                format: "text",
-                                truncated: false,
-                                content
+                                attachments: taskAttachmentHelpers.listTaskAttachmentDescriptors(task),
+                                ...(typeof attachmentId === 'string' && attachmentId.trim().length > 0
+                                    ? { attachmentContent: await buildTaskAttachmentContentPayload(task, args) }
+                                    : {}),
                             }, null, 2)
                         }],
                 };
@@ -3172,26 +3261,20 @@ export function createTaskforceMcpServer(options = {}) {
                 return {
                     content: [{
                             type: "text",
-                            text: JSON.stringify(buildPlanningAttachmentListPayload('workstream', target), null, 2)
+                            text: JSON.stringify(await buildPlanningAttachmentListPayload('workstream', target, args), null, 2)
                         }],
                 };
             }
-            case "read_workstream_attachment": {
-                return readPlanningAttachment('workstream', args);
-            }
             case "get_initiative_attachments": {
                 const { id } = args;
                 const target = resolvePlanningAttachmentTarget('initiative', id);
                 return {
                     content: [{
                             type: "text",
-                            text: JSON.stringify(buildPlanningAttachmentListPayload('initiative', target), null, 2)
+                            text: JSON.stringify(await buildPlanningAttachmentListPayload('initiative', target, args), null, 2)
                         }],
                 };
             }
-            case "read_initiative_attachment": {
-                return readPlanningAttachment('initiative', args);
-            }
             case "search_images": {
                 assertAnnotatedAttachmentReadAccess();
                 const { query, limit } = args;
@@ -3298,14 +3381,14 @@ export function createTaskforceMcpServer(options = {}) {
                                 query: typeof query === 'string' ? query.trim() : '',
                                 results,
                                 guidance: results.length > 0
-                                    ? 'After picking a match, call get_document with the suggestedArgs.documentId, then read_document_content to inspect the body.'
+                                    ? '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.',
                             }, null, 2)
                         }],
                 };
             }
             case "get_document": {
-                const { id, documentId } = args;
+                const { id, documentId, includeContent, format, maxChars } = args;
                 const asset = resolveDocumentAssetByIdentifierOrThrow(documentId ?? id);
                 const linkedTasks = (workspaceAssetStore?.listLinksForAsset(asset.assetId, ACTIVE_WORKSPACE_ID) || [])
                     .filter((entry) => !entry.deletedAt)
@@ -3331,6 +3414,11 @@ export function createTaskforceMcpServer(options = {}) {
                     updatedAt: session.updatedAt,
                     commentCount: Array.isArray(session.comments) ? session.comments.length : 0,
                 }));
+                const normalizedFormat = typeof format === 'string' ? format.trim().toLowerCase() : '';
+                const shouldIncludeContent = includeContent === true || ['content', 'full', 'text', 'download'].includes(normalizedFormat);
+                const documentContent = shouldIncludeContent
+                    ? await buildDocumentContentPayload(asset, { format, maxChars })
+                    : null;
                 return {
                     content: [{
                             type: "text",
@@ -3339,83 +3427,46 @@ export function createTaskforceMcpServer(options = {}) {
                                 readContent: buildDocumentReadHint(asset),
                                 linkedTasks,
                                 reviewSessions,
+                                ...(documentContent ? { documentContent } : {}),
                             }, null, 2)
                         }],
                 };
             }
-            case "read_document_content": {
-                const { documentId, format = "text", maxChars = 200000 } = args;
-                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId);
-                const document = buildDocumentDescriptor(asset);
-                if (format === "metadata") {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: JSON.stringify({
-                                    document,
-                                    format: "metadata"
-                                }, null, 2)
-                            }],
-                    };
+            case "get_image_annotations": {
+                assertAnnotatedAttachmentReadAccess();
+                const { taskId, imageId, imageAssetId, sessionId } = args;
+                const normalizedSessionId = typeof sessionId === 'string' ? sessionId.trim() : '';
+                const normalizedImageIdentifier = typeof imageId === 'string' && imageId.trim()
+                    ? imageId.trim()
+                    : (typeof imageAssetId === 'string' ? imageAssetId.trim() || null : null);
+                if (!taskId && !normalizedImageIdentifier && !normalizedSessionId) {
+                    throw new Error('taskId, imageId, or sessionId is required');
                 }
-                if (format === "download") {
+                const payload = normalizedSessionId
+                    ? core.buildAnnotatedAttachmentPayload({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                    })
+                    : null;
+                if (!taskId && !normalizedImageIdentifier) {
                     return {
                         content: [{
                                 type: "text",
-                                text: JSON.stringify({
-                                    document,
-                                    format: "download",
-                                    downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
-                                    reason: "requested_download"
-                                }, null, 2)
+                                text: JSON.stringify({ payload }, null, 2)
                             }],
                     };
                 }
-                if (!isTextReadableMimeType(asset.mimeType || '')) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: JSON.stringify({
-                                    document,
-                                    format: "download",
-                                    downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
-                                    reason: "binary_file"
-                                }, null, 2)
-                            }],
-                    };
-                }
-                const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
-                const buffer = await canonicalAssetHelpers.readCanonicalDocumentBuffer(asset);
-                const content = buffer.toString('utf8');
-                if (content.length > resolvedMaxChars) {
-                    throw new Error('Document exceeds maxChars limit for inline read');
-                }
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                document,
-                                format: "text",
-                                truncated: false,
-                                content
-                            }, null, 2)
-                        }],
-                };
-            }
-            case "get_annotated_attachment_sessions": {
-                assertAnnotatedAttachmentReadAccess();
-                const { taskId, imageId, imageAssetId } = args;
-                const normalizedImageIdentifier = typeof imageId === 'string' && imageId.trim()
-                    ? imageId.trim()
-                    : (typeof imageAssetId === 'string' ? imageAssetId.trim() || null : null);
-                if (!taskId && !normalizedImageIdentifier) {
-                    throw new Error('taskId or imageId is required');
-                }
                 const image = normalizedImageIdentifier
                     ? resolveImageAssetByIdentifierOrThrow(normalizedImageIdentifier)
                     : null;
                 if (taskId) {
                     const { task } = resolveTaskByIdentifierOrThrow(taskId);
+                    if (payload && payload.taskId !== task.id) {
+                        throw new Error(`Annotated attachment session ${normalizedSessionId} is not linked to task ${task.referenceLabel || task.id}.`);
+                    }
+                    if (payload && image && payload.image.assetId !== image.assetId) {
+                        throw new Error(`Annotated attachment session ${normalizedSessionId} is not linked to image ${image.assetId}.`);
+                    }
                     const sessions = core.listAnnotatedAttachmentSessions({
                         workspaceId: ACTIVE_WORKSPACE_ID,
                         taskId: task.id,
@@ -3428,11 +3479,15 @@ export function createTaskforceMcpServer(options = {}) {
                                     taskId: task.id,
                                     referenceLabel: task.referenceLabel || getTaskReferenceLabel(task),
                                     image: image ? buildImageDescriptor(image) : null,
-                                    sessions
+                                    sessions,
+                                    ...(payload ? { payload } : {}),
                                 }, null, 2)
                             }],
                     };
                 }
+                if (payload && image && payload.image.assetId !== image.assetId) {
+                    throw new Error(`Annotated attachment session ${normalizedSessionId} is not linked to image ${image.assetId}.`);
+                }
                 const sessionsForImage = core.listAnnotatedAttachmentSessions({
                     workspaceId: ACTIVE_WORKSPACE_ID,
                     imageAssetId: image.assetId,
@@ -3462,27 +3517,11 @@ export function createTaskforceMcpServer(options = {}) {
                                 image: buildImageDescriptor(image),
                                 tasks: sessionsByTask,
                                 unattachedSessions,
+                                ...(payload ? { payload } : {}),
                             }, null, 2)
                         }],
                 };
             }
-            case "read_annotated_attachment_payload": {
-                assertAnnotatedAttachmentReadAccess();
-                const { sessionId } = args;
-                if (!sessionId || typeof sessionId !== 'string') {
-                    throw new Error('sessionId is required');
-                }
-                const payload = core.buildAnnotatedAttachmentPayload({
-                    workspaceId: ACTIVE_WORKSPACE_ID,
-                    sessionId: sessionId.trim(),
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify(payload, null, 2)
-                        }],
-                };
-            }
             case "create_annotated_attachment_session": {
                 assertAnnotatedAttachmentReadAccess();
                 const { imageId, taskId, title, sessionInstruction } = args;
@@ -3738,9 +3777,37 @@ export function createTaskforceMcpServer(options = {}) {
                         }],
                 };
             }
-            case "get_document_review_sessions": {
-                const { documentId } = args;
-                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId);
+            case "get_document_reviews": {
+                const { documentId, id: legacyInputId, sessionId } = args;
+                const normalizedSessionId = typeof sessionId === 'string' ? sessionId.trim() : '';
+                if (normalizedSessionId) {
+                    const inputId = documentId ?? legacyInputId;
+                    const requestedAsset = typeof inputId === 'string' && inputId.trim()
+                        ? resolveDocumentAssetByIdentifierOrThrow(inputId)
+                        : null;
+                    const session = core.getDocumentReviewSession({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        sessionId: normalizedSessionId,
+                    });
+                    if (!session) {
+                        throw new Error(`Document review session ${sessionId} not found.`);
+                    }
+                    if (requestedAsset && session.assetId !== requestedAsset.assetId) {
+                        throw new Error(`Document review session ${normalizedSessionId} is not linked to document ${requestedAsset.assetId}.`);
+                    }
+                    const asset = workspaceAssetStore?.get(session.assetId, ACTIVE_WORKSPACE_ID) || null;
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    document: asset ? buildDocumentDescriptor(asset) : null,
+                                    session
+                                }, null, 2)
+                            }],
+                    };
+                }
+                const inputId = documentId ?? legacyInputId;
+                const asset = resolveDocumentAssetByIdentifierOrThrow(inputId);
                 const sessions = core.listDocumentReviewSessions({
                     workspaceId: ACTIVE_WORKSPACE_ID,
                     assetId: asset.assetId,
@@ -3755,29 +3822,6 @@ export function createTaskforceMcpServer(options = {}) {
                         }],
                 };
             }
-            case "get_document_review_session": {
-                const { sessionId } = args;
-                if (!sessionId || typeof sessionId !== 'string') {
-                    throw new Error('sessionId is required');
-                }
-                const session = core.getDocumentReviewSession({
-                    workspaceId: ACTIVE_WORKSPACE_ID,
-                    sessionId: sessionId.trim(),
-                });
-                if (!session) {
-                    throw new Error(`Document review session ${sessionId} not found.`);
-                }
-                const asset = workspaceAssetStore?.get(session.assetId, ACTIVE_WORKSPACE_ID) || null;
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                document: asset ? buildDocumentDescriptor(asset) : null,
-                                session
-                            }, null, 2)
-                        }],
-                };
-            }
             case "create_document_review_session": {
                 const { documentId, title, status } = args;
                 const asset = resolveDocumentAssetByIdentifierOrThrow(documentId);
@@ -4019,51 +4063,60 @@ export function createTaskforceMcpServer(options = {}) {
                     content: [{ type: "text", text: JSON.stringify(board, null, 2) }],
                 };
             }
-            case "schedule_task": {
-                const { id: legacyInputId, taskId, scheduledDate: legacyScheduledDate, date, orderInDay: legacyOrderInDay, order } = args;
+            case "update_schedule": {
+                const { id: legacyInputId, taskId, scheduledDate: legacyScheduledDate, date, orderInDay: legacyOrderInDay, order, moves, taskIds, } = args;
+                const inputMoves = Array.isArray(moves)
+                    ? moves
+                    : Array.isArray(taskIds) && typeof date === 'string'
+                        ? taskIds.map((moveTaskId, index) => ({ id: moveTaskId, scheduledDate: date, orderInDay: index }))
+                        : null;
+                if (Array.isArray(inputMoves)) {
+                    const resolvedMoves = inputMoves.map((move, index) => ({
+                        ...move,
+                        id: resolveTaskByIdentifierOrThrow(move?.taskId ?? move?.id).id,
+                        scheduledDate: move?.date ?? move?.scheduledDate,
+                        orderInDay: move?.order ?? move?.orderInDay ?? index,
+                    }));
+                    const result = core.reorderScheduledTasks(resolvedMoves, ACTIVE_WORKSPACE_ID);
+                    recordMcpWriteAudit('update_schedule', {
+                        operation: 'reorder',
+                        taskIds: resolvedMoves.map((m) => m.id),
+                        moveCount: resolvedMoves.length
+                    });
+                    await notifyResourceMutation({
+                        taskIds: resolvedMoves.map((m) => m.id),
+                        includeTasks: true,
+                        includeStats: true,
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
                 const inputId = taskId ?? legacyInputId;
-                const scheduledDate = date ?? legacyScheduledDate;
+                const scheduleInput = date !== undefined ? date : legacyScheduledDate;
                 const orderInDay = order ?? legacyOrderInDay;
                 const { id } = resolveTaskByIdentifierOrThrow(inputId);
-                if (!scheduledDate || typeof scheduledDate !== 'string')
-                    throw new Error('scheduledDate is required');
-                const result = core.updateTaskSchedule(id, { scheduledDate, orderInDay }, ACTIVE_WORKSPACE_ID);
-                if (!result) {
-                    throw new Error(`Task ${id} not found`);
+                if (scheduleInput === undefined) {
+                    throw new Error('date is required; pass null or an empty string to unschedule the task.');
                 }
-                recordMcpWriteAudit('schedule_task', { taskId: id, scheduledDate, orderInDay: orderInDay ?? null });
-                await notifyResourceMutation({
-                    taskIds: [id],
-                    includeTasks: true,
-                    includeStats: true,
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                scheduling: {
-                                    taskId: id,
-                                    requestedDate: scheduledDate,
-                                    persistedDate: result.task.scheduledDate,
-                                    persistedWeekKey: result.task.scheduledWeekKey,
-                                    persistedOrderInDay: result.task.orderInDay ?? null
-                                },
-                                warnings: result.warnings,
-                                task: buildTaskWriteSummary(result.task)
-                            }, null, 2)
-                        }],
-                };
-            }
-            case "unschedule_task": {
-                const { id: legacyInputId, taskId } = args;
-                const inputId = taskId ?? legacyInputId;
-                const { id } = resolveTaskByIdentifierOrThrow(inputId);
-                const result = core.updateTaskSchedule(id, { scheduledDate: null, orderInDay: null }, ACTIVE_WORKSPACE_ID);
+                const requestedDate = typeof scheduleInput === 'string' ? scheduleInput.trim() : scheduleInput;
+                const isUnschedule = requestedDate === null || requestedDate === '';
+                if (!isUnschedule && typeof requestedDate !== 'string') {
+                    throw new Error('date must be a string, null, or an empty string.');
+                }
+                const result = core.updateTaskSchedule(id, isUnschedule
+                    ? { scheduledDate: null, orderInDay: null }
+                    : { scheduledDate: requestedDate, orderInDay }, ACTIVE_WORKSPACE_ID);
                 if (!result) {
                     throw new Error(`Task ${id} not found`);
                 }
-                recordMcpWriteAudit('unschedule_task', { taskId: id });
+                const operation = isUnschedule ? 'unschedule' : 'schedule';
+                recordMcpWriteAudit('update_schedule', {
+                    operation,
+                    taskId: id,
+                    scheduledDate: isUnschedule ? null : requestedDate,
+                    orderInDay: isUnschedule ? null : orderInDay ?? null
+                });
                 await notifyResourceMutation({
                     taskIds: [id],
                     includeTasks: true,
@@ -4074,47 +4127,20 @@ export function createTaskforceMcpServer(options = {}) {
                             type: "text",
                             text: JSON.stringify({
                                 success: true,
+                                operation,
                                 scheduling: {
                                     taskId: id,
-                                    requestedDate: null,
+                                    requestedDate: isUnschedule ? null : requestedDate,
                                     persistedDate: result.task.scheduledDate,
                                     persistedWeekKey: result.task.scheduledWeekKey,
                                     persistedOrderInDay: result.task.orderInDay ?? null
                                 },
                                 warnings: result.warnings,
-                                task: result.task
+                                task: buildTaskWriteSummary(result.task)
                             }, null, 2)
                         }],
                 };
             }
-            case "reorder_scheduled_tasks": {
-                const { moves, date, taskIds } = args;
-                const inputMoves = Array.isArray(moves)
-                    ? moves
-                    : Array.isArray(taskIds) && typeof date === 'string'
-                        ? taskIds.map((taskId, index) => ({ id: taskId, scheduledDate: date, orderInDay: index }))
-                        : null;
-                if (!Array.isArray(inputMoves)) {
-                    throw new Error('moves must be an array');
-                }
-                const resolvedMoves = inputMoves.map((move) => ({
-                    ...move,
-                    id: resolveTaskByIdentifierOrThrow(move?.taskId ?? move?.id).id
-                }));
-                const result = core.reorderScheduledTasks(resolvedMoves, ACTIVE_WORKSPACE_ID);
-                recordMcpWriteAudit('reorder_scheduled_tasks', {
-                    taskIds: resolvedMoves.map((m) => m.id),
-                    moveCount: resolvedMoves.length
-                });
-                await notifyResourceMutation({
-                    taskIds: resolvedMoves.map((m) => m.id),
-                    includeTasks: true,
-                    includeStats: true,
-                });
-                return {
-                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-                };
-            }
             case "bulk_carryover": {
                 const { fromWeek, toWeek, mode, includeStatuses = ['task', 'in-progress', 'review', 'on-hold'] } = args;
                 if (!fromWeek || typeof fromWeek !== 'string')
@@ -4425,96 +4451,6 @@ export function createTaskforceMcpServer(options = {}) {
                     throw error;
                 }
             }
-            case "assign_task": {
-                const { id: inputId, assignee } = args;
-                const { id } = resolveTaskByIdentifierOrThrow(inputId);
-                const resolvedAssignee = resolveRuntimeTaskAssigneeInput(assignee);
-                if (!resolvedAssignee)
-                    throw new Error('assignee is required');
-                const updated = core.updateTask(id, { assignee: resolvedAssignee }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
-                if (!updated)
-                    throw new Error(`Task ${id} not found`);
-                recordMcpWriteAudit('assign_task', { taskId: id, assignee: resolvedAssignee });
-                await notifyResourceMutation({
-                    taskIds: [id],
-                    includeTasks: true,
-                    includeStats: true,
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                task: buildTaskWriteSummary(updated),
-                                assignee: resolvedAssignee,
-                            }, null, 2)
-                        }],
-                };
-            }
-            case "bulk_assign_tasks": {
-                const { ids, assignee } = args;
-                const list = Array.isArray(ids) ? ids : [];
-                if (list.length === 0)
-                    throw new Error('ids array is required');
-                const resolvedAssignee = resolveRuntimeTaskAssigneeInput(assignee);
-                if (!resolvedAssignee)
-                    throw new Error('assignee is required');
-                const resolvedIds = list.map((id) => resolveTaskByIdentifierOrThrow(id).id);
-                const updates = resolvedIds.map((id) => ({ id, assignee: resolvedAssignee }));
-                const preview = core.bulkUpdateFieldsPreview(updates, ACTIVE_WORKSPACE_ID);
-                const changed = [];
-                const errors = [];
-                for (const skipped of preview.skipped) {
-                    if (skipped.statusCode >= 400) {
-                        errors.push({
-                            index: skipped.index,
-                            id: skipped.id,
-                            message: skipped.message,
-                            statusCode: skipped.statusCode,
-                            code: skipped.code
-                        });
-                    }
-                }
-                for (const item of preview.toApply) {
-                    const updated = core.updateTask(item.id, item.fields, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
-                    if (!updated) {
-                        errors.push({ index: item.index, id: item.id, message: 'Task not found', statusCode: 404, code: 'TASK_NOT_FOUND' });
-                        continue;
-                    }
-                    changed.push({ id: updated.id, assignee: updated.assignee || 'unassigned' });
-                }
-                const summary = buildBatchSummary({
-                    operation: 'bulk-assign-tasks',
-                    total: resolvedIds.length,
-                    succeeded: changed.length
-                });
-                recordMcpWriteAudit('bulk_assign_tasks', {
-                    assignee: resolvedAssignee,
-                    requested: resolvedIds.length,
-                    changed: changed.length
-                });
-                await notifyResourceMutation({
-                    taskIds: resolvedIds,
-                    includeTasks: true,
-                    includeStats: true,
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                success: errors.length === 0,
-                                summary,
-                                results: {
-                                    assigned: changed,
-                                    preflight: {
-                                        deduped: preview.deduped,
-                                        skipped_noop: preview.skipped.filter((s) => s.code === 'NO_CHANGES' || s.code === 'DUPLICATE_SUPERSEDED').length
-                                    }
-                                },
-                                errors
-                            }, null, 2)
-                        }],
-                };
-            }
             case "archive_task": {
                 const { id: inputId, status, reason } = args;
                 const { id, task } = resolveTaskByIdentifierOrThrow(inputId);
@@ -4531,15 +4467,33 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "get_config": {
+                const startedAtMs = Date.now();
+                const categories = getActiveCategories();
+                const types = getActiveTypes();
+                const priorities = getActivePriorities();
+                const approaches = getActiveApproaches();
+                logMcpReadObservation('get_config', startedAtMs, {
+                    categoryCount: categories.length,
+                    typeCount: types.length,
+                    priorityCount: priorities.length,
+                    approachCount: approaches.length,
+                    activeToolProfile,
+                });
                 return {
                     content: [{
                             type: "text",
                             text: JSON.stringify({
-                                categories: getActiveCategories(),
-                                types: getActiveTypes(),
-                                priorities: getActivePriorities(),
-                                approaches: getActiveApproaches(),
-                                complexities: COMPLEXITY_OPTIONS
+                                categories,
+                                types,
+                                priorities,
+                                approaches,
+                                complexities: COMPLEXITY_OPTIONS,
+                                mcpToolProfile: {
+                                    active: activeToolProfile,
+                                    available: ['default', 'extended', 'full'],
+                                    defaultForRuntime: defaultToolProfile,
+                                    guidance: 'Cloud sessions default to the default profile. Local/dev sessions default to full. Use TASKFORCE_MCP_TOOL_PROFILE=default|extended|full for local stdio, or pass an explicit toolProfile runtime option where supported.',
+                                }
                             }, null, 2)
                         }],
                 };
@@ -5090,18 +5044,6 @@ export function createTaskforceMcpServer(options = {}) {
             case "delete_initiative_attachment": {
                 return deletePlanningAttachment('initiative', args);
             }
-            case "list_archive": {
-                const { format = "markdown" } = args;
-                const archive = core.listArchive(ACTIVE_WORKSPACE_ID);
-                if (format === "json") {
-                    return {
-                        content: [{ type: "text", text: JSON.stringify(archive.archived, null, 2) }],
-                    };
-                }
-                return {
-                    content: [{ type: "text", text: renderTaskTable(archive.archived) }],
-                };
-            }
             case "unarchive_task": {
                 const { id: inputId } = args;
                 const { id, task: existingTask } = resolveTaskByIdentifierOrThrow(inputId, { notFoundMessage: buildTaskLookupFailureMessage(String(inputId || '').trim()) });
@@ -5188,18 +5130,6 @@ export function createTaskforceMcpServer(options = {}) {
                     content: [{ type: "text", text: "Task types updated" }],
                 };
             }
-            case "bulk_update_type": {
-                const { fromType, toType } = args;
-                const count = core.bulkUpdateType(fromType, toType, ACTIVE_WORKSPACE_ID);
-                recordMcpWriteAudit('bulk_update_type', { fromType, toType, updated: count });
-                await notifyResourceMutation({
-                    includeTasks: true,
-                    includeStats: true,
-                });
-                return {
-                    content: [{ type: "text", text: `Updated ${count} items from ${fromType} to ${toType}` }],
-                };
-            }
             case "bulk_update_fields": {
                 const { updates } = args;
                 const list = Array.isArray(updates) ? updates : [];
@@ -5334,6 +5264,7 @@ export function createTaskforceMcpServer(options = {}) {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
+            assertToolProfile(name);
             assertToolPermission(name);
             ensureResolvedProfileForTool(name, args);
             assertResolvedProfileForMutatingTool(name);
@@ -5365,6 +5296,7 @@ export function createTaskforceMcpServer(options = {}) {
         workspaceId: ACTIVE_WORKSPACE_ID,
         tenantId,
         version: MCP_SERVER_VERSION,
+        toolProfile: activeToolProfile,
     };
 }
 export async function startTaskforceMcpStdioServer(options = {}) {