@taskforcehq/taskforce 0.3.324 → 0.3.327

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) => {
@@ -31,54 +91,84 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         });
     };
     register('get_task_attachments', (context) => ({
-        description: context.describeTool('List attachment descriptors for one task. This returns metadata only; use read_task_attachment for file contents. For canonical documents, prefer get_document and read_document_content for the document-focused workflow.'),
+        description: context.describeTool('List attachment descriptors for one task. Pass attachmentId when you need one attachment body or download reference. For canonical documents, prefer get_document with includeContent=true for the document-focused workflow.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
                 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. Longer content is truncated with size metadata and a download hint.'),
             },
         },
     }));
-    register('read_task_attachment', (context) => ({
-        description: context.describeTool('Read one task attachment by attachmentId. Prefer this tool over opening attachment path URLs directly. For a canonical document attachment, this response also points toward the document-specific workflow.'),
+    register('get_workstream_attachments', (context) => ({
+        description: context.describeTool('List attachment descriptors for one workstream. Pass attachmentId when you need one attachment body or download reference.'),
         inputSchema: {
             properties: {
-                taskId: stringProperty('Task ID or task reference such as T-123.'),
-                attachmentId: stringProperty('Attachment descriptor id from get_task_attachments.'),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+                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. Longer content is truncated with size metadata and a download hint.'),
             },
-            required: ['taskId', 'attachmentId'],
+            required: ['id'],
         },
     }));
-    register('get_workstream_attachments', (context) => ({
-        description: context.describeTool('List attachment descriptors for one workstream. This returns metadata only; use read_workstream_attachment for file contents.'),
+    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.'),
         inputSchema: {
             properties: {
-                id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                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: ['id'],
+            required: ['documentId', 'targetType', 'targetId'],
         },
     }));
-    register('read_workstream_attachment', (context) => ({
-        description: context.describeTool('Read one workstream attachment by attachmentId. Prefer this tool over opening attachment path URLs directly.'),
+    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: {
-                workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-                attachmentId: stringProperty('Attachment descriptor id from get_workstream_attachments.'),
-                format: stringProperty('Read format. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+                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: ['workstreamId', 'attachmentId'],
+            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.'),
+        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 generated content and attach it to a workstream. Provide inline content. Set overwrite=true to replace an existing canonical attachment with the same filename.'
+            : 'Save a file and attach it to a workstream. Provide inline content or an approved local sourcePath. Set overwrite=true to replace an existing canonical attachment with 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.'),
+                ...(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.'),
             },
@@ -96,34 +186,29 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_initiative_attachments', (context) => ({
-        description: context.describeTool('List attachment descriptors for one initiative. This returns metadata only; use read_initiative_attachment for file contents.'),
+        description: context.describeTool('List attachment descriptors for one initiative. Pass attachmentId when you need one attachment body or download reference.'),
         inputSchema: {
             properties: {
                 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. Longer content is truncated with size metadata and a download hint.'),
             },
             required: ['id'],
         },
     }));
-    register('read_initiative_attachment', (context) => ({
-        description: context.describeTool('Read one initiative attachment by attachmentId. Prefer this tool over opening attachment path URLs directly.'),
-        inputSchema: {
-            properties: {
-                initiativeId: stringProperty('Initiative ID or initiative reference such as IN-123.'),
-                attachmentId: stringProperty('Attachment descriptor id from get_initiative_attachments.'),
-                format: stringProperty('Read format. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
-            },
-            required: ['initiativeId', 'attachmentId'],
-        },
-    }));
     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 generated content and attach it to an initiative. Provide inline content. Set overwrite=true to replace an existing canonical attachment with the same filename.'
+            : 'Save a file and attach it to an initiative. Provide inline content or an approved local sourcePath. Set overwrite=true to replace an existing canonical attachment with 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.'),
+                ...(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.'),
             },
@@ -151,7 +236,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_image', (context) => ({
-        description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details. When the image is being used for UI, placement, or visual correction feedback, read the saved annotation payload before making changes.'),
+        description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_image_annotations for saved annotation sessions and payloads. When the image is being used for UI, placement, or visual correction feedback, read the saved annotation payload before making changes.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Image asset id or image reference such as I-123.'),
@@ -160,7 +245,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('search_documents', (context) => ({
-        description: context.describeTool('Search document assets by keyword, title, filename, caption, or D-123 reference. Use this before get_document when you only know a rough identifier. Search results guide the next step into get_document and read_document_content.'),
+        description: context.describeTool('Search document assets by keyword, title, filename, caption, or D-123 reference. Use this before get_document when you only know a rough identifier. Search results guide the next step into get_document.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Search term for document lookup, including D-123 references.'),
@@ -170,40 +255,40 @@ 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. Use this first when the user references a document, then call read_document_content to inspect what it is reviewing.'),
-        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.'),
-            },
-        },
-    }));
-    register('read_document_content', (context) => ({
-        description: context.describeTool('Read the canonical document body for one document. Use this when an AI needs to inspect what it is reviewing before adding review comments.'),
+        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: {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
-                maxChars: numberProperty('Optional max inline character count for readable documents.'),
+                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. Longer content is truncated with size metadata and a download hint.'),
             },
-            required: ['documentId'],
         },
     }));
-    register('get_annotated_attachment_sessions', (context) => ({
-        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload. If the user is pointing at a visual target in I-123, do not stop at the screenshot alone; inspect the saved session payload next.'),
+    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: {
-                imageId: stringProperty('Image asset id or image reference such as I-123.'),
+                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: ['imageId'],
+            required: ['documentId', 'content'],
         },
     }));
-    register('read_annotated_attachment_payload', (context) => ({
-        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints. Use this as the authoritative instruction source when I-123 is being used for UI placement or visual change requests.'),
+    register('get_image_annotations', (context) => ({
+        description: context.describeTool('List saved annotation sessions for one image or task, and optionally include one session payload. Use this after get_image when an image reference such as I-123 is being used for UI, placement, or visual correction feedback. Pass sessionId when you need the authoritative payload for a specific saved session.'),
         inputSchema: {
             properties: {
-                sessionId: stringProperty('Annotated attachment session id.'),
+                imageId: stringProperty('Image asset id or image reference such as I-123.'),
+                imageAssetId: stringProperty('Alias for imageId. Image asset id or image reference such as I-123.'),
+                taskId: stringProperty('Optional task ID or task reference such as T-123 to narrow sessions linked to one task.'),
+                sessionId: stringProperty('Optional annotated attachment session id to include the structured payload for one session.'),
             },
-            required: ['sessionId'],
         },
     }));
     register('create_annotated_attachment_session', (context) => ({
@@ -211,7 +296,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'],
         },
@@ -222,6 +309,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'],
         },
@@ -240,9 +328,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) => ({
@@ -258,7 +350,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) => ({
@@ -266,19 +363,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'],
         },
@@ -289,12 +374,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'],
         },
@@ -305,9 +393,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) => ({
@@ -320,26 +408,22 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             required: ['sessionId', 'markerId'],
         },
     }));
-    register('get_document_review_sessions', (context) => ({
-        description: context.describeTool('List review sessions for one document such as D-123. Use read_document_content first when you need to inspect the document body before choosing a session.'),
+    register('get_document_reviews', (context) => ({
+        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.'),
-            },
-            required: ['documentId'],
-        },
-    }));
-    register('get_document_review_session', (context) => ({
-        description: context.describeTool('Get one document review session with its comments and summary state.'),
-        inputSchema: {
-            properties: {
                 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.',
+                },
             },
-            required: ['sessionId'],
         },
     }));
     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.'),
@@ -349,23 +433,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.'),
@@ -373,7 +458,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                     type: 'object',
                     properties: {
                         body: { type: 'string' },
-                        anchor: { type: 'object' },
+                        anchor: documentReviewAnchorProperty(),
                     },
                     required: ['body'],
                 }),
@@ -381,33 +466,48 @@ 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 multi-comment first-pass reviews.'),
         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.'),
             },
             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) => ({
@@ -422,23 +522,43 @@ 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.'),
                 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.'),
+        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: {