@taskforcehq/taskforce 0.3.324 → 0.3.326

package/dist/hooks/useTaskforce.js

@@ -62,7 +62,7 @@ import { useTaskFilters } from './tasks/useTaskFilters';
 import { useTaskFormActions } from './tasks/useTaskFormActions';
 import { useTaskRelationships } from './tasks/useTaskRelationships';
 import { useTaskActions } from './tasks/useTaskActions';
-import { clearPersistedWorkspaceId, logBootstrapDebug, persistRemoteUiState, readPersistedAppUiState, readPersistedWorkspaceId, writePersistedAppUiState, writePersistedWorkspaceId } from './workspace/workspaceLocalState';
+import { areFilterTaxonomySignaturesEqual, buildFilterTaxonomySignature, clearPersistedWorkspaceId, logBootstrapDebug, persistRemoteUiState, readPersistedAppUiState, readPersistedWorkspaceId, writePersistedAppUiState, writePersistedWorkspaceId } from './workspace/workspaceLocalState';
 import { useTaskforceApiRouting } from './workspace/useTaskforceApiRouting';
 import { useTaskforceAuthBootstrap } from './auth/useTaskforceAuthBootstrap';
 import { deriveAuthGuardPolicy } from './auth/useAuthGuardPolicy';
@@ -442,6 +442,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const authSessionLastCheckedAtRef = useRef(0);
     const authSessionLastResultRef = useRef(hasOptimisticLocalAuth);
     const currentWorkspaceIdRef = useRef(currentWorkspaceId);
+    const pendingPersistedTaxonomyUiStateRef = useRef(null);
     const explicitWorkspaceSelectionRef = useRef(null);
     const workspaceTransitionEpochRef = useRef(0);
     const bootstrapTraceSeedRef = useRef((() => {
@@ -1238,9 +1239,26 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         authRequiredForApiRef.current = authRequiredForApi;
         isAuthenticatedRef.current = isAuthenticated;
     }, [authSessionResolved, authRequiredForApi, isAuthenticated]);
+    const currentFilterTaxonomySignature = useMemo(() => (referenceDataLoaded
+        ? buildFilterTaxonomySignature({
+            categories: activeCategories,
+            types: activeTypes,
+            priorities,
+            taxonomies
+        })
+        : null), [activeCategories, activeTypes, priorities, referenceDataLoaded, taxonomies]);
     const applyPersistedUiState = useCallback((state, options) => {
-        if (!state)
+        if (!state) {
+            pendingPersistedTaxonomyUiStateRef.current = null;
             return;
+        }
+        const hasPersistedTaxonomyFilterState = Array.isArray(state.filterCategories)
+            || Array.isArray(state.filterPriorities)
+            || Array.isArray(state.filterTypes)
+            || (state.filterTaxonomies && typeof state.filterTaxonomies === 'object');
+        if (!hasPersistedTaxonomyFilterState) {
+            pendingPersistedTaxonomyUiStateRef.current = null;
+        }
         const hasPersistedFilterState = Array.isArray(state.filterCategories)
             || Array.isArray(state.filterPriorities)
             || Array.isArray(state.filterTypes)
@@ -1248,6 +1266,20 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             || Array.isArray(state.filterAssignees)
             || typeof state.filterAssigneesAllSelected === 'boolean'
             || (state.filterTaxonomies && typeof state.filterTaxonomies === 'object');
+        const canCompareTaxonomySignature = currentFilterTaxonomySignature !== null;
+        if (hasPersistedTaxonomyFilterState && !canCompareTaxonomySignature) {
+            pendingPersistedTaxonomyUiStateRef.current = {
+                state,
+                skipActiveWorkspaceModule: options?.skipActiveWorkspaceModule
+            };
+        }
+        const canApplyTaxonomyFilters = hasPersistedTaxonomyFilterState
+            && canCompareTaxonomySignature
+            && areFilterTaxonomySignaturesEqual(state.filterTaxonomySignature, currentFilterTaxonomySignature);
+        const shouldResetTaxonomyFilters = hasPersistedTaxonomyFilterState
+            && canCompareTaxonomySignature
+            && !canApplyTaxonomyFilters;
+        const taxonomyFiltersAreReady = !hasPersistedTaxonomyFilterState || canApplyTaxonomyFilters || shouldResetTaxonomyFilters;
         if (!options?.skipActiveWorkspaceModule) {
             if (typeof state.activeWorkspaceModule === 'string') {
                 setActiveWorkspaceModuleState(state.activeWorkspaceModule);
@@ -1264,28 +1296,39 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             setZenModeState(state.zenMode);
         if (typeof state.searchQuery === 'string')
             setSearchQuery(state.searchQuery);
-        if (Array.isArray(state.filterCategories))
-            setFilterCategories(state.filterCategories);
-        if (Array.isArray(state.filterPriorities))
-            setFilterPriorities(state.filterPriorities);
-        if (Array.isArray(state.filterTypes))
-            setFilterTypes(state.filterTypes);
+        if (canApplyTaxonomyFilters) {
+            if (Array.isArray(state.filterCategories))
+                setFilterCategories(state.filterCategories);
+            if (Array.isArray(state.filterPriorities))
+                setFilterPriorities(state.filterPriorities);
+            if (Array.isArray(state.filterTypes))
+                setFilterTypes(state.filterTypes);
+            if (state.filterTaxonomies && typeof state.filterTaxonomies === 'object')
+                setFilterTaxonomies(state.filterTaxonomies);
+        }
+        else if (shouldResetTaxonomyFilters) {
+            setFilterCategories(activeCategories.map((category) => category.value));
+            setFilterPriorities(priorities.map((priority) => priority.value));
+            setFilterTypes(activeTypes.map((type) => type.value));
+            setFilterTaxonomies({});
+        }
         if (Array.isArray(state.filterStatus))
             setFilterStatus(state.filterStatus);
         if (Array.isArray(state.filterAssignees))
             setFilterAssignees(state.filterAssignees);
         if (typeof state.filterAssigneesAllSelected === 'boolean')
             setFilterAssigneesAllSelected(state.filterAssigneesAllSelected);
-        if (state.filterTaxonomies && typeof state.filterTaxonomies === 'object')
-            setFilterTaxonomies(state.filterTaxonomies);
         if (state.sortBy === 'created' || state.sortBy === 'priority' || state.sortBy === 'updated' || state.sortBy === 'complexity')
             setSortBy(state.sortBy);
         if (state.sortOrder === 'asc' || state.sortOrder === 'desc')
             setSortOrder(state.sortOrder);
-        if (typeof state.hasInitedFilters === 'boolean') {
+        if (shouldResetTaxonomyFilters) {
+            setHasInitedFilters(true);
+        }
+        else if (typeof state.hasInitedFilters === 'boolean' && taxonomyFiltersAreReady) {
             setHasInitedFilters(state.hasInitedFilters);
         }
-        else if (hasPersistedFilterState) {
+        else if (hasPersistedFilterState && taxonomyFiltersAreReady) {
             setHasInitedFilters(true);
         }
         if (typeof state.showChecklist === 'boolean')
@@ -1295,7 +1338,16 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         if (typeof state.exportEnvironment === 'string' && state.exportEnvironment.trim().length > 0) {
             setExportEnvironment(state.exportEnvironment.trim());
         }
-    }, []);
+    }, [activeCategories, activeTypes, currentFilterTaxonomySignature, priorities]);
+    useEffect(() => {
+        if (!currentFilterTaxonomySignature || !pendingPersistedTaxonomyUiStateRef.current)
+            return;
+        const pending = pendingPersistedTaxonomyUiStateRef.current;
+        pendingPersistedTaxonomyUiStateRef.current = null;
+        applyPersistedUiState(pending.state, {
+            skipActiveWorkspaceModule: pending.skipActiveWorkspaceModule
+        });
+    }, [applyPersistedUiState, currentFilterTaxonomySignature]);
     const loadPersistedUiState = useCallback(async (workspaceIdOverride) => {
         const targetWorkspaceId = String(workspaceIdOverride || currentWorkspaceIdRef.current || currentWorkspaceId || 'default').trim() || 'default';
         const uiStateLoadKey = `${runtimeMode}:${workspaceUiStateScope}:${targetWorkspaceId}`;
@@ -1369,6 +1421,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             filterAssignees,
             filterAssigneesAllSelected,
             filterTaxonomies,
+            ...(currentFilterTaxonomySignature ? { filterTaxonomySignature: currentFilterTaxonomySignature } : {}),
             sortBy,
             sortOrder,
             hasInitedFilters,
@@ -1404,6 +1457,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         filterAssignees,
         filterAssigneesAllSelected,
         filterTaxonomies,
+        currentFilterTaxonomySignature,
         sortBy,
         sortOrder,
         hasInitedFilters,
@@ -2557,6 +2611,9 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         setInitiatives((current) => upsertEntityById(current, data));
         return data;
     }, [fetchPlanningEntities]);
+    const refreshPlanningEntitiesInBackground = useCallback(() => {
+        void fetchPlanningEntities();
+    }, [fetchPlanningEntities]);
     const archiveInitiative = useCallback(async (id) => {
         const res = await fetch(`/api/taskforce/initiative/${encodeURIComponent(id)}/archive`, {
             method: 'POST',
@@ -2565,10 +2622,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         if (!res.ok) {
             throw new Error(data?.error || `Failed to archive initiative (${res.status})`);
         }
-        await fetchPlanningEntities();
         setInitiatives((current) => upsertEntityById(current, data));
+        refreshPlanningEntitiesInBackground();
         return data;
-    }, [fetchPlanningEntities]);
+    }, [refreshPlanningEntitiesInBackground]);
     const unarchiveInitiative = useCallback(async (id) => {
         const res = await fetch(`/api/taskforce/initiative/${encodeURIComponent(id)}/unarchive`, {
             method: 'POST',
@@ -2577,10 +2634,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         if (!res.ok) {
             throw new Error(data?.error || `Failed to unarchive initiative (${res.status})`);
         }
-        await fetchPlanningEntities();
         setInitiatives((current) => upsertEntityById(current, data));
+        refreshPlanningEntitiesInBackground();
         return data;
-    }, [fetchPlanningEntities]);
+    }, [refreshPlanningEntitiesInBackground]);
     const createWorkstream = useCallback(async (payload) => {
         const res = await fetch('/api/taskforce/workstream', {
             method: 'POST',

package/dist/hooks/workspace/workspaceLocalState.d.ts

@@ -1,5 +1,11 @@
 import type { TaskAssignee } from '../../types';
 import type { TaskSortKey } from '../../utils/taxonomySorting.js';
+export interface FilterTaxonomySignature {
+    categories: string[];
+    types: string[];
+    priorities: string[];
+    taxonomies: Record<string, string[]>;
+}
 export interface PersistedUiState {
     groupBy?: 'category' | 'type' | 'priority' | 'approach' | 'assignee' | 'status' | 'complexity' | 'schedule' | 'docs';
     activeWorkspaceModule?: 'tasks' | 'docs' | 'annotate' | 'workflows' | 'agents';
@@ -13,6 +19,7 @@ export interface PersistedUiState {
     filterAssignees?: TaskAssignee[];
     filterAssigneesAllSelected?: boolean;
     filterTaxonomies?: Record<string, (string | number)[]>;
+    filterTaxonomySignature?: FilterTaxonomySignature;
     sortBy?: TaskSortKey;
     sortOrder?: 'asc' | 'desc';
     hasInitedFilters?: boolean;
@@ -28,6 +35,24 @@ type RemoteUiStatePersistResult = {
     response?: Response;
     payload?: any;
 };
+export declare function buildFilterTaxonomySignature(input: {
+    categories: Array<{
+        value?: unknown;
+    }>;
+    types: Array<{
+        value?: unknown;
+    }>;
+    priorities: Array<{
+        value?: unknown;
+    }>;
+    taxonomies?: Array<{
+        id?: unknown;
+        options?: Array<{
+            value?: unknown;
+        }>;
+    }>;
+}): FilterTaxonomySignature | null;
+export declare function areFilterTaxonomySignaturesEqual(left: FilterTaxonomySignature | null | undefined, right: FilterTaxonomySignature | null | undefined): boolean;
 export declare function generateClientUuid(): string;
 export declare function logBootstrapDebug(event: string, details?: Record<string, unknown>): void;
 export declare function resetRemoteUiStatePersistCache(): void;

package/dist/hooks/workspace/workspaceLocalState.js

@@ -4,6 +4,44 @@ const APP_UI_STATE_STORAGE_KEY_PREFIX = 'taskforce.uiState.app.v1';
 const BOOTSTRAP_DEBUG_LOG_KEY = 'taskforce.bootstrapDebug.v1';
 const REMOTE_UI_STATE_FAILURE_RETRY_MS = 5000;
 const remoteUiStatePersistCache = new Map();
+function normalizeSignatureValues(values) {
+    return Array.from(new Set(values
+        .map((value) => String(value ?? '').trim())
+        .filter((value) => value.length > 0))).sort();
+}
+export function buildFilterTaxonomySignature(input) {
+    const categories = normalizeSignatureValues(input.categories.map((category) => category.value));
+    const types = normalizeSignatureValues(input.types.map((type) => type.value));
+    const priorities = normalizeSignatureValues(input.priorities.map((priority) => priority.value));
+    if (categories.length === 0 || types.length === 0 || priorities.length === 0)
+        return null;
+    const taxonomies = {};
+    (input.taxonomies || []).forEach((taxonomy) => {
+        const id = String(taxonomy.id ?? '').trim();
+        if (!id)
+            return;
+        taxonomies[id] = normalizeSignatureValues((taxonomy.options || []).map((option) => option.value));
+    });
+    return { categories, types, priorities, taxonomies };
+}
+function haveSameStringValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+export function areFilterTaxonomySignaturesEqual(left, right) {
+    if (!left || !right)
+        return false;
+    if (!haveSameStringValues(left.categories || [], right.categories || []))
+        return false;
+    if (!haveSameStringValues(left.types || [], right.types || []))
+        return false;
+    if (!haveSameStringValues(left.priorities || [], right.priorities || []))
+        return false;
+    const leftTaxonomyKeys = Object.keys(left.taxonomies || {}).sort();
+    const rightTaxonomyKeys = Object.keys(right.taxonomies || {}).sort();
+    if (!haveSameStringValues(leftTaxonomyKeys, rightTaxonomyKeys))
+        return false;
+    return leftTaxonomyKeys.every((key) => (haveSameStringValues(left.taxonomies[key] || [], right.taxonomies[key] || [])));
+}
 export function generateClientUuid() {
     if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
         return crypto.randomUUID();

package/dist/mcp/adminWorkspaceRegistrar.js

@@ -66,16 +66,6 @@ export function registerAdminWorkspaceTools(registerTool, executeTool) {
             required: ['types'],
         },
     }));
-    register('bulk_update_type', (context) => ({
-        description: context.describeTool('Bulk-update tasks from one task type to another. Use get_config first to confirm the current valid type values.'),
-        inputSchema: {
-            properties: {
-                fromType: stringProperty('Current task type value to replace.', context.typeEnum),
-                toType: stringProperty('Replacement task type value.', context.typeEnum),
-            },
-            required: ['fromType', 'toType'],
-        },
-    }));
     register('bulk_update_fields', (context) => ({
         description: context.describeTool('Apply field updates to multiple tasks in one request. Use get_config first to confirm valid taxonomy values before calling this tool.'),
         inputSchema: {

package/dist/mcp/clientIntegrations.d.ts

@@ -1,5 +1,5 @@
 import { type AiProfileBootstrapConfig } from './aiProfileBootstrap.js';
-export type McpClientId = 'general' | 'cursor' | 'cline' | 'vscode' | 'windsurf' | 'antigravity' | 'openclaw' | 'codex' | 'claude-code' | 'gemini-cli' | 'claude-desktop' | 'chatgpt-desktop';
+export type McpClientId = 'general' | 'cursor' | 'cline' | 'vscode' | 'kiro' | 'windsurf' | 'antigravity' | 'openclaw' | 'codex' | 'grok' | 'claude-code' | 'gemini-cli' | 'claude-desktop' | 'chatgpt-desktop';
 export interface McpClientOption {
     id: McpClientId;
     label: string;

package/dist/mcp/clientIntegrations.js

@@ -4,10 +4,12 @@ const LOCAL_AI_PROFILE_DEFAULTS = {
     cursor: { name: 'Cursor', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cursor', model: 'Cursor', surfaceType: 'ide' },
     cline: { name: 'Cline', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cline', model: 'Cline', surfaceType: 'ide' },
     vscode: { name: 'VS Code Copilot', icon: 'Bot', role: 'IDE coding assistant', provider: 'Microsoft', model: 'Copilot', surfaceType: 'ide' },
+    kiro: { name: 'Kiro', icon: 'Bot', role: 'IDE coding assistant', provider: 'Amazon', model: 'Kiro', surfaceType: 'ide' },
     windsurf: { name: 'Windsurf', icon: 'Bot', role: 'IDE coding assistant', provider: 'Windsurf', model: 'Windsurf', surfaceType: 'ide' },
     antigravity: { name: 'Antigravity', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Antigravity', surfaceType: 'coding_tool' },
     openclaw: { name: 'OpenClaw', icon: 'Bot', role: 'AI agent', provider: 'OpenClaw', model: 'OpenClaw', surfaceType: 'agent' },
     codex: { name: 'Codex', icon: 'Bot', role: 'Coding agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'cli' },
+    grok: { name: 'Grok CLI', icon: 'Bot', role: 'Coding agent', provider: 'xAI', model: 'Grok CLI', surfaceType: 'cli' },
     'claude-code': { name: 'Claude Code', icon: 'Bot', role: 'Coding agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'cli' },
     'gemini-cli': { name: 'Gemini CLI', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Gemini CLI', surfaceType: 'cli' },
     'claude-desktop': { name: 'Claude Desktop', icon: 'Bot', role: 'Desktop AI collaborator', provider: 'Anthropic', model: 'Claude Desktop', surfaceType: 'chat_app' },
@@ -32,6 +34,8 @@ export const MCP_CLIENT_OPTIONS = [
     { id: 'codex', label: 'Codex' },
     { id: 'cursor', label: 'Cursor' },
     { id: 'gemini-cli', label: 'Gemini CLI' },
+    { id: 'grok', label: 'Grok CLI' },
+    { id: 'kiro', label: 'Kiro' },
     { id: 'openclaw', label: 'OpenClaw' },
     { id: 'vscode', label: 'VS Code / Copilot' },
     { id: 'windsurf', label: 'Windsurf' },
@@ -149,6 +153,18 @@ export function buildCloudMcpClientIntegration(input) {
                 instructionLabel: 'VS Code Configuration Instructions',
                 instructionText: buildConfigurationInstruction('Open .vscode/mcp.json or MCP: Open User Configuration and add this server under the servers object.')
             };
+        case 'kiro':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: {
+                    url: endpoint,
+                    headers
+                },
+                instructionLabel: 'Kiro Configuration Instructions',
+                instructionText: buildConfigurationInstruction('Open .kiro/settings/mcp.json in your workspace (or ~/.kiro/settings/mcp.json for user-level config) and add this server under mcpServers.')
+            };
         case 'windsurf':
             return {
                 clientId,
@@ -199,6 +215,18 @@ export function buildCloudMcpClientIntegration(input) {
                 instructionLabel: 'Codex Configuration Instructions',
                 instructionText: buildConfigurationInstruction('Open ~/.codex/config.toml and add this Codex MCP entry.')
             };
+        case 'grok':
+            return {
+                clientId,
+                kind: 'text',
+                renderedText: [
+                    `[mcp_servers.${serverId}]`,
+                    `url = "${endpoint}"`,
+                    `headers = { ${Object.entries(headers).map(([key, value]) => `${key} = "${value}"`).join(', ')} }`
+                ].join('\n'),
+                instructionLabel: 'Grok CLI Configuration Instructions',
+                instructionText: buildConfigurationInstruction('Open ~/.grok/config.toml (or .grok/config.toml in your project for project-scoped config) and add this Grok CLI MCP entry.')
+            };
         case 'claude-code':
             return {
                 clientId,
@@ -288,6 +316,15 @@ export function buildLocalMcpClientIntegration(input) {
                 instructionLabel: 'VS Code Configuration Instructions',
                 instructionText: buildLocalConfigurationInstruction('Open .vscode/mcp.json or MCP: Open User Configuration and add this server under the servers object.')
             };
+        case 'kiro':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Kiro Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open .kiro/settings/mcp.json in your workspace (or ~/.kiro/settings/mcp.json for user-level config) and add this server under mcpServers.')
+            };
         case 'windsurf':
             return {
                 clientId,
@@ -332,6 +369,19 @@ export function buildLocalMcpClientIntegration(input) {
                 instructionLabel: 'Codex Configuration Instructions',
                 instructionText: buildLocalConfigurationInstruction('Open ~/.codex/config.toml and add this local MCP entry.')
             };
+        case 'grok':
+            return {
+                clientId,
+                kind: 'text',
+                renderedText: [
+                    `[mcp_servers.${serverId}]`,
+                    `command = ${formatTomlString(serverConfig.command)}`,
+                    `args = ${formatTomlArray(serverConfig.args)}`,
+                    ...buildTomlEnvAssignment(serverConfig.env)
+                ].join('\n'),
+                instructionLabel: 'Grok CLI Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open ~/.grok/config.toml (or .grok/config.toml in your project for project-scoped config) and add this local Grok CLI MCP entry.')
+            };
         case 'claude-code':
             return {
                 clientId,

package/dist/mcp/clientProfileDefaults.js

@@ -16,8 +16,12 @@ export function getDefaultAiProfileMetadataForClient(clientId) {
             return { icon: 'MessageSquareMore', color: '#d97706', description: 'Claude Desktop connected through the Taskforce MCP connector.', role: 'AI Assistant', provider: 'Anthropic', model: 'Claude', surfaceType: 'chat_app' };
         case 'gemini-cli':
             return { icon: 'Gem', color: '#2563eb', description: 'Gemini CLI coding agent connected through MCP.', role: 'CLI Coding Agent', provider: 'Google', model: 'Gemini', surfaceType: 'cli' };
+        case 'grok':
+            return { icon: 'Sparkles', color: '#111827', description: 'Grok CLI coding agent connected through MCP.', role: 'CLI Coding Agent', provider: 'xAI', model: 'Grok CLI', surfaceType: 'cli' };
         case 'vscode':
             return { icon: 'Code2', color: '#2563eb', description: 'VS Code MCP-connected coding agent.', role: 'Coding Agent', provider: null, model: null, surfaceType: 'ide' };
+        case 'kiro':
+            return { icon: 'Bot', color: '#7c3aed', description: 'Kiro IDE-connected AI assistant.', role: 'IDE coding assistant', provider: 'Amazon', model: null, surfaceType: 'ide' };
         case 'cline':
         case 'windsurf':
         case 'antigravity':

package/dist/mcp/collaborationRegistrar.js

@@ -23,11 +23,11 @@ export function registerCollaborationTools(registerTool, executeTool) {
         });
     };
     register('list_assignees', (context) => ({
-        description: context.describeTool('List eligible assignees for the active workspace. Returns human workspace members and AI profiles that can own tasks. Use this before create_task, update_task, assign_task, or bulk_assign_tasks when you need a valid assignee ID.'),
+        description: context.describeTool('List eligible assignees for the active workspace. Returns human workspace members and AI profiles that can own tasks. Use this before create_task, update_task, or bulk_update_fields when you need a valid assignee ID.'),
         inputSchema: { properties: {} },
     }));
     register('get_current_profile', (context) => ({
-        description: context.describeTool('Inspect the effective AI profile for this session. Use this when an agent needs to know its current profile id before filtering for tasks assigned to itself. If no profile is currently bound, this tool explains how to bootstrap with resolve_profile. You may also pass your own profileToken to inspect a stateless AI profile without mutating session state. The response includes your profileToken only for private agent/client storage; do not write it to repos, task comments, task attachments, logs, generated docs, or shared output.'),
+        description: context.describeTool('Inspect current AI identity for this call (ambient session, connection bootstrap, or explicit profileToken). Returns identityBound (true if this invocation has a resolved identity), bindingSource, profile, taskFilter, suggestedArgs, and guidance. Stateless/scheduled agents: call with profileToken if no ambient bind; use the returned suggestedArgs (with assignee) for list_tasks and pass profileToken on writes. Call before mutating or to decide on resolve_profile.'),
         inputSchema: {
             properties: {
                 profileToken: stringProperty('Optional AI profile token to inspect when no profile is currently bound in session state. Pass only a token previously issued to this AI identity.'),
@@ -35,7 +35,7 @@ export function registerCollaborationTools(registerTool, executeTool) {
         },
     }));
     register('resolve_profile', (context) => ({
-        description: context.describeTool('Resolve or create the current AI collaborator profile for this workspace. On first bootstrap, omit profileToken and Taskforce will create a named AI profile, issue a stable profileToken, and return the profile id to use in assignee, createdBy, and comment author fields on later calls. Store the returned profileToken only in private agent/client state and include it on future mutating calls when your MCP client does not preserve session identity. Never write profileToken values to repos, task comments, task attachments, logs, generated docs, or shared output. When a valid profileToken is provided, Taskforce resolves the existing profile and updates any supplied presentation fields such as name, icon, color, description, role, provider, model, and surfaceType. Update semantics: omitted optional fields leave existing stored values unchanged. For description, role, provider, and model, empty strings are ignored rather than clearing. For surfaceType, null or an empty string clears the stored value; valid enum values replace it.'),
+        description: context.describeTool('Resolve or create this AI collaborator profile. For stateless agents (no ambient binding): call with name + surfaceType (and profileToken to re-use); the response includes created, profileToken, profile, *plus* identityBound, bindingSource, taskFilter, suggestedArgs, nextTool, guidance. Store profileToken privately only. Use suggestedArgs for list_tasks; pass profileToken on mutating calls. Never write profileToken to repos, tasks, logs, or docs.'),
         inputSchema: {
             properties: {
                 name: stringProperty('Display name for the AI collaborator.'),

package/dist/mcp/documentAssetRegistrar.js

@@ -31,44 +31,27 @@ 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.'),
-            },
-        },
-    }));
-    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.'),
-        inputSchema: {
-            properties: {
-                taskId: stringProperty('Task ID or task reference such as T-123.'),
-                attachmentId: stringProperty('Attachment descriptor id from get_task_attachments.'),
+                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.'),
             },
-            required: ['taskId', 'attachmentId'],
         },
     }));
     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.'),
+        description: context.describeTool('List attachment descriptors for one workstream. Pass attachmentId when you need one attachment body or download reference.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-            },
-            required: ['id'],
-        },
-    }));
-    register('read_workstream_attachment', (context) => ({
-        description: context.describeTool('Read one workstream attachment by attachmentId. Prefer this tool over opening attachment path URLs directly.'),
-        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']),
+                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.'),
             },
-            required: ['workstreamId', 'attachmentId'],
+            required: ['id'],
         },
     }));
     register('save_workstream_attachment', (context) => ({
@@ -96,24 +79,15 @@ 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.'),
-            },
-            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']),
+                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.'),
             },
-            required: ['initiativeId', 'attachmentId'],
+            required: ['id'],
         },
     }));
     register('save_initiative_attachment', (context) => ({
@@ -151,7 +125,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 +134,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 +144,26 @@ 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.'),
+        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.'),
         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.'),
-        inputSchema: {
-            properties: {
-                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.'),
             },
-            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('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: {
                 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: ['imageId'],
-        },
-    }));
-    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.'),
-        inputSchema: {
-            properties: {
-                sessionId: stringProperty('Annotated attachment session id.'),
-            },
-            required: ['sessionId'],
         },
     }));
     register('create_annotated_attachment_session', (context) => ({
@@ -320,22 +280,14 @@ 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 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.'),
         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: {
+                id: stringProperty('Alias for documentId. Document asset id or document reference such as D-123.'),
                 sessionId: stringProperty('Document review session id.'),
             },
-            required: ['sessionId'],
         },
     }));
     register('create_document_review_session', (context) => ({