fix(mothership): clarify tool permissions and folder context

Author: Sg312

apps/docs/openapi-v2-workflows.json

@@ -8069,12 +8069,12 @@
           "usageControl": {
             "type": "string",
             "enum": ["auto", "force", "none"],
-            "description": "When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`."
+            "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`."
           },
           "usageControlExpression": {
             "type": "string",
             "maxLength": 2048,
-            "description": "Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time."
+            "description": "Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`."
           },
           "params": {
             "type": "object",
@@ -8121,12 +8121,12 @@
               "usageControl": {
                 "type": "string",
                 "enum": ["auto", "force", "none"],
-                "description": "When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`."
+                "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`."
               },
               "usageControlExpression": {
                 "type": "string",
                 "maxLength": 2048,
-                "description": "Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time."
+                "description": "Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`."
               }
             },
             "required": ["type", "customToolId"],
@@ -8194,12 +8194,12 @@
               "usageControl": {
                 "type": "string",
                 "enum": ["auto", "force", "none"],
-                "description": "When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`."
+                "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`."
               },
               "usageControlExpression": {
                 "type": "string",
                 "maxLength": 2048,
-                "description": "Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time."
+                "description": "Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`."
               }
             },
             "required": ["type", "schema", "code"],
@@ -8264,12 +8264,12 @@
           "usageControl": {
             "type": "string",
             "enum": ["auto", "force", "none"],
-            "description": "When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`."
+            "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`."
           },
           "usageControlExpression": {
             "type": "string",
             "maxLength": 2048,
-            "description": "Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time."
+            "description": "Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`."
           }
         },
         "required": ["type", "params"],
@@ -8377,12 +8377,12 @@
           "usageControl": {
             "type": "string",
             "enum": ["auto", "force", "none"],
-            "description": "When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`."
+            "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`."
           },
           "usageControlExpression": {
             "type": "string",
             "maxLength": 2048,
-            "description": "Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time."
+            "description": "Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`."
           }
         },
         "required": ["type", "params"],

apps/sim/lib/api/contracts/v2/workflows.ts

@@ -3026,14 +3026,14 @@ const WORKFLOW_OPERATION_PARAM_ENVELOPE =
 const v2AgentToolUsageControlSchema = z
   .enum(['auto', 'force', 'none'])
   .describe(
-    'When the Agent may call the tool: `auto` lets the model decide, `force` requires a call, and `none` disables it. Omitted means `auto`.'
+    'Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`.'
   )
 
 const v2AgentToolUsageControlExpressionSchema = z
   .string()
   .max(2048, 'Agent tool mode expression must be at most 2048 characters')
   .describe(
-    'Variable-capable tool mode value used when the matching canonical mode is `advanced`. It must resolve to `auto`, `force`, or `none` at execution time.'
+    'Variable Permission Mode: a reference such as `<start.toolMode>` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`.'
   )
 
 const v2AgentToolParamsSchema = z

apps/sim/lib/mothership/chat/process-contents.test.ts

@@ -193,14 +193,17 @@ describe('processContextsServer - workflow references', () => {
         { id: 'folder-1', name: 'Leads / new', parentId: 'root' },
       ],
     })
-    expect(
-      await resolveActiveResourceContext('folder', 'folder-1', 'workspace-1', 'reader')
-    ).toMatchObject({
-      type: 'active_resource',
-      content: JSON.stringify({
-        resourceType: 'workflow',
-        folderPath: '/Sales%20team/Leads%20%2F%20new',
-      }),
+    const context = await resolveActiveResourceContext(
+      'folder',
+      'folder-1',
+      'workspace-1',
+      'reader'
+    )
+    expect(context?.type).toBe('active_resource')
+    expect(JSON.parse(context!.content)).toEqual({
+      resourceType: 'workflow',
+      folderPath: '/Sales%20team/Leads%20%2F%20new',
+      discovery: expect.stringContaining('including descendants'),
     })
     expect(listWorkflowFolders).toHaveBeenCalledWith({
       principal: expect.objectContaining({ subjectUserId: 'reader', workspaceId: 'workspace-1' }),
@@ -911,13 +914,16 @@ describe('file folder context', () => {
 
   it('uses the CLI folder path while preserving literal slashes inside folder names', async () => {
     resolveFileFolderPath.mockResolvedValueOnce({ path: 'Reports/Client \\/ notes' })
-    expect(await resolveActiveResourceContext('filefolder', 'folder-1', 'ws-1', 'reader')).toEqual({
+    const context = await resolveActiveResourceContext('filefolder', 'folder-1', 'ws-1', 'reader')
+    expect(context).toEqual({
       type: 'active_resource',
       tag: '@active_resource',
-      content: JSON.stringify({
-        resourceType: 'file',
-        folderPath: '/Reports/Client%20%2F%20notes',
-      }),
+      content: expect.any(String),
+    })
+    expect(JSON.parse(context!.content)).toEqual({
+      resourceType: 'file',
+      folderPath: '/Reports/Client%20%2F%20notes',
+      discovery: expect.stringContaining('including descendants'),
     })
     expect(resolveFileFolderPath).toHaveBeenCalledWith({
       principal: expect.objectContaining({ subjectUserId: 'reader', workspaceId: 'ws-1' }),
@@ -1549,9 +1555,11 @@ describe('folder and foldered-resource chat pointers', () => {
         'user-1',
         'chat-1'
       )
-      const content = JSON.stringify({
+      const content = mention.content
+      expect(JSON.parse(content)).toMatchObject({
         resourceType: _kind === 'knowledge' ? 'knowledge_base' : _kind,
         folderPath: '/Finance%2FLegal/Q4%20100%25',
+        discovery: expect.stringContaining('including descendants'),
       })
       expect(mention).toMatchObject({ type: context.kind, tag: '@Chosen folder', content })
       expect(mention.path).toBeUndefined()
@@ -1586,7 +1594,7 @@ describe('folder and foldered-resource chat pointers', () => {
       'chat-1'
     )
     expect(result.path).toBeUndefined()
-    expect(JSON.parse(result.content)).toEqual({
+    expect(JSON.parse(result.content)).toMatchObject({
       resourceType: 'file',
       folderPath: '/Finance%2FLegal/Q4%20100%25',
     })
@@ -1606,6 +1614,27 @@ describe('folder and foldered-resource chat pointers', () => {
     })
   })
 
+  it('keeps literal special characters scoped and explains descendant discovery', async () => {
+    listTableFolders.mockResolvedValue({
+      folders: [
+        { id: 'selected', name: 'Reports[*]?', parentId: null },
+        { id: 'sibling', name: 'Reports-other', parentId: null },
+      ],
+    })
+    const [context] = await processContextsServer(
+      [{ kind: 'folder', folderId: 'selected', label: 'Reports' }],
+      'user-1',
+      'inspect',
+      'ws-1'
+    )
+    const content = JSON.parse(context.content)
+    expect(content.folderPath).toBe('/Reports%5B*%5D%3F')
+    expect(content.discovery).toContain('literal path, not a glob')
+    expect(content.discovery).toContain('follow pagination and descendant folders')
+    expect(content.discovery).toContain('An empty folder has no contents')
+    expect(context.content).not.toContain('Reports-other')
+  })
+
   it('shares folder reads within a turn and re-resolves moves on the next turn', async () => {
     listTableFolders.mockResolvedValue({ folders: nestedFolders })
     const contexts: ChatContext[] = [
@@ -1618,7 +1647,10 @@ describe('folder and foldered-resource chat pointers', () => {
       folders: [{ id: 'child', name: 'Moved', parentId: null }],
     })
     const [result] = await processContextsServer([contexts[1]], 'user-1', '', 'ws-1')
-    expect(JSON.parse(result.content)).toEqual({ resourceType: 'table', folderPath: '/Moved' })
+    expect(JSON.parse(result.content)).toMatchObject({
+      resourceType: 'table',
+      folderPath: '/Moved',
+    })
     expect(listTableFolders).toHaveBeenCalledTimes(2)
   })
 
@@ -1631,7 +1663,7 @@ describe('folder and foldered-resource chat pointers', () => {
       '',
       'ws-1'
     )
-    expect(JSON.parse(result.content)).toEqual({
+    expect(JSON.parse(result.content)).toMatchObject({
       resourceType: 'table',
       folderPath: '/Finance%2FLegal/Q4%20100%25',
     })

apps/sim/lib/mothership/chat/process-contents.ts

@@ -845,7 +845,12 @@ function folderReferenceContent(pointer: string): string {
   }
   const resourceType = resourceTypes[root]
   if (!resourceType) throw new Error('Unsupported folder resource domain')
-  return JSON.stringify({ resourceType, folderPath: pointer.slice(separator) })
+  return JSON.stringify({
+    resourceType,
+    folderPath: pointer.slice(separator),
+    discovery:
+      "This attachment refers to the contents of this exact folder, including descendants. Use the domain's CLI folder/resource listing with this literal path, not a glob; follow pagination and descendant folders, then read relevant resources. An empty folder has no contents; do not substitute a similarly named folder.",
+  })
 }
 
 async function resolveTableResource(