@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/mcp/documentAssetRegistrar.js

@@ -9,7 +9,67 @@ function booleanProperty(description) {
     return { type: 'boolean', description };
 }
 function arrayProperty(description, items) {
-    return { type: 'array', description, items };
+    return { type: 'array', description, items: items };
+}
+function annotatedAttachmentMarkerProperty() {
+    return {
+        type: 'object',
+        properties: {
+            type: { type: 'string' },
+            kind: { type: 'string' },
+            x: { type: 'number' },
+            y: { type: 'number' },
+            width: { type: 'number' },
+            height: { type: 'number' },
+            x2: { type: 'number' },
+            y2: { type: 'number' },
+            text: { type: 'string' },
+            instruction: { type: 'string' },
+            instructionType: { type: 'string' },
+            color: { type: 'string' },
+        },
+        additionalProperties: false,
+    };
+}
+function documentReviewAnchorProperty(options = {}) {
+    const anchorVariants = [
+        {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['document'] },
+            },
+            required: ['kind'],
+            additionalProperties: false,
+        },
+        {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['quote'] },
+                quote: { type: 'string' },
+                occurrenceIndex: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'null' }] },
+                prefix: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+                suffix: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+            },
+            required: ['kind', 'quote'],
+            additionalProperties: false,
+        },
+        {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['line-range'] },
+                startLine: { type: 'integer', minimum: 1 },
+                endLine: { type: 'integer', minimum: 1 },
+            },
+            required: ['kind', 'startLine', 'endLine'],
+            additionalProperties: false,
+        },
+    ];
+    return {
+        description: options.nullable
+            ? 'Document, quote, or line-range anchor; null clears it.'
+            : 'Document, quote, or line-range anchor; null leaves the comment unanchored.',
+        anyOf: [...anchorVariants, { type: 'null' }],
+    };
 }
 export function registerDocumentAssetTools(registerTool, executeTool) {
     const register = (name, buildDescriptor) => {
@@ -25,6 +85,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                         properties: descriptor.inputSchema.properties,
                         ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
                     },
+                    ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
                 };
             },
             handler: bindDomainTool(executeTool, name),
@@ -38,7 +99,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
             },
         },
     }));
@@ -49,21 +110,70 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
             },
             required: ['id'],
         },
     }));
+    register('link_document', (context) => ({
+        description: context.describeTool('Link an existing canonical document to a task, initiative, or workstream without copying it. The operation is idempotent. Use search_documents first when you do not know the exact D-123 reference or asset id.'),
+        annotations: { idempotentHint: true },
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
+                targetType: stringProperty('Entity type to link the document to.', ['task', 'initiative', 'workstream']),
+                targetId: stringProperty('Entity id or reference such as T-123, IN-123, or WS-123.'),
+                caption: stringProperty('Optional caption shown on the target entity.'),
+            },
+            required: ['documentId', 'targetType', 'targetId'],
+        },
+    }));
+    register('unlink_document', (context) => ({
+        description: context.describeTool('Remove a document reference from a task, initiative, or workstream without deleting the canonical document. This only removes links created as references; use the target-specific delete attachment tool for managed attachments.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
+                targetType: stringProperty('Entity type to unlink the document from.', ['task', 'initiative', 'workstream']),
+                targetId: stringProperty('Entity id or reference such as T-123, IN-123, or WS-123.'),
+            },
+            required: ['documentId', 'targetType', 'targetId'],
+        },
+    }));
+    register('rehome_document', (context) => ({
+        description: context.describeTool('Atomically move an existing canonical document reference between a task, initiative, or workstream without copying or deleting the document. Use this instead of separate link_document and unlink_document calls when correcting planning scope.'),
+        annotations: { idempotentHint: true },
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
+                sourceType: stringProperty('Current entity type holding the reference.', ['task', 'initiative', 'workstream']),
+                sourceId: stringProperty('Current entity id or reference such as T-123, IN-123, or WS-123.'),
+                destinationType: stringProperty('Destination entity type for the reference.', ['task', 'initiative', 'workstream']),
+                destinationId: stringProperty('Destination entity id or reference such as T-123, IN-123, or WS-123.'),
+                caption: stringProperty('Optional caption shown on the destination entity.'),
+                idempotencyKey: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 128,
+                    description: 'Opaque retry key scoped to the current caller, workspace, document, and endpoints.',
+                },
+            },
+            required: ['documentId', 'sourceType', 'sourceId', 'destinationType', 'destinationId', 'idempotencyKey'],
+        },
+    }));
     register('save_workstream_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to a workstream. Use this for generated content or existing local files from disk. In cloud MCP, use inline content instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+        description: context.describeTool(context.runtimeMode === 'cloud'
+            ? 'Save inline content as a workstream-owned attachment. Use overwrite=true to replace the same filename.'
+            : 'Save inline content or an approved local file as a workstream-owned attachment. Use overwrite=true to replace the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
-                content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                content: stringProperty('Inline text content.'),
+                ...(context.runtimeMode === 'local' ? {
+                    sourcePath: stringProperty("Existing local file. Allowed roots: project, registered Git worktrees, Taskforce-managed sources, approved agent workspaces, or the bound profile's ~/.taskforce/qa/<username>/artifacts."),
+                } : {}),
                 caption: stringProperty('Optional attachment caption.'),
-                overwrite: booleanProperty('When true, overwrite an existing canonical workstream attachment with the same filename instead of creating a new one.'),
+                overwrite: booleanProperty('Replace the existing attachment with the same filename.'),
             },
             required: ['id', 'filename'],
         },
@@ -85,21 +195,25 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
             },
             required: ['id'],
         },
     }));
     register('save_initiative_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to an initiative. Use this for generated content or existing local files from disk. In cloud MCP, use inline content instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+        description: context.describeTool(context.runtimeMode === 'cloud'
+            ? 'Save inline content as an initiative-owned attachment. Use overwrite=true to replace the same filename.'
+            : 'Save inline content or an approved local file as an initiative-owned attachment. Use overwrite=true to replace the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
-                content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                content: stringProperty('Inline text content.'),
+                ...(context.runtimeMode === 'local' ? {
+                    sourcePath: stringProperty("Existing local file. Allowed roots: project, registered Git worktrees, Taskforce-managed sources, approved agent workspaces, or the bound profile's ~/.taskforce/qa/<username>/artifacts."),
+                } : {}),
                 caption: stringProperty('Optional attachment caption.'),
-                overwrite: booleanProperty('When true, overwrite an existing canonical initiative attachment with the same filename instead of creating a new one.'),
+                overwrite: booleanProperty('Replace the existing attachment with the same filename.'),
             },
             required: ['id', 'filename'],
         },
@@ -144,15 +258,30 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_document', (context) => ({
-        description: context.describeTool('Get a single canonical document by asset id or document reference such as D-123. Pass includeContent=true when you need the document body for review or analysis.'),
+        description: context.describeTool('Get a single canonical document by asset id or document reference such as D-123. Metadata includes contentSha256 for cheap change detection. Pass includeContent=true when you need the document body for review or analysis. Use update_document to replace the complete body of an existing text document.'),
         inputSchema: {
             properties: {
-                id: stringProperty('Document asset id or document reference such as D-123.'),
-                documentId: stringProperty('Alias for id. Document asset id or document reference such as D-123.'),
+                documentId: stringProperty('Document asset id or document reference such as D-123.'),
                 includeContent: booleanProperty('When true, include bounded inline text content or a download reference for binary documents.'),
                 format: stringProperty('Optional read mode when including content.', ['metadata', 'text', 'content', 'full', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable documents.'),
+                maxChars: numberProperty('Optional max inline character count for readable documents. Longer content is truncated with size metadata and a download hint.'),
             },
+            required: ['documentId'],
+        },
+    }));
+    register('update_document', (context) => ({
+        description: context.describeTool('Replace the complete body of an existing canonical text document by D-123 reference, document id, or asset id. Preserves document identity and links; byte-identical content is a no-op and does not increment the version. Pass expectedVersion from get_document to reject stale writes.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
+                content: stringProperty('Complete replacement text content, up to 1,048,576 UTF-8 bytes.'),
+                expectedVersion: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Optional current version from get_document. A stale value rejects the update without changing the document.',
+                },
+            },
+            required: ['documentId', 'content'],
         },
     }));
     register('get_image_annotations', (context) => ({
@@ -171,7 +300,9 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 imageId: stringProperty('Image asset id or image reference such as I-123.'),
+                taskId: stringProperty('Optional task ID or task reference such as T-123 to link to the session.'),
                 title: stringProperty('Optional session title.'),
+                sessionInstruction: stringProperty('Optional instruction applied to the whole annotation session.'),
             },
             required: ['imageId'],
         },
@@ -182,6 +313,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 title: stringProperty('Updated session title.'),
+                sessionInstruction: stringProperty('Updated instruction applied to the whole annotation session.'),
             },
             required: ['sessionId'],
         },
@@ -200,9 +332,13 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 imageId: stringProperty('Image asset id or image reference such as I-123.'),
-                prompt: stringProperty('Review instructions or focus areas for the first-pass review.'),
+                taskId: stringProperty('Optional task ID or task reference such as T-123 to link to the review.'),
+                sessionId: stringProperty('Optional existing annotation session to reuse.'),
+                title: stringProperty('Optional session title.'),
+                sessionInstruction: stringProperty('Optional instruction applied to the whole annotation session.'),
+                markers: arrayProperty('One or more review markers to save.', annotatedAttachmentMarkerProperty()),
             },
-            required: ['imageId', 'prompt'],
+            required: ['imageId', 'markers'],
         },
     }));
     register('add_annotated_attachment_marker', (context) => ({
@@ -218,7 +354,12 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 height: numberProperty('Optional normalized height in the 0..1 range.'),
                 text: stringProperty('Optional marker text or note.'),
                 instruction: stringProperty('Alias for text. Marker instruction or note.'),
+                instructionType: stringProperty('Optional marker instruction category.'),
+                color: stringProperty('Optional marker color.'),
+                x2: numberProperty('Arrow endpoint normalized x coordinate.'),
+                y2: numberProperty('Arrow endpoint normalized y coordinate.'),
             },
+            required: ['sessionId'],
         },
     }));
     register('bulk_add_annotated_attachment_markers', (context) => ({
@@ -226,19 +367,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
-                markers: arrayProperty('Marker definitions to add.', {
-                    type: 'object',
-                    properties: {
-                        type: { type: 'string' },
-                        kind: { type: 'string' },
-                        x: { type: 'number' },
-                        y: { type: 'number' },
-                        width: { type: 'number' },
-                        height: { type: 'number' },
-                        text: { type: 'string' },
-                        instruction: { type: 'string' },
-                    },
-                }),
+                markers: arrayProperty('Marker definitions to add.', annotatedAttachmentMarkerProperty()),
             },
             required: ['sessionId', 'markers'],
         },
@@ -249,12 +378,15 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 markerId: stringProperty('Marker id within the session.'),
-                type: stringProperty('Updated marker type.'),
                 x: numberProperty('Updated normalized x coordinate.'),
                 y: numberProperty('Updated normalized y coordinate.'),
                 width: numberProperty('Updated normalized width.'),
                 height: numberProperty('Updated normalized height.'),
-                text: stringProperty('Updated marker text.'),
+                x2: numberProperty('Updated arrow endpoint normalized x coordinate.'),
+                y2: numberProperty('Updated arrow endpoint normalized y coordinate.'),
+                instruction: stringProperty('Updated marker instruction.'),
+                instructionType: stringProperty('Updated marker instruction category.'),
+                color: stringProperty('Updated marker color.'),
             },
             required: ['sessionId', 'markerId'],
         },
@@ -265,9 +397,9 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 markerId: stringProperty('Marker id within the session.'),
-                order: numberProperty('Target zero-based review order.'),
+                toIndex: numberProperty('Target zero-based review order.'),
             },
-            required: ['sessionId', 'markerId', 'order'],
+            required: ['sessionId', 'markerId', 'toIndex'],
         },
     }));
     register('delete_annotated_attachment_marker', (context) => ({
@@ -281,17 +413,21 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_document_reviews', (context) => ({
-        description: context.describeTool('List review sessions for one document such as D-123, or fetch one review session by sessionId. Use get_document with includeContent=true when you need the document body before choosing a session.'),
+        description: context.describeTool('List compact review-session summaries for one document such as D-123, or fetch one session with comments and compact actors by sessionId. Pass detail=full only when fully hydrated actor metadata is required.'),
         inputSchema: {
             properties: {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
-                id: stringProperty('Alias for documentId. Document asset id or document reference such as D-123.'),
                 sessionId: stringProperty('Document review session id.'),
+                detail: {
+                    type: 'string',
+                    enum: ['compact', 'full'],
+                    description: 'Response detail level (default: compact). Full includes hydrated actor metadata and all comments when listing sessions.',
+                },
             },
         },
     }));
     register('create_document_review_session', (context) => ({
-        description: context.describeTool('Create a new document review session. Requires AI identity via resolve_profile before write operations.'),
+        description: context.describeTool('Create an explicit document review session for lifecycle control. Prefer review_document for normal first-pass reviews.'),
         inputSchema: {
             properties: {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
@@ -301,23 +437,24 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('update_document_review_session', (context) => ({
-        description: context.describeTool('Update a document review session title, status, or summary fields without creating a new session. Requires AI identity via resolve_profile before write operations.'),
+        description: context.describeTool('Update an existing review session title or status. Prefer review_document for posting normal review feedback.'),
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Document review session id.'),
-                title: stringProperty('Updated review session title.'),
-                status: stringProperty('Updated review status.'),
-                summary: stringProperty('Updated review summary.'),
+                title: {
+                    description: 'Updated review session title; null clears it.',
+                    anyOf: [{ type: 'string' }, { type: 'null' }],
+                },
+                status: stringProperty('Updated review status.', ['open', 'resolved']),
             },
             required: ['sessionId'],
         },
     }));
     register('review_document', (context) => ({
-        description: context.describeTool('Run the lower-friction document review path for one document. This helper creates or updates the review workflow while preserving a lower-friction document review path than manual session management. Requires AI identity via resolve_profile before write operations.'),
+        description: context.describeTool('Create or reuse a review session for one document and append review comments. Use this for plan and document reviews.'),
         inputSchema: {
             properties: {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
-                id: stringProperty('Alias for documentId. Document asset id or document reference such as D-123.'),
                 sessionId: stringProperty('Optional existing review session id.'),
                 title: stringProperty('Optional review session title when a new session is created.'),
                 prompt: stringProperty('Review instructions or focus areas.'),
@@ -325,7 +462,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                     type: 'object',
                     properties: {
                         body: { type: 'string' },
-                        anchor: { type: 'object' },
+                        anchor: documentReviewAnchorProperty(),
                     },
                     required: ['body'],
                 }),
@@ -333,33 +470,49 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('add_document_review_comment', (context) => ({
-        description: context.describeTool('Add a comment to a document review session. Use this for review feedback that should stay attached to the document rather than the task. Requires AI identity via resolve_profile before write operations.'),
+        description: context.describeTool('Add one follow-up comment to an existing review session. Prefer review_document for a complete review. Pass idempotencyKey only for exact retries after an ambiguous timeout.'),
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Document review session id.'),
                 body: stringProperty('Comment text.'),
-                anchor: { type: 'object', description: 'Optional anchor object such as a quote or line-range reference.' },
+                anchor: documentReviewAnchorProperty(),
+                parentCommentId: stringProperty('Optional root comment id. When supplied, adds a reply to that one-level thread; replies cannot target other replies.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['sessionId', 'body'],
         },
     }));
+    register('update_document_review_thread', (context) => ({
+        description: context.describeTool('Resolve or reopen one root document review comment thread. Only the root author may change thread status through MCP.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Document review session id.'),
+                commentId: stringProperty('Root document review comment id.'),
+                status: stringProperty('Updated thread status.', ['open', 'resolved']),
+            },
+            required: ['sessionId', 'commentId', 'status'],
+        },
+    }));
     register('update_document_review_comment', (context) => ({
-        description: context.describeTool('Update an existing document review comment without creating a new comment.'),
+        description: context.describeTool('Edit your own review comment body or anchor. Pass anchor=null to clear it; only the original author can edit.'),
         inputSchema: {
             properties: {
+                sessionId: stringProperty('Document review session id.'),
                 commentId: stringProperty('Document review comment id.'),
                 body: stringProperty('Updated comment text.'),
+                anchor: documentReviewAnchorProperty({ nullable: true }),
             },
-            required: ['commentId', 'body'],
+            required: ['sessionId', 'commentId'],
         },
     }));
     register('delete_document_review_comment', (context) => ({
         description: context.describeTool('Delete an existing document review comment when it should be removed entirely.'),
         inputSchema: {
             properties: {
+                sessionId: stringProperty('Document review session id.'),
                 commentId: stringProperty('Document review comment id.'),
             },
-            required: ['commentId'],
+            required: ['sessionId', 'commentId'],
         },
     }));
     register('link_task_context', (context) => ({
@@ -374,23 +527,45 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('save_task_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to a task. Use this for generated content, existing local files from disk, or staged remote uploads for binary files in cloud MCP. In cloud MCP, use inline content or the staged upload flow instead of server-local file paths. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
+        description: context.describeTool(context.runtimeMode === 'cloud'
+            ? 'Save a file and attach it to a task. Use inline content for AI-authored markdown/text or the staged upload flow for binary files. Set overwrite=true to replace an existing canonical attachment with the same filename.'
+            : 'Save a file and attach it to a task. Use inline content for AI-authored markdown/text or sourcePath for an approved existing local file. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
                 content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
-                sourcePath: stringProperty('Path to an existing source file for local runtimes only. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
-                uploadedPath: stringProperty('Finalize a previously staged remote upload by passing the uploaded Taskforce storage path returned by save_task_attachment init mode.'),
-                uploadDraftId: stringProperty('Finalize a previously staged remote upload by passing the uploadDraftId returned by save_task_attachment init mode.'),
-                mimeType: stringProperty('Mime type for staged remote uploads such as image/png or image/jpeg. Provide this with sizeBytes to start a staged upload.'),
-                sizeBytes: numberProperty('File size in bytes for staged remote uploads. Provide this with mimeType to start a staged upload.'),
+                ...(context.runtimeMode === 'local' ? {
+                    sourcePath: stringProperty("Existing local file. Allowed roots: project, registered Git worktrees, Taskforce-managed sources, approved agent workspaces, or the bound profile's ~/.taskforce/qa/<username>/artifacts."),
+                } : {
+                    uploadedPath: stringProperty('Finalize a previously staged remote upload by passing the uploaded Taskforce storage path returned by save_task_attachment init mode.'),
+                    uploadDraftId: stringProperty('Finalize a previously staged remote upload by passing the uploadDraftId returned by save_task_attachment init mode.'),
+                    mimeType: stringProperty('Mime type for staged remote uploads such as image/png or image/jpeg. Provide this with sizeBytes to start a staged upload.'),
+                    sizeBytes: numberProperty('File size in bytes for staged remote uploads. Provide this with mimeType to start a staged upload.'),
+                }),
+                expectedSizeBytes: numberProperty('Optional exact byte count for integrity verification. The save is rejected before attachment when the persisted bytes would differ.'),
+                expectedSha256: stringProperty('Optional lowercase or uppercase SHA-256 hex digest for integrity verification. The save is rejected before attachment when the persisted bytes would differ.'),
+                displayName: stringProperty('Optional attachment display name. Defaults to filename and is independent from caption.'),
                 caption: stringProperty('Optional attachment caption.'),
                 overwrite: booleanProperty('When true, overwrite an existing canonical task attachment with the same filename instead of creating a new one.'),
             },
             required: ['id', 'filename'],
         },
     }));
+    register('set_task_plan', (context) => ({
+        description: context.describeTool('Create or replace the canonical Markdown implementation plan for a task. Identical retries are no-ops. Optionally replace the task description with a concise summary after the plan is verified; a description failure preserves the valid plan and returns partial-success recovery guidance.'),
+        annotations: { idempotentHint: true },
+        inputSchema: {
+            properties: {
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
+                content: stringProperty('Complete Markdown plan content, up to 1,048,576 UTF-8 bytes.'),
+                caption: stringProperty('Optional canonical document title.'),
+                summary: stringProperty('Concise task description used when replaceDescription=true.'),
+                replaceDescription: booleanProperty('Replace the task description only after the canonical plan is persisted and verified.'),
+            },
+            required: ['taskId', 'content'],
+        },
+    }));
     register('delete_task_attachment', (context) => ({
         description: context.describeTool('Delete one task attachment. Use get_task_attachments first to inspect attachment ids before removing one.'),
         inputSchema: {

package/dist/mcp/documentContentCommand.d.ts

@@ -0,0 +1,94 @@
+import type { WorkspaceAssetEntry, WorkspaceAssetScanStatus } from '../storage/workspaceAssetStore.js';
+export interface UpdateDocumentContentInput {
+    assetId: string;
+    content: unknown;
+    expectedVersion?: unknown;
+}
+export interface UpdateDocumentContentResult {
+    asset: WorkspaceAssetEntry;
+    unchanged: boolean;
+    versionCreated: boolean;
+    integrity: {
+        sizeBytes: number;
+        sha256: string;
+    };
+}
+export declare class DocumentContentCommandError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code?: string, statusCode?: number, details?: Record<string, unknown> | undefined);
+}
+type DocumentAssetStore = {
+    get(assetId: string, workspaceId: string): WorkspaceAssetEntry | null;
+    updateDocumentContentMetadataIfVersion(input: {
+        workspaceId: string;
+        assetId: string;
+        expectedVersion: number;
+        contentSha256: string;
+        sizeBytes: number;
+        mimeType: string;
+        scanStatus: WorkspaceAssetScanStatus;
+        scanEngine?: string | null;
+        scanDetails?: string | null;
+        updatedAt: string;
+    }): WorkspaceAssetEntry | null;
+};
+type ContentHeadStore = {
+    lockLogicalHead(input: {
+        tenantId: string;
+        workspaceId: string;
+        kind: 'document';
+        logicalPath: string;
+    }, updatedAt: string): void;
+    getHead(input: {
+        tenantId: string;
+        workspaceId: string;
+        kind: 'document';
+        logicalPath: string;
+    }): {
+        sourceUpdatedAt: string;
+    } | null;
+};
+export interface DocumentContentCommandDependencies<PreparedVersion = unknown> {
+    workspaceId: string;
+    tenantId: string;
+    basePath: string;
+    assetStore: DocumentAssetStore | null;
+    contentHeadStore: ContentHeadStore | null;
+    transaction<T>(operation: () => T): T;
+    inferMimeTypeFromPath(filePath: string): string;
+    isTextReadableMimeType(mimeType: string): boolean;
+    isValidCanonicalDocumentAsset(asset: WorkspaceAssetEntry): boolean;
+    validateStructuredDocument(relativePath: string, content: string): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    scanContent(body: Buffer): Promise<{
+        verdict: string;
+        engine?: string | null;
+        details?: string | null;
+        failClosed: boolean;
+    }>;
+    scanStatus(verdict: string | undefined): WorkspaceAssetScanStatus;
+    prepareContentVersion(input: {
+        asset: WorkspaceAssetEntry;
+        body: Buffer;
+    }): Promise<PreparedVersion | null>;
+    publishPreparedContentVersion(input: {
+        asset: WorkspaceAssetEntry;
+        version: PreparedVersion;
+        sourceUpdatedAt: string;
+        publishedAt: string;
+    }): unknown;
+    hasPublishedContentVersion?(asset: WorkspaceAssetEntry): boolean;
+    resolveLocalWritePath(basePath: string, storageKey: string): string | null;
+    nowMs?: () => number;
+    createUuid?: () => string;
+}
+export declare function createDocumentContentCommand<PreparedVersion = unknown>(deps: DocumentContentCommandDependencies<PreparedVersion>): {
+    update: (input: UpdateDocumentContentInput) => Promise<UpdateDocumentContentResult>;
+};
+export {};