@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/mcp/runtime.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as fs from 'fs';
 import * as path from 'path';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import * as os from 'node:os';
 import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce.js'; // Note .js extension for ESM
 import { COMPLEXITY_OPTIONS, resolveNumberOption, resolveStringOption, STATUS_OPTIONS } from './optionResolution.js';
@@ -15,8 +15,9 @@ import { validateStructuredDocForAttach } from './structuredDocValidation.js';
 import { validateStructuredCommentForAdd } from './structuredCommentValidation.js';
 import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
 import { resolveObjectStorageConfigFromEnv } from '../storage/objectStorageConfig.js';
-import { ObjectStorageClient } from '../storage/objectStorageClient.js';
+import { ObjectStorageClient, normalizeTaskDataRelativePath } from '../storage/objectStorageClient.js';
 import { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import { resolveVirusScanConfigFromEnv, scanBufferForThreats } from '../security/virusScan.js';
 import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../runtime/appGates.js';
 import { getDocumentReferenceLabel, parseDocumentReference } from '../utils/documentReferences.js';
 import { getImageReferenceLabel, parseImageReference } from '../utils/imageReferences.js';
@@ -24,12 +25,30 @@ import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils
 import { getTaskReferenceLabel, shouldUseProvisionalTaskReferences } from '../utils/taskReferences.js';
 import { parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { parseAiProfileSeatScope } from '../shared/aiProfileSeatScope.js';
-import { formatWorkstreamReference, resolveInitiativeReference, parseWorkstreamReference, } from '../utils/planningReferences.js';
+import { formatInitiativeReference, formatWorkstreamReference, resolveInitiativeReference, parseWorkstreamReference, } from '../utils/planningReferences.js';
 import { MCP_TOOL_PERMISSIONS, MCP_WRITE_TOOL_NAMES } from './toolRegistry.js';
 import { registerAdminWorkspaceTools } from './adminWorkspaceRegistrar.js';
 import { registerCollaborationTools } from './collaborationRegistrar.js';
 import { registerDocumentAssetTools } from './documentAssetRegistrar.js';
 import { registerTaskPlanningTools } from './taskPlanningRegistrar.js';
+function readEnvValue(name) {
+    const value = String(process.env[name] || '').trim();
+    return value || null;
+}
+function buildStdioAuthFromEnv() {
+    return {
+        aiProfileToken: readEnvValue('TASKFORCE_AI_PROFILE_TOKEN'),
+        aiProfileName: readEnvValue('TASKFORCE_AI_NAME'),
+        aiProfileIcon: readEnvValue('TASKFORCE_AI_ICON'),
+        aiProfileColor: readEnvValue('TASKFORCE_AI_COLOR'),
+        aiProfileDescription: readEnvValue('TASKFORCE_AI_DESCRIPTION'),
+        aiProfileRole: readEnvValue('TASKFORCE_AI_ROLE'),
+        aiProfileProvider: readEnvValue('TASKFORCE_AI_PROVIDER'),
+        aiProfileModel: readEnvValue('TASKFORCE_AI_MODEL'),
+        aiProfileSurfaceType: parseAiProfileSurfaceType(readEnvValue('TASKFORCE_AI_SURFACE_TYPE')),
+        aiProfileSeatScope: parseAiProfileSeatScope(readEnvValue('TASKFORCE_AI_SEAT_SCOPE')),
+    };
+}
 export function isMcpWriteToolName(name) {
     return MCP_WRITE_TOOL_NAMES.has(String(name || '').trim());
 }
@@ -81,7 +100,7 @@ function resolveRecoverableToolError(error) {
             code: 'AI_PROFILE_REQUIRED',
             nextTool: 'resolve_profile',
             suggestedArgs: {},
-            retryHint: 'Call get_current_profile to inspect binding state first, or call resolve_profile to bind an AI identity. Only pass profileToken on later mutating calls if your client is stateless.'
+            retryHint: 'Call get_current_profile to inspect binding state first, or call resolve_profile to bind an AI identity. Store the returned profileToken only in private agent/client state and pass it on later mutating calls only if your client is stateless.'
         };
     }
     if (/^Invalid AI profile token\./i.test(message)) {
@@ -90,7 +109,7 @@ function resolveRecoverableToolError(error) {
             code: 'INVALID_AI_PROFILE_TOKEN',
             nextTool: 'resolve_profile',
             suggestedArgs: {},
-            retryHint: 'Call get_current_profile to confirm whether ambient identity is already bound. If not, call resolve_profile again to obtain a fresh profileToken, then retry the original mutating tool call.'
+            retryHint: 'Call get_current_profile to confirm whether ambient identity is already bound. If not, call resolve_profile again to obtain a fresh profileToken for private agent/client storage, then retry the original mutating tool call once.'
         };
     }
     if (error instanceof TaskforceRuleError) {
@@ -116,12 +135,29 @@ function resolveRecoverableToolError(error) {
     }
     if (!message)
         return null;
+    const transient = classifyTransientMcpError(error);
+    if (transient) {
+        return {
+            message,
+            code: transient.code,
+            kind: transient.kind,
+            retryable: true,
+            details: {
+                kind: transient.kind,
+                retryable: true
+            },
+            retryHint: transient.retryHint
+        };
+    }
     const safePatterns = [
         /^Invalid /i,
         / is required$/i,
-        /^Task .+ not found$/i,
+        /^attachments must be an array$/i,
+        /^Task .+ not found/i,
+        /^Initiative .+ not found/i,
+        /^Workstream .+ not found/i,
         /^Image .+ not found in workspace .+$/i,
-        /^Attachment .+ not found on task .+$/i,
+        /^Attachment .+ not found on (task|initiative|workstream) .+$/i,
         /^Attachment is quarantined$/i,
         /^Attachment scan pending$/i,
         /^Attachment is not readable as text$/i,
@@ -141,6 +177,53 @@ function resolveRecoverableToolError(error) {
     }
     return null;
 }
+function collectErrorMessages(error) {
+    const messages = [];
+    let current = error;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof Error && current.message) {
+            messages.push(String(current.message));
+            current = current.cause;
+            continue;
+        }
+        if (typeof current === 'object') {
+            const record = current;
+            if (typeof record.message === 'string')
+                messages.push(record.message);
+            if (typeof record.code === 'string')
+                messages.push(record.code);
+            current = record.cause;
+            continue;
+        }
+        break;
+    }
+    return messages;
+}
+function classifyTransientMcpError(error) {
+    const combined = collectErrorMessages(error).join(' ').trim();
+    if (!combined)
+        return null;
+    if (/(fetch failed|ECONNRESET|ECONNREFUSED|EPIPE|socket hang up|UND_ERR_|network error|request aborted|connection terminated)/i.test(combined)) {
+        return {
+            kind: 'transport_failure',
+            code: 'MCP_TRANSPORT_FAILURE',
+            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 (/(timed out|timeout|ETIMEDOUT|query canceled|statement timeout|database timeout|postgres worker)/i.test(combined)) {
+        return {
+            kind: 'backend_timeout',
+            code: 'MCP_BACKEND_TIMEOUT',
+            retryHint: 'Taskforce reached the backend but the read timed out. Retry the same read after a short delay; repeated failures point to backend saturation rather than a missing document or attachment.'
+        };
+    }
+    return null;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function inferMimeTypeFromPath(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     const contentTypes = {
@@ -160,6 +243,22 @@ function inferMimeTypeFromPath(filePath) {
 function inferAssetKind(filePath, mimeType) {
     return inferCanonicalAssetKind(filePath, mimeType);
 }
+function scanVerdictToCanonicalStatus(verdict) {
+    if (verdict === 'pending')
+        return 'pending';
+    if (verdict === 'infected')
+        return 'infected';
+    if (verdict === 'error')
+        return 'failed';
+    return 'clean';
+}
+function inferWorkspaceIdFromStoragePath(pathValue) {
+    const normalized = String(pathValue || '').trim().replace(/\\/g, '/');
+    const match = normalized.match(/^workspaces\/([^/]+)\//);
+    if (match && match[1])
+        return match[1];
+    return 'default';
+}
 function isTextReadableMimeType(mimeTypeRaw) {
     const mimeType = String(mimeTypeRaw || '').trim().toLowerCase();
     if (!mimeType)
@@ -213,6 +312,8 @@ export function buildRecoverableToolErrorResult(error, requestId) {
                     error: resolved.message,
                     message: resolved.message,
                     ...(resolved.code ? { code: resolved.code } : {}),
+                    ...(resolved.kind ? { kind: resolved.kind } : {}),
+                    ...(resolved.retryable ? { retryable: true } : {}),
                     ...(resolved.details !== undefined ? { details: resolved.details } : {}),
                     ...(resolved.needs_confirmation ? { needs_confirmation: true } : {}),
                     ...(resolved.nextTool ? { nextTool: resolved.nextTool } : {}),
@@ -239,8 +340,7 @@ export function createTaskforceMcpServer(options = {}) {
     if (logStartup) {
         console.error(`[Taskforce MCP] Starting for project: ${PROJECT_NAME} at ${PROJECT_ROOT}`);
     }
-    const db = resolveDatabaseConfigFromEnv();
-    const tenantId = String(options.tenantId || process.env.TASKFORCE_TENANT_ID || 'default').trim() || 'default';
+    const tenantId = String(options.tenantId || options.core?.getTenantId() || process.env.TASKFORCE_TENANT_ID || 'default').trim() || 'default';
     const MCP_SERVER_VERSION = (() => {
         if (options.version)
             return String(options.version).trim() || '0.0.0-dev';
@@ -255,14 +355,17 @@ export function createTaskforceMcpServer(options = {}) {
             return '0.0.0-dev';
         }
     })();
-    const core = new TaskforceCore({
-        projectRoot: PROJECT_ROOT,
-        tenantId,
-        database: {
-            provider: db.provider,
-            connectionString: db.connectionString
-        }
-    });
+    const core = options.core || (() => {
+        const db = resolveDatabaseConfigFromEnv();
+        return new TaskforceCore({
+            projectRoot: PROJECT_ROOT,
+            tenantId,
+            database: {
+                provider: db.provider,
+                connectionString: db.connectionString
+            }
+        });
+    })();
     const workspaceFromEnv = String(options.workspaceId || process.env.TASKFORCE_WORKSPACE_ID || '').trim();
     let ACTIVE_WORKSPACE_ID = '';
     const workspaceFromEnvValid = workspaceFromEnv && workspaceFromEnv.toLowerCase() !== 'default'
@@ -342,7 +445,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, and include profileToken on later mutating tool calls only when your MCP client does not preserve session identity between calls.\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, coding_tool for the coding surface or terminal tool itself, chat_app for a conversational app identity, ide for an IDE-native copilot identity, and other only when none of those fit. If you are unsure and you are registering a named collaborator such as a teammate-style AI persona, 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_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.`,
     });
     const TOOL_PERMISSIONS = MCP_TOOL_PERMISSIONS;
     const RESOURCE_PERMISSIONS = {
@@ -653,7 +756,7 @@ export function createTaskforceMcpServer(options = {}) {
         }
         const previousStatus = String(task?.status || 'task').trim() || 'task';
         const previousAssignee = String(task?.assignee || '').trim() || 'unassigned';
-        if (previousStatus === 'done' || previousStatus === 'review' || previousStatus === 'cancelled') {
+        if (previousStatus === 'done' || previousStatus === 'cancelled') {
             throw new Error(`Task ${formatTaskIdentifier(task)} is already ${previousStatus} and must be reopened explicitly before active work resumes.`);
         }
         if (previousAssignee !== 'unassigned' && previousAssignee !== currentAiAssignee) {
@@ -690,6 +793,26 @@ export function createTaskforceMcpServer(options = {}) {
             return auditActorUserId;
         return undefined;
     }
+    function isStableMcpCommentActorRef(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (!normalized)
+            return false;
+        return normalized === 'user'
+            || normalized.startsWith('user-')
+            || normalized.startsWith('ai-profile-');
+    }
+    function resolveMcpCommentAuthorInput(value) {
+        const raw = String(value || '').trim();
+        const normalized = raw.toLowerCase();
+        const activeActor = getActiveMcpActorRef();
+        if (!raw || normalized === 'system')
+            return activeActor;
+        if (isStableMcpCommentActorRef(raw))
+            return raw;
+        if (activeActor !== 'system')
+            return activeActor;
+        return raw;
+    }
     function resolveProfileTokenFromArgs(args) {
         if (!args || typeof args !== 'object' || Array.isArray(args))
             return null;
@@ -946,8 +1069,8 @@ export function createTaskforceMcpServer(options = {}) {
         };
     }
     function createAnnotatedAttachmentAnnotationFromArgs(args, order) {
-        const kind = normalizeAnnotatedAttachmentKind(args.kind);
-        const instruction = normalizeOptionalString(args.instruction);
+        const kind = normalizeAnnotatedAttachmentKind(args.kind ?? args.type);
+        const instruction = normalizeOptionalString(args.instruction ?? args.text);
         if (!instruction) {
             throw new Error('instruction is required');
         }
@@ -1107,6 +1230,61 @@ export function createTaskforceMcpServer(options = {}) {
             ...details,
         });
     }
+    const burstyQaReadToolNames = new Set([
+        'get_initiative',
+        'get_workstream',
+        'list_initiatives',
+        'list_workstreams',
+        'get_workstream_attachments',
+        'get_initiative_attachments',
+        'get_document',
+        'read_document_content',
+    ]);
+    const burstyQaReadRetryDelaysMs = [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)) {
+                    logMcpReadObservation(toolName, startedAtMs, {
+                        attempts: attempt + 1,
+                        retried: attempt > 0,
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                const transient = classifyTransientMcpError(error);
+                if (!burstyQaReadToolNames.has(toolName) || !transient || attempt >= burstyQaReadRetryDelaysMs.length) {
+                    if (burstyQaReadToolNames.has(toolName) && transient) {
+                        logMcpStructuredEvent('warn', 'tool_read_retry_exhausted', {
+                            toolName,
+                            attempts: attempt + 1,
+                            durationMs: Date.now() - startedAtMs,
+                            errorKind: transient.kind,
+                            errorCode: transient.code,
+                        });
+                    }
+                    throw error;
+                }
+                const delayMs = burstyQaReadRetryDelaysMs[attempt];
+                attempt += 1;
+                logMcpStructuredEvent('warn', 'tool_read_retry', {
+                    toolName,
+                    attempt,
+                    nextAttempt: attempt + 1,
+                    delayMs,
+                    durationMs: Date.now() - startedAtMs,
+                    errorKind: transient.kind,
+                    errorCode: transient.code,
+                    args: sanitizeToolArgsForLog(args),
+                });
+                await delay(delayMs);
+            }
+        }
+    }
     /**
      * Helpers
      */
@@ -1601,6 +1779,61 @@ export function createTaskforceMcpServer(options = {}) {
             workstreams,
         };
     }
+    function buildPlanningWriteResponseHydrationFallbackDetails(targetType, entity, context, error) {
+        const transient = classifyTransientMcpError(error);
+        if (!transient)
+            throw error;
+        const referenceLabel = targetType === 'initiative'
+            ? (typeof entity?.referenceLabel === 'string' ? entity.referenceLabel : formatInitiativeReference(entity))
+            : (typeof entity?.referenceLabel === 'string' ? entity.referenceLabel : formatWorkstreamReference(entity));
+        logMcpStructuredEvent('warn', 'planning_write_response_hydration_fallback', {
+            context,
+            targetType,
+            targetId: entity?.id || null,
+            referenceLabel,
+            errorKind: transient.kind,
+            errorCode: transient.code,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return {
+            fallback: true,
+            reason: transient.kind,
+            code: transient.code,
+            retryable: true,
+            message: 'The write completed, but Taskforce skipped the richer response hydration after a transient read timeout.',
+            nextTool: targetType === 'initiative' ? 'get_initiative' : 'get_workstream',
+            suggestedArgs: {
+                id: referenceLabel || entity?.id || '',
+            },
+        };
+    }
+    function buildPostWriteInitiativeResourcePayload(initiative, context) {
+        try {
+            return buildInitiativeResourcePayload(initiative);
+        }
+        catch (error) {
+            return {
+                initiative: buildPlanningInitiativeSummary(initiative),
+                workstreamCount: 0,
+                taskCount: 0,
+                workstreams: [],
+                responseHydration: buildPlanningWriteResponseHydrationFallbackDetails('initiative', initiative, context, error),
+            };
+        }
+    }
+    function buildPostWriteWorkstreamResourcePayload(workstream, context) {
+        try {
+            return buildWorkstreamResourcePayload(workstream);
+        }
+        catch (error) {
+            return {
+                workstream: buildPlanningWorkstreamSummary(workstream),
+                taskCount: 0,
+                tasks: [],
+                responseHydration: buildPlanningWriteResponseHydrationFallbackDetails('workstream', workstream, context, error),
+            };
+        }
+    }
     function buildInitiativeLookupFailureMessage(initiativeIdOrReference) {
         const normalizedValue = String(initiativeIdOrReference || '').trim() || 'initiative';
         return `Initiative ${normalizedValue} not found in workspace ${ACTIVE_WORKSPACE_ID}.`;
@@ -1892,9 +2125,314 @@ export function createTaskforceMcpServer(options = {}) {
             tools,
         };
     });
-    /**
-     * Tool Execution
-     */
+    const resolvePlanningAttachmentTarget = (targetType, inputId) => {
+        if (targetType === 'initiative') {
+            const { id, initiative } = resolveInitiativeByIdentifierOrThrow(inputId);
+            return {
+                type: targetType,
+                id,
+                entity: initiative,
+                referenceLabel: typeof initiative.referenceLabel === 'string' ? initiative.referenceLabel : formatInitiativeReference(initiative),
+            };
+        }
+        const { id, workstream } = resolveWorkstreamByIdentifierOrThrow(inputId);
+        return {
+            type: targetType,
+            id,
+            entity: workstream,
+            referenceLabel: typeof workstream.referenceLabel === 'string' ? workstream.referenceLabel : formatWorkstreamReference(workstream),
+        };
+    };
+    const formatPlanningAttachmentTarget = (target) => {
+        const reference = String(target.referenceLabel || '').trim();
+        if (reference)
+            return reference;
+        const title = String(target.entity?.title || '').trim();
+        if (title)
+            return `"${title}"`;
+        return target.id;
+    };
+    const listPlanningAttachmentDescriptors = (target) => (taskAttachmentHelpers.listTaskAttachmentDescriptors({
+        id: target.id,
+        attachments: Array.isArray(target.entity?.attachments) ? target.entity.attachments : [],
+    }));
+    const updatePlanningAttachmentTarget = (targetType, targetId, attachments) => (targetType === 'initiative'
+        ? core.updateInitiative(targetId, { attachments }, ACTIVE_WORKSPACE_ID)
+        : core.updateWorkstream(targetId, { attachments }, ACTIVE_WORKSPACE_ID));
+    const notifyPlanningAttachmentMutation = async (targetType, targetId, entity) => {
+        if (targetType === 'initiative') {
+            await notifyResourceMutation({
+                includeInitiatives: true,
+                initiativeIds: [targetId],
+            });
+            return;
+        }
+        await notifyResourceMutation({
+            includeWorkstreams: true,
+            workstreamIds: [targetId],
+            ...(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 { 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}`);
+        }
+        if (format === "metadata") {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            [`${targetType}Id`]: target.id,
+                            attachment,
+                            format: "metadata"
+                        }, null, 2)
+                    }],
+            };
+        }
+        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)
+                    }],
+            };
+        }
+        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)
+                    }],
+            };
+        }
+        const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
+        const buffer = await canonicalAssetHelpers.readCanonicalAttachmentBuffer(target.id, attachment, targetType);
+        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({
+                        [`${targetType}Id`]: target.id,
+                        attachment,
+                        format: "text",
+                        truncated: false,
+                        content
+                    }, null, 2)
+                }],
+        };
+    };
+    const savePlanningAttachment = async (targetType, args) => {
+        const { id: inputId, filename, content, sourcePath, caption, overwrite = false } = args;
+        const target = resolvePlanningAttachmentTarget(targetType, inputId);
+        if (!filename || typeof filename !== 'string')
+            throw new Error("filename is required");
+        const hasContent = typeof content === 'string';
+        const hasSourcePath = typeof sourcePath === 'string' && sourcePath.trim().length > 0;
+        if (hasContent === hasSourcePath) {
+            throw new Error("Provide exactly one of: content or sourcePath");
+        }
+        const now = new Date().toISOString();
+        const safeCaption = typeof caption === 'string' && caption.trim().length > 0
+            ? caption.trim()
+            : undefined;
+        const safeFilename = sanitizeFilenameForPath(filename);
+        const { projectRoot, basePath } = core.getPaths();
+        const targetForOverwrite = {
+            id: target.id,
+            attachments: Array.isArray(target.entity.attachments) ? target.entity.attachments : [],
+        };
+        const overwriteTarget = overwrite === true
+            ? canonicalAssetHelpers.resolveCanonicalOverwriteTarget(targetForOverwrite, safeFilename, taskAttachmentHelpers.describeTaskAttachment)
+            : null;
+        const canonicalAsset = overwriteTarget
+            ? null
+            : canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
+                workspaceIdRaw: ACTIVE_WORKSPACE_ID,
+                kind: inferAssetKind(safeFilename, inferMimeTypeFromPath(safeFilename)),
+                filename: safeFilename
+            });
+        const destinationPath = overwriteTarget
+            ? overwriteTarget.absolutePath
+            : path.join(basePath, canonicalAsset.relativePath);
+        fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+        if (hasContent) {
+            fs.writeFileSync(destinationPath, content, 'utf8');
+        }
+        else {
+            const trimmedSource = sourcePath.trim();
+            const sourceResolved = path.isAbsolute(trimmedSource)
+                ? path.resolve(trimmedSource)
+                : path.resolve(projectRoot, trimmedSource);
+            if (!fs.existsSync(sourceResolved)) {
+                throw new Error(`File not found: ${trimmedSource}`);
+            }
+            const sourceReal = fs.realpathSync(sourceResolved);
+            const projectRootReal = fs.realpathSync(projectRoot);
+            if (!isApprovedAttachmentSourcePath(sourceReal, projectRootReal)) {
+                throw new Error("sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root");
+            }
+            if (!fs.statSync(sourceReal).isFile()) {
+                throw new Error(`Path is not a file: ${trimmedSource}`);
+            }
+            fs.copyFileSync(sourceReal, destinationPath);
+        }
+        const relativePath = overwriteTarget
+            ? overwriteTarget.relativePath
+            : toPosixPath(path.relative(projectRoot, destinationPath));
+        if (relativePath.endsWith('.md')) {
+            const fileContent = fs.readFileSync(destinationPath, 'utf8');
+            const validation = validateStructuredDocForAttach(relativePath, fileContent);
+            if (!validation.ok) {
+                throw new Error(validation.message);
+            }
+        }
+        const isMarkdownDocument = relativePath.toLowerCase().endsWith('.md') || relativePath.toLowerCase().endsWith('.markdown');
+        const canonicalName = safeCaption || overwriteTarget?.asset.logicalName || safeFilename;
+        const persistedCaption = isMarkdownDocument
+            ? canonicalName
+            : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+        const asset = await canonicalAssetHelpers.ensureCanonicalAttachment(relativePath, targetType, target.id, persistedCaption, now, 'attachment', {
+            originalFilename: safeFilename,
+            logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+            ...(overwriteTarget
+                ? {
+                    assetId: overwriteTarget.asset.assetId,
+                    documentId: overwriteTarget.asset.documentId,
+                    createdAt: overwriteTarget.asset.createdAt,
+                    createdByUserId: overwriteTarget.asset.createdByUserId,
+                    scanStatus: overwriteTarget.asset.scanStatus,
+                    scanEngine: overwriteTarget.asset.scanEngine,
+                    scanDetails: overwriteTarget.asset.scanDetails,
+                }
+                : {})
+        });
+        const attachmentReferenceLabel = asset?.kind === 'image'
+            ? getImageReferenceLabel(asset)
+            : (asset && isValidCanonicalDocumentAsset(asset) ? getDocumentReferenceLabel(asset) : null);
+        const attachment = {
+            path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && isValidCanonicalDocumentAsset(asset) && asset.assetId
+                ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+                : `/api/taskforce/context/${encodeURIComponent((canonicalAsset || { relativePath: overwriteTarget?.descriptor.fsPath || '' }).relativePath)}`),
+            fsPath: overwriteTarget?.attachment.fsPath || canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath,
+            caption: isMarkdownDocument ? canonicalName : persistedCaption,
+            displayName: isMarkdownDocument ? canonicalName : safeFilename,
+            originalFilename: safeFilename,
+            ...(asset?.assetId ? { assetId: asset.assetId } : {}),
+            ...(typeof asset?.referenceNumber === 'number' ? { referenceNumber: asset.referenceNumber } : {}),
+            ...(attachmentReferenceLabel ? { referenceLabel: attachmentReferenceLabel } : {}),
+            timestamp: now
+        };
+        const existing = Array.isArray(target.entity.attachments)
+            ? target.entity.attachments
+            : [];
+        if (overwriteTarget) {
+            const updatedAttachments = existing.map((item, index) => (index === overwriteTarget.index
+                ? attachment
+                : item));
+            updatePlanningAttachmentTarget(targetType, target.id, updatedAttachments);
+            recordMcpWriteAudit(`save_${targetType}_attachment`, { [`${targetType}Id`]: target.id, path: attachment.fsPath, overwrite: true, attachmentId: asset?.assetId || overwriteTarget.descriptor.attachmentId });
+            await notifyPlanningAttachmentMutation(targetType, target.id, target.entity);
+            return {
+                content: [{ type: "text", text: `${targetType[0].toUpperCase()}${targetType.slice(1)} attachment overwritten for ${formatPlanningAttachmentTarget(target)}\n${JSON.stringify(attachment, null, 2)}` }],
+            };
+        }
+        const duplicate = existing.some((item) => {
+            if (typeof item === 'string') {
+                return item === attachment.path || item === attachment.fsPath;
+            }
+            if (!item || typeof item !== 'object')
+                return false;
+            if (item.path === attachment.path)
+                return true;
+            if (item.fsPath === attachment.fsPath)
+                return true;
+            return false;
+        });
+        if (duplicate) {
+            return {
+                content: [{ type: "text", text: `${targetType[0].toUpperCase()}${targetType.slice(1)} attachment saved for ${formatPlanningAttachmentTarget(target)}\n${JSON.stringify(attachment, null, 2)}\nAlready attached.` }],
+            };
+        }
+        updatePlanningAttachmentTarget(targetType, target.id, [...existing, attachment]);
+        recordMcpWriteAudit(`save_${targetType}_attachment`, { [`${targetType}Id`]: target.id, path: attachment.fsPath });
+        await notifyPlanningAttachmentMutation(targetType, target.id, target.entity);
+        return {
+            content: [{ type: "text", text: `${targetType[0].toUpperCase()}${targetType.slice(1)} attachment saved and attached to ${formatPlanningAttachmentTarget(target)}\n${JSON.stringify(attachment, null, 2)}` }],
+        };
+    };
+    const deletePlanningAttachment = async (targetType, args) => {
+        const inputId = targetType === 'initiative' ? args.initiativeId : args.workstreamId;
+        const { attachmentId } = args;
+        if (!attachmentId || typeof attachmentId !== 'string')
+            throw new Error('attachmentId is required');
+        const target = resolvePlanningAttachmentTarget(targetType, inputId);
+        const existing = Array.isArray(target.entity.attachments) ? target.entity.attachments : [];
+        const descriptors = listPlanningAttachmentDescriptors(target);
+        const targetIndex = descriptors.findIndex((entry) => entry.attachmentId === attachmentId);
+        if (targetIndex < 0) {
+            throw new Error(`Attachment ${attachmentId} not found on ${targetType} ${String(inputId || '').trim() || target.id}`);
+        }
+        const targetDescriptor = descriptors[targetIndex];
+        const updatedAttachments = existing.filter((_, index) => index !== targetIndex);
+        updatePlanningAttachmentTarget(targetType, target.id, updatedAttachments);
+        let canonicalAssetDeleted = false;
+        if (targetDescriptor.source === 'canonical' && targetDescriptor.assetId && workspaceAssetStore) {
+            workspaceAssetStore.deleteLink({
+                workspaceId: ACTIVE_WORKSPACE_ID,
+                assetId: targetDescriptor.assetId,
+                targetType,
+                targetId: target.id,
+                role: 'attachment',
+            });
+            const remainingLinks = workspaceAssetStore.listLinksForAsset(targetDescriptor.assetId, ACTIVE_WORKSPACE_ID);
+            if (remainingLinks.length === 0) {
+                workspaceAssetStore.markDeleted(targetDescriptor.assetId, ACTIVE_WORKSPACE_ID, new Date().toISOString(), null);
+                canonicalAssetDeleted = true;
+            }
+        }
+        recordMcpWriteAudit(`delete_${targetType}_attachment`, {
+            [`${targetType}Id`]: target.id,
+            attachmentId,
+            canonicalAssetDeleted,
+        });
+        await notifyPlanningAttachmentMutation(targetType, target.id, target.entity);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        [`${targetType}Id`]: target.id,
+                        attachmentId,
+                        canonicalAssetDeleted
+                    }, null, 2)
+                }],
+        };
+    };
     const executeRegisteredTool = async (name, args) => {
         switch (name) {
             case "list_tasks": {
@@ -1950,6 +2488,15 @@ export function createTaskforceMcpServer(options = {}) {
                 });
                 activeAiProfileId = resolved.profile.id;
                 activeAiBindingSource = 'session';
+                if (auditActorType === 'oauth' && auditTokenId && resolved.profile.profileToken) {
+                    core.bindMcpOAuthConnectorGrantAiProfile({
+                        grantId: auditTokenId,
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        profileId: resolved.profile.id,
+                        profileToken: resolved.profile.profileToken,
+                        profileName: resolved.profile.name,
+                    });
+                }
                 recordMcpWriteAudit('resolve_profile', {
                     profileId: resolved.profile.id,
                     created: resolved.created
@@ -2067,12 +2614,15 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "create_initiative": {
-                const { title, description, ownerId, order } = args;
+                const { title, description, ownerId, order, attachments } = args;
+                if (attachments !== undefined && !Array.isArray(attachments))
+                    throw new Error('attachments must be an array');
                 const created = core.createInitiative({
                     title,
                     description,
                     ownerId: resolvePlanningOwnerInput(ownerId),
                     order,
+                    ...(attachments !== undefined ? { attachments } : {}),
                 }, ACTIVE_WORKSPACE_ID);
                 recordMcpWriteAudit('create_initiative', { initiativeId: created.id });
                 await notifyResourceMutation({
@@ -2080,11 +2630,11 @@ export function createTaskforceMcpServer(options = {}) {
                     initiativeIds: [created.id],
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativeResourcePayload(created), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteInitiativeResourcePayload(created, 'create_initiative:response'), null, 2) }],
                 };
             }
             case "update_initiative": {
-                const { id, title, description, ownerId, order } = args;
+                const { id, title, description, ownerId, order, attachments } = args;
                 const { id: initiativeId } = resolveInitiativeByIdentifierOrThrow(id);
                 const patch = {};
                 if (title !== undefined)
@@ -2095,6 +2645,11 @@ export function createTaskforceMcpServer(options = {}) {
                     patch.ownerId = resolvePlanningOwnerInput(ownerId);
                 if (order !== undefined)
                     patch.order = order;
+                if (attachments !== undefined) {
+                    if (!Array.isArray(attachments))
+                        throw new Error('attachments must be an array');
+                    patch.attachments = attachments;
+                }
                 const updated = core.updateInitiative(initiativeId, patch, ACTIVE_WORKSPACE_ID);
                 recordMcpWriteAudit('update_initiative', { initiativeId: updated.id, changedFields: Object.keys(patch) });
                 await notifyResourceMutation({
@@ -2102,7 +2657,7 @@ export function createTaskforceMcpServer(options = {}) {
                     initiativeIds: [updated.id],
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativeResourcePayload(updated), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteInitiativeResourcePayload(updated, 'update_initiative:response'), null, 2) }],
                 };
             }
             case "archive_initiative": {
@@ -2115,7 +2670,7 @@ export function createTaskforceMcpServer(options = {}) {
                     initiativeIds: [archived.id],
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativeResourcePayload(archived), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteInitiativeResourcePayload(archived, 'archive_initiative:response'), null, 2) }],
                 };
             }
             case "unarchive_initiative": {
@@ -2128,7 +2683,7 @@ export function createTaskforceMcpServer(options = {}) {
                     initiativeIds: [unarchived.id],
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativeResourcePayload(unarchived), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteInitiativeResourcePayload(unarchived, 'unarchive_initiative:response'), null, 2) }],
                 };
             }
             case "list_workstreams": {
@@ -2144,7 +2699,9 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "create_workstream": {
-                const { title, description, ownerId, initiativeId, order } = args;
+                const { title, description, ownerId, initiativeId, order, attachments } = args;
+                if (attachments !== undefined && !Array.isArray(attachments))
+                    throw new Error('attachments must be an array');
                 const initiative = initiativeId === undefined || String(initiativeId).trim() === ''
                     ? null
                     : resolveInitiativeByIdentifierOrThrow(initiativeId).id;
@@ -2154,6 +2711,7 @@ export function createTaskforceMcpServer(options = {}) {
                     ownerId: resolvePlanningOwnerInput(ownerId),
                     initiativeId: initiative,
                     order,
+                    ...(attachments !== undefined ? { attachments } : {}),
                 }, ACTIVE_WORKSPACE_ID);
                 recordMcpWriteAudit('create_workstream', { workstreamId: created.id, initiativeId: created.initiativeId || null });
                 await notifyResourceMutation({
@@ -2162,11 +2720,11 @@ export function createTaskforceMcpServer(options = {}) {
                     ...(created.initiativeId ? { includeInitiatives: true, initiativeIds: [created.initiativeId] } : {}),
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(created), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteWorkstreamResourcePayload(created, 'create_workstream:response'), null, 2) }],
                 };
             }
             case "update_workstream": {
-                const { id, title, description, ownerId, initiativeId, order } = args;
+                const { id, title, description, ownerId, initiativeId, order, attachments } = args;
                 const { id: workstreamId, workstream: existingWorkstream } = resolveWorkstreamByIdentifierOrThrow(id);
                 const patch = {};
                 if (title !== undefined)
@@ -2177,6 +2735,11 @@ export function createTaskforceMcpServer(options = {}) {
                     patch.ownerId = resolvePlanningOwnerInput(ownerId);
                 if (order !== undefined)
                     patch.order = order;
+                if (attachments !== undefined) {
+                    if (!Array.isArray(attachments))
+                        throw new Error('attachments must be an array');
+                    patch.attachments = attachments;
+                }
                 if (initiativeId !== undefined) {
                     patch.initiativeId = String(initiativeId).trim() === ''
                         ? null
@@ -2195,7 +2758,7 @@ export function createTaskforceMcpServer(options = {}) {
                     ...(relatedInitiativeIds.size > 0 ? { includeInitiatives: true, initiativeIds: Array.from(relatedInitiativeIds) } : {}),
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(updated), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteWorkstreamResourcePayload(updated, 'update_workstream:response'), null, 2) }],
                 };
             }
             case "archive_workstream": {
@@ -2209,7 +2772,7 @@ export function createTaskforceMcpServer(options = {}) {
                     ...(existingWorkstream.initiativeId ? { includeInitiatives: true, initiativeIds: [existingWorkstream.initiativeId] } : {}),
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(archived), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteWorkstreamResourcePayload(archived, 'archive_workstream:response'), null, 2) }],
                 };
             }
             case "unarchive_workstream": {
@@ -2223,7 +2786,7 @@ export function createTaskforceMcpServer(options = {}) {
                     ...(existingWorkstream.initiativeId ? { includeInitiatives: true, initiativeIds: [existingWorkstream.initiativeId] } : {}),
                 });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamResourcePayload(unarchived), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildPostWriteWorkstreamResourcePayload(unarchived, 'unarchive_workstream:response'), null, 2) }],
                 };
             }
             case "set_task_workstream": {
@@ -2345,10 +2908,11 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "get_task_attachments": {
-                const { id } = args;
-                const task = core.resolveTaskIdentifier(id, ACTIVE_WORKSPACE_ID);
+                const { id, taskId } = args;
+                const taskIdentifier = taskId ?? id;
+                const task = core.resolveTaskIdentifier(taskIdentifier, ACTIVE_WORKSPACE_ID);
                 if (!task) {
-                    throw new Error(`Task ${id} not found`);
+                    throw new Error(`Task ${taskIdentifier} not found`);
                 }
                 return {
                     content: [{
@@ -2431,6 +2995,32 @@ export function createTaskforceMcpServer(options = {}) {
                         }],
                 };
             }
+            case "get_workstream_attachments": {
+                const { id } = args;
+                const target = resolvePlanningAttachmentTarget('workstream', id);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(buildPlanningAttachmentListPayload('workstream', target), 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)
+                        }],
+                };
+            }
+            case "read_initiative_attachment": {
+                return readPlanningAttachment('initiative', args);
+            }
             case "search_images": {
                 assertAnnotatedAttachmentReadAccess();
                 const { query, limit } = args;
@@ -2459,8 +3049,8 @@ export function createTaskforceMcpServer(options = {}) {
             }
             case "get_image": {
                 assertAnnotatedAttachmentReadAccess();
-                const { imageId } = args;
-                const image = resolveImageAssetByIdentifierOrThrow(imageId);
+                const { id, imageId } = args;
+                const image = resolveImageAssetByIdentifierOrThrow(imageId ?? id);
                 const sessionsForImage = core.listAnnotatedAttachmentSessions({
                     workspaceId: ACTIVE_WORKSPACE_ID,
                     imageAssetId: image.assetId,
@@ -2544,8 +3134,8 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "get_document": {
-                const { documentId } = args;
-                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId);
+                const { id, documentId } = args;
+                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId ?? id);
                 const linkedTasks = (workspaceAssetStore?.listLinksForAsset(asset.assetId, ACTIVE_WORKSPACE_ID) || [])
                     .filter((entry) => !entry.deletedAt)
                     .filter((entry) => entry.targetType === 'task' && !!entry.taskId)
@@ -3070,9 +3660,13 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "review_document": {
-                const { documentId, sessionId, title, comments } = args;
-                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId);
-                const normalizedComments = Array.isArray(comments) ? comments : [];
+                const { id, documentId, sessionId, title, comments, prompt } = args;
+                const asset = resolveDocumentAssetByIdentifierOrThrow(documentId ?? id);
+                const normalizedComments = Array.isArray(comments)
+                    ? comments
+                    : (typeof prompt === 'string' && prompt.trim()
+                        ? [{ body: prompt.trim() }]
+                        : []);
                 if (normalizedComments.length === 0) {
                     throw new Error('comments array is required');
                 }
@@ -3788,11 +4382,12 @@ export function createTaskforceMcpServer(options = {}) {
                 if (!validation.ok) {
                     throw new Error(validation.message);
                 }
-                const updated = core.addComment(id, text, author, ACTIVE_WORKSPACE_ID);
+                const effectiveAuthor = resolveMcpCommentAuthorInput(author);
+                const updated = core.addComment(id, text, effectiveAuthor, ACTIVE_WORKSPACE_ID, { actorRef: effectiveAuthor });
                 if (!updated) {
                     throw new Error(`Task ${id} not found`);
                 }
-                recordMcpWriteAudit('add_comment', { taskId: id, author: author || 'ai' });
+                recordMcpWriteAudit('add_comment', { taskId: id, author: effectiveAuthor });
                 await notifyResourceMutation({
                     taskIds: [id],
                     includeTasks: true,
@@ -3845,7 +4440,7 @@ export function createTaskforceMcpServer(options = {}) {
                 }
                 const updated = core.updateTask(id, {
                     attachments: [...existing, attachment]
-                }, ACTIVE_WORKSPACE_ID);
+                }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
                 if (!updated) {
                     throw new Error(`Task ${id} not found`);
                 }
@@ -3859,97 +4454,319 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "save_task_attachment": {
-                const { id: inputId, filename, content, sourcePath, caption, overwrite = false } = args;
+                const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, caption, overwrite = false } = args;
                 const { id, task } = resolveTaskByIdentifierOrThrow(inputId);
                 if (!filename || typeof filename !== 'string')
                     throw new Error("filename is required");
                 const hasContent = typeof content === 'string';
                 const hasSourcePath = typeof sourcePath === 'string' && sourcePath.trim().length > 0;
-                if (hasContent === hasSourcePath) {
-                    throw new Error("Provide exactly one of: content or sourcePath");
-                }
+                const hasUploadedPath = typeof uploadedPath === 'string' && uploadedPath.trim().length > 0;
+                const contentModeCount = Number(hasContent) + Number(hasSourcePath) + Number(hasUploadedPath);
                 const now = new Date().toISOString();
                 const safeCaption = typeof caption === 'string' && caption.trim().length > 0
                     ? caption.trim()
                     : undefined;
                 const safeFilename = sanitizeFilenameForPath(filename);
+                const safeMimeType = typeof mimeType === 'string' && mimeType.trim().length > 0
+                    ? mimeType.trim().toLowerCase()
+                    : '';
+                const numericSizeBytes = Number(sizeBytes);
+                const hasStagedInitMetadata = !!safeMimeType && Number.isFinite(numericSizeBytes) && numericSizeBytes > 0;
                 const { projectRoot, basePath } = core.getPaths();
                 const overwriteTarget = overwrite === true
                     ? canonicalAssetHelpers.resolveCanonicalOverwriteTarget(task, safeFilename, taskAttachmentHelpers.describeTaskAttachment)
                     : null;
-                const canonicalAsset = overwriteTarget
-                    ? null
-                    : canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
+                const buildAttachmentRecord = (asset, storageKey) => {
+                    const isMarkdownDocument = storageKey.toLowerCase().endsWith('.md') || storageKey.toLowerCase().endsWith('.markdown');
+                    const canonicalName = safeCaption || overwriteTarget?.asset.logicalName || safeFilename;
+                    const persistedCaption = isMarkdownDocument
+                        ? canonicalName
+                        : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                    return {
+                        path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && isValidCanonicalDocumentAsset(asset) && asset.assetId
+                            ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+                            : `/api/taskforce/context/${encodeURIComponent(storageKey)}`),
+                        fsPath: overwriteTarget?.attachment.fsPath || storageKey,
+                        caption: isMarkdownDocument ? canonicalName : persistedCaption,
+                        displayName: isMarkdownDocument ? canonicalName : safeFilename,
+                        originalFilename: safeFilename,
+                        ...(asset?.assetId ? { assetId: asset.assetId } : {}),
+                        timestamp: now
+                    };
+                };
+                if (contentModeCount === 0) {
+                    if (!hasStagedInitMetadata) {
+                        throw new Error('Provide exactly one of: content, sourcePath, or uploadedPath. To start a staged remote upload, provide mimeType and sizeBytes.');
+                    }
+                    if (runtimeMode !== 'cloud' || !objectStorageClient || objectStorageConfig.provider !== 'r2' || !objectStorageConfig.r2) {
+                        throw new Error('Staged remote uploads require cloud runtime with object storage enabled. Otherwise provide content or sourcePath.');
+                    }
+                    const stagedAsset = canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
                         workspaceIdRaw: ACTIVE_WORKSPACE_ID,
-                        kind: inferAssetKind(safeFilename, inferMimeTypeFromPath(safeFilename)),
+                        kind: inferAssetKind(safeFilename, safeMimeType),
                         filename: safeFilename
                     });
-                const destinationPath = overwriteTarget
-                    ? overwriteTarget.absolutePath
-                    : path.join(basePath, canonicalAsset.relativePath);
-                fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-                if (hasContent) {
-                    fs.writeFileSync(destinationPath, content, 'utf8');
+                    const uploadDraftId = `task-attachment-draft-${randomUUID().replace(/-/g, '')}`;
+                    const uploadExpiresInSeconds = Math.max(1, Math.floor(objectStorageConfig.r2.signedUploadTtlSeconds));
+                    const uploadExpiresAt = new Date(Date.now() + uploadExpiresInSeconds * 1000).toISOString();
+                    core.createTaskAttachmentUploadDraft({
+                        draftId: uploadDraftId,
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        taskId: id,
+                        actorRef: getActiveMcpActorRef(),
+                        storageKey: stagedAsset.relativePath,
+                        mimeType: safeMimeType,
+                        originalFilename: safeFilename,
+                        sizeBytes: Math.floor(numericSizeBytes),
+                        storageProvider: 'r2',
+                    });
+                    const uploadUrl = objectStorageClient.createSignedPutUrl(stagedAsset.relativePath, uploadExpiresInSeconds, safeMimeType);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    mode: 'staged_upload',
+                                    status: 'upload_required',
+                                    taskId: id,
+                                    referenceLabel: formatTaskIdentifier(task),
+                                    filename: safeFilename,
+                                    mimeType: safeMimeType,
+                                    sizeBytes: Math.floor(numericSizeBytes),
+                                    assetId: stagedAsset.assetId,
+                                    uploadDraftId,
+                                    expiresAt: uploadExpiresAt,
+                                    upload: {
+                                        uploadUrl,
+                                        method: 'PUT',
+                                        headers: {
+                                            'Content-Type': safeMimeType
+                                        },
+                                        uploadedPath: stagedAsset.relativePath,
+                                    },
+                                    finalize: {
+                                        tool: 'save_task_attachment',
+                                        arguments: {
+                                            id: inputId,
+                                            filename: safeFilename,
+                                            uploadDraftId,
+                                            mimeType: safeMimeType,
+                                            uploadedPath: stagedAsset.relativePath,
+                                            ...(safeCaption ? { caption: safeCaption } : {}),
+                                            ...(overwrite === true ? { overwrite: true } : {}),
+                                        }
+                                    },
+                                    guidance: 'Upload the raw file bytes to upload.uploadUrl with the listed headers before expiresAt, then call save_task_attachment again with finalize.arguments to attach the uploaded file to the task.'
+                                }, null, 2)
+                            }],
+                    };
                 }
-                else {
-                    const trimmedSource = sourcePath.trim();
-                    const sourceResolved = path.isAbsolute(trimmedSource)
-                        ? path.resolve(trimmedSource)
-                        : path.resolve(projectRoot, trimmedSource);
-                    if (!fs.existsSync(sourceResolved)) {
-                        throw new Error(`File not found: ${trimmedSource}`);
+                if (contentModeCount > 1) {
+                    throw new Error('Provide exactly one of: content, sourcePath, or uploadedPath');
+                }
+                let attachment;
+                let asset = null;
+                let storageKeyForAudit = '';
+                let replacedStorageKey = null;
+                if (hasUploadedPath) {
+                    if (!objectStorageClient || objectStorageConfig.provider !== 'r2') {
+                        throw new Error('uploadedPath requires object storage to be enabled for this MCP runtime.');
                     }
-                    const sourceReal = fs.realpathSync(sourceResolved);
-                    const projectRootReal = fs.realpathSync(projectRoot);
-                    if (!isApprovedAttachmentSourcePath(sourceReal, projectRootReal)) {
-                        throw new Error("sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root");
+                    if (!workspaceAssetStore) {
+                        throw new Error('uploadedPath requires canonical asset storage support.');
                     }
-                    if (!fs.statSync(sourceReal).isFile()) {
-                        throw new Error(`Path is not a file: ${trimmedSource}`);
+                    const normalizedUploadDraftId = typeof uploadDraftId === 'string' ? uploadDraftId.trim() : '';
+                    if (!normalizedUploadDraftId) {
+                        throw new Error('uploadedPath finalization requires uploadDraftId from the staged upload init response.');
                     }
-                    fs.copyFileSync(sourceReal, destinationPath);
-                }
-                const relativePath = overwriteTarget
-                    ? overwriteTarget.relativePath
-                    : toPosixPath(path.relative(projectRoot, destinationPath));
-                if (relativePath.endsWith('.md')) {
-                    const fileContent = fs.readFileSync(destinationPath, 'utf8');
-                    const validation = validateStructuredDocForAttach(relativePath, fileContent);
-                    if (!validation.ok) {
-                        throw new Error(validation.message);
+                    const draft = core.getTaskAttachmentUploadDraft(normalizedUploadDraftId);
+                    if (!draft || draft.discardedAt || draft.consumedAt) {
+                        throw new Error('uploadDraftId is invalid, expired, or already consumed.');
+                    }
+                    if (draft.workspaceId !== ACTIVE_WORKSPACE_ID) {
+                        throw new Error('uploadDraftId does not belong to the active workspace.');
+                    }
+                    if (draft.taskId !== id) {
+                        throw new Error('uploadDraftId does not belong to this task.');
+                    }
+                    if (draft.actorRef !== getActiveMcpActorRef()) {
+                        throw new Error('uploadDraftId was created by a different actor and cannot finalize this attachment.');
+                    }
+                    const normalizedUploadedPath = normalizeTaskDataRelativePath(uploadedPath.trim());
+                    if (!normalizedUploadedPath) {
+                        throw new Error('uploadedPath must be a valid Taskforce storage path.');
+                    }
+                    if (draft.storageKey !== normalizedUploadedPath) {
+                        throw new Error('uploadedPath does not match the staged upload draft.');
                     }
+                    if (inferWorkspaceIdFromStoragePath(normalizedUploadedPath) !== ACTIVE_WORKSPACE_ID) {
+                        throw new Error('uploadedPath does not belong to the active workspace.');
+                    }
+                    const uploadTtlSeconds = objectStorageConfig.provider === 'r2' && objectStorageConfig.r2
+                        ? Math.max(1, Math.floor(objectStorageConfig.r2.signedUploadTtlSeconds))
+                        : 0;
+                    if (uploadTtlSeconds > 0) {
+                        const draftCreatedAtMs = Date.parse(draft.createdAt);
+                        if (Number.isFinite(draftCreatedAtMs) && Date.now() > draftCreatedAtMs + uploadTtlSeconds * 1000) {
+                            core.discardTaskAttachmentUploadDraft(draft.draftId);
+                            await objectStorageClient.deleteObject(normalizedUploadedPath).catch(() => { });
+                            throw new Error('uploadDraftId has expired. Start a new staged upload.');
+                        }
+                    }
+                    const uploadedObject = await objectStorageClient.getObject(normalizedUploadedPath);
+                    if (!uploadedObject) {
+                        core.discardTaskAttachmentUploadDraft(draft.draftId);
+                        throw new Error(`Uploaded file not found: ${normalizedUploadedPath}`);
+                    }
+                    if (safeFilename !== draft.originalFilename) {
+                        throw new Error('filename does not match the staged upload draft.');
+                    }
+                    const draftMimeType = String(draft.mimeType || '').trim().toLowerCase() || 'application/octet-stream';
+                    if (safeMimeType && safeMimeType !== draftMimeType) {
+                        throw new Error('mimeType does not match the staged upload draft.');
+                    }
+                    const uploadedContentType = String(uploadedObject.contentType || '').trim().toLowerCase();
+                    if (uploadedContentType && uploadedContentType !== draftMimeType) {
+                        throw new Error('Uploaded object content type does not match the staged upload draft.');
+                    }
+                    if (uploadedObject.body.length !== draft.sizeBytes) {
+                        throw new Error('Uploaded object size does not match the staged upload draft.');
+                    }
+                    const resolvedMimeType = draftMimeType || uploadedContentType || inferMimeTypeFromPath(safeFilename);
+                    if (normalizedUploadedPath.endsWith('.md') || normalizedUploadedPath.endsWith('.markdown')) {
+                        const validation = validateStructuredDocForAttach(normalizedUploadedPath, uploadedObject.body.toString('utf8'));
+                        if (!validation.ok) {
+                            throw new Error(validation.message);
+                        }
+                    }
+                    const virusScanConfig = resolveVirusScanConfigFromEnv(process.env);
+                    const scan = await scanBufferForThreats(uploadedObject.body, virusScanConfig);
+                    if (scan.verdict === 'infected') {
+                        await objectStorageClient.deleteObject(normalizedUploadedPath).catch(() => { });
+                        throw new Error('File rejected by virus scanner.');
+                    }
+                    if (scan.verdict === 'error' && virusScanConfig.failClosed) {
+                        throw new Error('Virus scan failed. Upload blocked.');
+                    }
+                    const kind = inferAssetKind(safeFilename, resolvedMimeType);
+                    const embeddedAssetId = normalizedUploadedPath.match(/(^|\/)(asset-[a-f0-9]{32})(?=[^/]*$)/i)?.[2] || null;
+                    const existingUploadedAsset = workspaceAssetStore.getByStorageKey(normalizedUploadedPath, ACTIVE_WORKSPACE_ID);
+                    const isMarkdownDocument = normalizedUploadedPath.toLowerCase().endsWith('.md') || normalizedUploadedPath.toLowerCase().endsWith('.markdown');
+                    const canonicalName = safeCaption || overwriteTarget?.asset.logicalName || safeFilename;
+                    const persistedCaption = isMarkdownDocument
+                        ? canonicalName
+                        : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                    replacedStorageKey = overwriteTarget?.asset.storageKey && overwriteTarget.asset.storageKey !== normalizedUploadedPath
+                        ? overwriteTarget.asset.storageKey
+                        : null;
+                    asset = workspaceAssetStore.upsertAsset({
+                        assetId: overwriteTarget?.asset.assetId || existingUploadedAsset?.assetId || embeddedAssetId || `asset-${randomUUID().replace(/-/g, '')}`,
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        kind,
+                        logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                        originalFilename: safeFilename,
+                        mimeType: resolvedMimeType,
+                        storageProvider: 'r2',
+                        storageKey: normalizedUploadedPath,
+                        contentSha256: createHash('sha256').update(uploadedObject.body).digest('hex'),
+                        sizeBytes: uploadedObject.body.length,
+                        documentId: kind === 'document'
+                            ? (overwriteTarget?.asset.documentId || existingUploadedAsset?.documentId || `doc-${randomUUID().replace(/-/g, '')}`)
+                            : null,
+                        version: kind === 'document'
+                            ? Math.max(1, Number(overwriteTarget?.asset.version || existingUploadedAsset?.version || 0) + 1)
+                            : null,
+                        isLatest: true,
+                        scanStatus: scanVerdictToCanonicalStatus(scan.verdict),
+                        scanEngine: scan.engine || null,
+                        scanDetails: scan.details || null,
+                        createdByUserId: overwriteTarget?.asset.createdByUserId || getActiveMcpActorRef(),
+                        createdAt: overwriteTarget?.asset.createdAt || existingUploadedAsset?.createdAt || now,
+                        updatedAt: now,
+                        deletedAt: null,
+                        purgeAfter: null,
+                    });
+                    workspaceAssetStore.upsertLink({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        assetId: asset.assetId,
+                        taskId: id,
+                        role: 'attachment',
+                        displayName: kind === 'document' ? null : persistedCaption,
+                        updatedAt: now,
+                        deletedAt: null,
+                    });
+                    core.markTaskAttachmentUploadDraftConsumed(draft.draftId);
+                    attachment = buildAttachmentRecord(asset, normalizedUploadedPath);
+                    storageKeyForAudit = normalizedUploadedPath;
                 }
-                const isMarkdownDocument = relativePath.toLowerCase().endsWith('.md') || relativePath.toLowerCase().endsWith('.markdown');
-                const canonicalName = safeCaption || overwriteTarget?.asset.logicalName || safeFilename;
-                const persistedCaption = isMarkdownDocument
-                    ? canonicalName
-                    : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
-                const asset = canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
-                    originalFilename: safeFilename,
-                    logicalName: isMarkdownDocument ? canonicalName : safeFilename,
-                    ...(overwriteTarget
-                        ? {
-                            assetId: overwriteTarget.asset.assetId,
-                            documentId: overwriteTarget.asset.documentId,
-                            createdAt: overwriteTarget.asset.createdAt,
-                            createdByUserId: overwriteTarget.asset.createdByUserId,
-                            scanStatus: overwriteTarget.asset.scanStatus,
-                            scanEngine: overwriteTarget.asset.scanEngine,
-                            scanDetails: overwriteTarget.asset.scanDetails,
+                else {
+                    const canonicalAsset = overwriteTarget
+                        ? null
+                        : canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
+                            workspaceIdRaw: ACTIVE_WORKSPACE_ID,
+                            kind: inferAssetKind(safeFilename, inferMimeTypeFromPath(safeFilename)),
+                            filename: safeFilename
+                        });
+                    const destinationPath = overwriteTarget
+                        ? overwriteTarget.absolutePath
+                        : path.join(basePath, canonicalAsset.relativePath);
+                    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+                    if (hasContent) {
+                        fs.writeFileSync(destinationPath, content, 'utf8');
+                    }
+                    else {
+                        const trimmedSource = sourcePath.trim();
+                        const sourceResolved = path.isAbsolute(trimmedSource)
+                            ? path.resolve(trimmedSource)
+                            : path.resolve(projectRoot, trimmedSource);
+                        if (!fs.existsSync(sourceResolved)) {
+                            throw new Error(`File not found: ${trimmedSource}`);
                         }
-                        : {})
-                });
-                const attachment = {
-                    path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && isValidCanonicalDocumentAsset(asset) && asset.assetId
-                        ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
-                        : `/api/taskforce/context/${encodeURIComponent((canonicalAsset || { relativePath: overwriteTarget?.descriptor.fsPath || '' }).relativePath)}`),
-                    fsPath: overwriteTarget?.attachment.fsPath || canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath,
-                    caption: isMarkdownDocument ? canonicalName : persistedCaption,
-                    displayName: isMarkdownDocument ? canonicalName : safeFilename,
-                    originalFilename: safeFilename,
-                    ...(asset?.assetId ? { assetId: asset.assetId } : {}),
-                    timestamp: now
-                };
+                        const sourceReal = fs.realpathSync(sourceResolved);
+                        const projectRootReal = fs.realpathSync(projectRoot);
+                        if (!isApprovedAttachmentSourcePath(sourceReal, projectRootReal)) {
+                            throw new Error("sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root");
+                        }
+                        if (!fs.statSync(sourceReal).isFile()) {
+                            throw new Error(`Path is not a file: ${trimmedSource}`);
+                        }
+                        fs.copyFileSync(sourceReal, destinationPath);
+                    }
+                    const relativePath = overwriteTarget
+                        ? overwriteTarget.relativePath
+                        : toPosixPath(path.relative(projectRoot, destinationPath));
+                    if (relativePath.endsWith('.md')) {
+                        const fileContent = fs.readFileSync(destinationPath, 'utf8');
+                        const validation = validateStructuredDocForAttach(relativePath, fileContent);
+                        if (!validation.ok) {
+                            throw new Error(validation.message);
+                        }
+                    }
+                    const isMarkdownDocument = relativePath.toLowerCase().endsWith('.md') || relativePath.toLowerCase().endsWith('.markdown');
+                    const canonicalName = safeCaption || overwriteTarget?.asset.logicalName || safeFilename;
+                    const persistedCaption = isMarkdownDocument
+                        ? canonicalName
+                        : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                    asset = await canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
+                        originalFilename: safeFilename,
+                        logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                        ...(overwriteTarget
+                            ? {
+                                assetId: overwriteTarget.asset.assetId,
+                                documentId: overwriteTarget.asset.documentId,
+                                createdAt: overwriteTarget.asset.createdAt,
+                                createdByUserId: overwriteTarget.asset.createdByUserId,
+                                scanStatus: overwriteTarget.asset.scanStatus,
+                                scanEngine: overwriteTarget.asset.scanEngine,
+                                scanDetails: overwriteTarget.asset.scanDetails,
+                            }
+                            : {
+                                createdByUserId: getActiveMcpActorRef(),
+                            })
+                    });
+                    attachment = buildAttachmentRecord(asset, canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath || relativePath);
+                    storageKeyForAudit = String(attachment.fsPath || '');
+                }
                 const existing = Array.isArray(task.attachments)
                     ? task.attachments
                     : [];
@@ -3959,11 +4776,22 @@ export function createTaskforceMcpServer(options = {}) {
                         : item));
                     const updated = core.updateTask(id, {
                         attachments: updatedAttachments
-                    }, ACTIVE_WORKSPACE_ID);
+                    }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
                     if (!updated) {
                         throw new Error(`Task ${id} not found`);
                     }
-                    recordMcpWriteAudit('save_task_attachment', { taskId: id, path: attachment.fsPath, overwrite: true, attachmentId: asset?.assetId || overwriteTarget.descriptor.attachmentId });
+                    if (replacedStorageKey) {
+                        if (overwriteTarget.asset.storageProvider === 'r2' && objectStorageClient) {
+                            await objectStorageClient.deleteObject(replacedStorageKey).catch(() => { });
+                        }
+                        else if (overwriteTarget.asset.storageProvider === 'local') {
+                            const replacedAbsolutePath = path.resolve(basePath, replacedStorageKey);
+                            if (replacedAbsolutePath.startsWith(path.resolve(basePath)) && fs.existsSync(replacedAbsolutePath)) {
+                                fs.rmSync(replacedAbsolutePath, { force: true });
+                            }
+                        }
+                    }
+                    recordMcpWriteAudit('save_task_attachment', { taskId: id, path: storageKeyForAudit, overwrite: true, attachmentId: asset?.assetId || overwriteTarget.descriptor.attachmentId });
                     await notifyResourceMutation({
                         taskIds: [id],
                         includeTasks: true,
@@ -3991,11 +4819,11 @@ export function createTaskforceMcpServer(options = {}) {
                 }
                 const updated = core.updateTask(id, {
                     attachments: [...existing, attachment]
-                }, ACTIVE_WORKSPACE_ID);
+                }, ACTIVE_WORKSPACE_ID, { actorRef: getActiveMcpActorRef() });
                 if (!updated) {
                     throw new Error(`Task ${id} not found`);
                 }
-                recordMcpWriteAudit('save_task_attachment', { taskId: id, path: attachment.fsPath });
+                recordMcpWriteAudit('save_task_attachment', { taskId: id, path: storageKeyForAudit });
                 await notifyResourceMutation({
                     taskIds: [id],
                     includeTasks: true,
@@ -4004,6 +4832,12 @@ export function createTaskforceMcpServer(options = {}) {
                     content: [{ type: "text", text: `Task attachment saved and attached to ${formatTaskIdentifier(task)}\n${JSON.stringify(attachment, null, 2)}` }],
                 };
             }
+            case "save_workstream_attachment": {
+                return savePlanningAttachment('workstream', args);
+            }
+            case "save_initiative_attachment": {
+                return savePlanningAttachment('initiative', args);
+            }
             case "delete_task_attachment": {
                 const { taskId: inputTaskId, attachmentId } = args;
                 if (!attachmentId || typeof attachmentId !== 'string')
@@ -4063,6 +4897,12 @@ export function createTaskforceMcpServer(options = {}) {
                         }],
                 };
             }
+            case "delete_workstream_attachment": {
+                return deletePlanningAttachment('workstream', args);
+            }
+            case "delete_initiative_attachment": {
+                return deletePlanningAttachment('initiative', args);
+            }
             case "list_archive": {
                 const { format = "markdown" } = args;
                 const archive = core.listArchive(ACTIVE_WORKSPACE_ID);
@@ -4314,7 +5154,7 @@ export function createTaskforceMcpServer(options = {}) {
             if (!handler) {
                 throw new Error(`Unknown tool: ${name}`);
             }
-            return await handler((args || {}));
+            return await executeMcpToolWithReadRetry(name, (args || {}), handler);
         }
         catch (error) {
             const recoverable = buildRecoverableToolErrorResult(error, auditRequestId);
@@ -4341,7 +5181,14 @@ export function createTaskforceMcpServer(options = {}) {
     };
 }
 export async function startTaskforceMcpStdioServer(options = {}) {
-    const runtime = createTaskforceMcpServer(options);
+    const envAuth = buildStdioAuthFromEnv();
+    const runtime = createTaskforceMcpServer({
+        ...options,
+        auth: {
+            ...envAuth,
+            ...(options.auth || {}),
+        },
+    });
     const transport = new StdioServerTransport();
     await runtime.server.connect(transport);
     return { ...runtime, transport };