feat(mothership): support dynamic Sim Chat tool modes

Author: Sg312

apps/sim/app/api/mothership/execute/route.test.ts

@@ -424,6 +424,7 @@ describe('mothership private trace provenance transport', () => {
           mcpTools: [
             {
               type: 'mcp',
+              usageControl: 'force',
               params: { serverId: 'mcp-cg-123456789012345678901', toolName: 'search_transcripts' },
             },
             {
@@ -459,6 +460,7 @@ describe('mothership private trace provenance transport', () => {
       integrationCatalog: {
         mcpServerIds: ['123'],
         mcpToolIds: ['mcp-cg-123456789012345678901-search_transcripts'],
+        requiredToolIds: ['mcp-cg-123456789012345678901-search_transcripts'],
         mcpExecution: {
           workflowId: 'workflow-1',
           executionId: 'execution-1',

apps/sim/app/api/mothership/execute/route.ts

@@ -253,6 +253,12 @@ export const POST = withRouteHandler(async (req: NextRequest) => {
         const { serverId, toolName } = resolveMcpToolBinding(tool)
         return createMcpToolId(serverId, toolName)
       })
+    const requiredToolIds = (mcpTools ?? [])
+      .filter((tool) => tool.usageControl === 'force')
+      .map((tool) => {
+        const { serverId, toolName } = resolveMcpToolBinding(tool)
+        return createMcpToolId(serverId, toolName)
+      })
     const agentContexts = await processContextsServer(
       nonMcpAgentMentions,
       userId,
@@ -306,6 +312,7 @@ export const POST = withRouteHandler(async (req: NextRequest) => {
       integrationCatalog: {
         mcpServerIds: taggedMcpServerIds,
         mcpToolIds: selectedMcpToolIds,
+        ...(requiredToolIds.length ? { requiredToolIds: [...new Set(requiredToolIds)] } : {}),
         mcpExecution: IntegrationCatalogMcpExecution.parse({
           workflowId: delegation.workflowId,
           executionId: delegation.executionId,

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/tool-input/tool-input.tsx

@@ -599,8 +599,9 @@ export const ToolInput = memo(function ToolInput({
   const modelValue = useSubBlockStore((state) => state.getValue(blockId, 'model'))
   const model = typeof modelValue === 'string' ? modelValue : ''
   const provider = model ? getProviderFromModel(model) : ''
-  const supportsToolControl = provider ? supportsToolUsageControl(provider) : false
-  const supportsForce = supportsForcedToolUse(model)
+  const supportsToolControl =
+    blockType === 'mothership' || (provider ? supportsToolUsageControl(provider) : false)
+  const supportsForce = blockType === 'mothership' || supportsForcedToolUse(model)
 
   const {
     filterBlocks,

apps/sim/executor/handlers/mothership/mothership-handler.test.ts

@@ -956,6 +956,78 @@ describe('MothershipBlockHandler', () => {
     })
   })
 
+  it.each(['auto', 'force', 'none'])(
+    'resolves variable MCP permission mode %s before discovery and execution',
+    async (mode) => {
+      fetchMock.mockResolvedValue(createJsonResponse({ content: 'done', toolCalls: [] }))
+      block.canonicalModes = { '0:agentToolUsageControl': 'advanced' }
+      await handler.execute(context, block, {
+        prompt: 'Use my tools',
+        tools: [
+          {
+            type: 'mcp',
+            usageControl: 'auto',
+            usageControlExpression: ` ${mode.toUpperCase()} `,
+            params: { serverId: 'mcp-server-1', toolName: 'search' },
+          },
+        ],
+      })
+      const body = JSON.parse(String(fetchMock.mock.calls[0][1].body))
+      expect(body.mcpTools).toEqual(
+        mode === 'none'
+          ? undefined
+          : [
+              {
+                type: 'mcp',
+                usageControl: mode,
+                params: { serverId: 'mcp-server-1', toolName: 'search' },
+              },
+            ]
+      )
+    }
+  )
+
+  it('does not discover an advanced MCP server disabled by a variable', async () => {
+    fetchMock.mockResolvedValue(createJsonResponse({ content: 'done', toolCalls: [] }))
+    mockDiscoverMcpServerToolsAsExecutor.mockClear()
+    block.canonicalModes = { '0:agentToolUsageControl': 'advanced' }
+    await handler.execute(context, block, {
+      prompt: 'No tools',
+      tools: [
+        {
+          type: 'mcp-server-advanced',
+          usageControl: 'force',
+          usageControlExpression: 'none',
+          params: { serverId: 'mcp-server-1' },
+        },
+      ],
+    })
+    expect(mockDiscoverMcpServerToolsAsExecutor).not.toHaveBeenCalled()
+    expect(JSON.parse(String(fetchMock.mock.calls[0][1].body))).not.toHaveProperty('mcpTools')
+  })
+
+  it.each(['', 'sometimes', '<start.unresolved>', null])(
+    'rejects an invalid variable mode before making requests: %s',
+    async (mode) => {
+      block.canonicalModes = { '0:agentToolUsageControl': 'advanced' }
+      mockDiscoverMcpServerToolsAsExecutor.mockClear()
+      await expect(
+        handler.execute(context, block, {
+          prompt: 'Use tools',
+          tools: [
+            {
+              type: 'mcp-server-advanced',
+              usageControlExpression: mode,
+              params: { serverId: 'mcp-server-1' },
+            },
+          ],
+        })
+      ).rejects.toThrow('mode must resolve to Auto, Force, or None')
+      expect(fetchMock).not.toHaveBeenCalled()
+      expect(mockDiscoverMcpServerToolsAsExecutor).not.toHaveBeenCalled()
+    }
+  )
+
   it('forwards only enabled MCP tools and selected skills', async () => {
     mockGenerateId
       .mockReturnValueOnce('chat-uuid')
@@ -1248,6 +1320,7 @@ describe('MothershipBlockHandler', () => {
     expect(body.mcpTools).toEqual([
       {
         type: 'mcp',
+        usageControl: 'auto',
         schema: {
           type: 'object',
           description: 'Search {{MCP_SCHEMA_DESCRIPTION}} for Box',
@@ -1681,6 +1754,7 @@ describe('MothershipBlockHandler', () => {
     expect(body.mcpTools).toHaveLength(5)
     expect(body.mcpTools[0]).toEqual({
       type: 'mcp',
+      usageControl: 'auto',
       params: { serverId: secret, toolName: 'search' },
     })
     expect(body.mcpTools[2].schema).toEqual({ type: 'string', enum: [secret] })

apps/sim/executor/handlers/mothership/mothership-handler.ts

@@ -37,6 +37,7 @@ import {
   type RawFileInput,
 } from '@/lib/uploads/utils/file-utils'
 import { selectModelBoundFileInputPaths } from '@/lib/uploads/utils/model-input'
+import { resolveAgentToolUsageControl } from '@/lib/workflows/tool-input/usage-control'
 import type { BlockOutput } from '@/blocks/types'
 import { normalizeFileInput } from '@/blocks/utils'
 import { BlockType } from '@/executor/constants'
@@ -890,13 +891,24 @@ export class MothershipBlockHandler implements BlockHandler {
     if (!prompt || typeof prompt !== 'string') {
       throw new Error('Prompt input is required')
     }
-    const metadataInputPaths = selectMothershipMetadataModelInputPaths(inputs.tools, requestSkills)
+    const requestTools = Array.isArray(inputs.tools)
+      ? inputs.tools.map((tool: unknown, index: number) => {
+          if (!isPlainRecord(tool)) throw new Error(`Tool ${index + 1} must be a tool binding.`)
+          const usageControl = resolveAgentToolUsageControl(tool, index, block.canonicalModes)
+          if (!usageControl)
+            throw new Error(
+              `Tool ${index + 1} mode must resolve to Auto, Force, or None before Sim Chat can run.`
+            )
+          return { ...tool, usageControl }
+        })
+      : inputs.tools
+    const metadataInputPaths = selectMothershipMetadataModelInputPaths(requestTools, requestSkills)
     if (ctx.resolvedSecretTraceRegistry) {
       assertMothershipStructuralInputsDoNotResolveSecrets(
         ctx.resolvedSecretTraceRegistry,
         metadataInputPaths.structuralInputPaths
       )
-      assertMothershipToolSchemaProjectionsAreSafe(ctx.resolvedSecretTraceRegistry, inputs.tools)
+      assertMothershipToolSchemaProjectionsAreSafe(ctx.resolvedSecretTraceRegistry, requestTools)
     }
     const modelInputPaths: ResolvedSecretInputPath[] = [
       ['prompt'],
@@ -909,7 +921,7 @@ export class MothershipBlockHandler implements BlockHandler {
     ]
     const modelInputProjection = projectResolvedModelInput(
       sourceRegistry,
-      { prompt, files: inputs.files, tools: inputs.tools, skills: requestSkills },
+      { prompt, files: inputs.files, tools: requestTools, skills: requestSkills },
       modelInputPaths
     )
     if (!modelInputProjection.complete || typeof modelInputProjection.value.prompt !== 'string') {

apps/sim/lib/mothership/agent-cli/curation.test.ts

@@ -106,6 +106,8 @@ describe('curateBlockDetail', () => {
         type: 'array',
         items: { anyOf: expect.any(Array) },
       })
+      expect(JSON.stringify(field?.valueSchema)).toContain('usageControlExpression')
+      expect(JSON.stringify(field?.valueSchema)).toContain('force')
       expect(field?.toolBinding?.selectionMode).toBe(id === 'agent' ? 'explicit' : 'additive')
       expect(field?.toolBinding?.naming).toContain(
         id === 'agent' ? 'operations[operation].toolId' : 'call_integration_tool'

apps/sim/lib/mothership/agent-cli/tool-binding-hints.ts

@@ -34,7 +34,7 @@ export function withToolBindingHints(detail: MothershipBlockDetail): MothershipB
                 ? 'Use the exact MCP toolName returned by discovery. Sim Chat discovers the callable toolId and invokes it through call_integration_tool. An attachment title/name cannot rename the operation.'
                 : 'Integration operations use operations[operation].toolId from blocks get (not the UI toolName/title). Custom tools use custom_ followed by the saved definition title or inline title. MCP tools use a server-qualified ID derived from the discovered toolName. Duplicate bindings receive provider-generated suffixes. Do not override title, name, toolId or functionName when attaching a saved tool. Inline custom definitions require title = schema.function.name.',
               access: isMothership
-                ? 'Selections add MCP operations to available integration access; this is not an integration allowlist. Empty tools does not disable integrations. Fixed MCP arguments, force mode and variable permission mode are not supported by this block. Actual calls remain subject to execution permissions and MCP policies.'
+                ? 'Selections add MCP operations to available integration access; this is not an integration allowlist. Empty tools does not disable integrations. Fixed MCP arguments are not supported. Each selection supports usageControl (auto/force/none) or usageControlExpression resolving to those values. Send only the chosen property; Sim selects its mode. none removes the selection from discovery and execution; force requires an invocation of each selected operation before completion. These controls do not disable ambient integrations. Actual calls remain subject to execution permissions and MCP policies.'
                 : 'This array defines the selected tools, subject to execution permissions. For integration, inline custom and individual MCP bindings, params fixes author-supplied values; remaining eligible parameters are model-supplied. Saved custom-tool references do not retain fixed arguments. auto lets the model choose, force requires a call, none disables the binding. Runtime helpers such as skill loading are separate. Labels do not enforce approvals or permissions.',
             },
           }

apps/sim/lib/mothership/generated/integration-catalog.ts

@@ -28,6 +28,8 @@ export type IntegrationCatalogMcpExecution = z.infer<typeof IntegrationCatalogMc
 export const IntegrationCatalogContext = z.object({
   mcpServerIds: z.array(z.string().min(1)).default([]),
   mcpToolIds: z.array(z.string().min(1)).optional(),
+  /** Resolved workflow selections that must be invoked before completion; no schemas. */
+  requiredToolIds: z.array(z.string().min(1)).optional(),
   mcpExecution: IntegrationCatalogMcpExecution.optional(),
 });
 export type IntegrationCatalogContext = z.infer<typeof IntegrationCatalogContext>;

apps/sim/lib/mothership/integrations/application/catalog.test.ts

@@ -283,26 +283,32 @@ describe('catalog authorization', () => {
   })
 })
 
-it('exposes selected MCP operations without enabling sibling operations', async () => {
-  queueChat('agent')
-  mocks.target.mockResolvedValue({ workspaceId: 'workspace-1' })
-  mocks.mcp.mockResolvedValue([
-    { name: 'mcp-abc-read', service: 'mcp:mcp-abc', description: 'Read', input_schema: {} },
-    { name: 'mcp-abc-write', service: 'mcp:mcp-abc', description: 'Write', input_schema: {} },
-  ])
-  const result = await readIntegrationCatalog.execute({
-    principal: principal(),
-    input: {
-      ...input,
-      mode: 'agent',
-      workspaceId: 'workspace-1',
-      mcpToolIds: ['mcp-abc-read'],
-      service: 'mcp:mcp-abc',
-    },
-  })
-  expect(mocks.mcp).toHaveBeenCalledWith('actor', 'workspace-1', ['mcp-abc'], undefined)
-  expect(result.operations.map((operation) => operation.toolId)).toEqual(['mcp-abc-read'])
-})
+it.each([undefined, 'mcp-abc-write'])(
+  'exposes selected MCP operations without enabling sibling operations (exact lookup: %s)',
+  async (toolId) => {
+    queueChat('agent')
+    mocks.target.mockResolvedValue({ workspaceId: 'workspace-1' })
+    mocks.mcp.mockResolvedValue([
+      { name: 'mcp-abc-read', service: 'mcp:mcp-abc', description: 'Read', input_schema: {} },
+      { name: 'mcp-abc-write', service: 'mcp:mcp-abc', description: 'Write', input_schema: {} },
+    ])
+    const result = await readIntegrationCatalog.execute({
+      principal: principal(),
+      input: {
+        ...input,
+        mode: 'agent',
+        workspaceId: 'workspace-1',
+        mcpToolIds: ['mcp-abc-read'],
+        service: 'mcp:mcp-abc',
+        ...(toolId ? { toolId } : {}),
+      },
+    })
+    expect(mocks.mcp).toHaveBeenCalledWith('actor', 'workspace-1', ['mcp-abc'], undefined)
+    expect(result.operations.map((operation) => operation.toolId)).toEqual(
+      toolId ? [] : ['mcp-abc-read']
+    )
+  }
+)
 it('keeps native discovery available in organization chats with tagged MCP servers', async () => {
   queueChat('agent')
   const result = await readIntegrationCatalog.execute({

apps/sim/lib/workflows/application/inspect-workflow-tools.test.ts

@@ -325,14 +325,36 @@ describe('configured workflow tool inspection', () => {
     const result = await inspect()
     expect(result.selected[0]).toMatchObject({
       callableName: 'mcp-server-read',
-      usageControl: 'auto',
+      usageControl: 'force',
     })
     expect(result.selected[0].fixedArgumentNames).toBeUndefined()
     expect(result.selected[1].status).toBe('unavailable')
     expect(result.ambient?.total).toBe(2)
     expect(JSON.stringify(result)).not.toContain('never-return')
   })
 
+  it.each(['<start.mode>', 'none'])(
+    'reports Sim Chat variable mode %s without discovering disabled or unresolved tools',
+    async (usageControlExpression) => {
+      save(
+        'mothership',
+        [
+          {
+            type: 'mcp',
+            usageControl: 'force',
+            usageControlExpression,
+            params: { serverId: 'server', toolName: 'read' },
+          },
+        ],
+        { data: { canonicalModes: { '0:agentToolUsageControl': 'advanced' } } }
+      )
+      expect((await inspect()).selected[0].status).toBe(
+        usageControlExpression === 'none' ? 'disabled' : 'unresolved'
+      )
+      expect(mocks.mcp).not.toHaveBeenCalled()
+    }
+  )
+
   it('does not discover tools from a disabled block', async () => {
     save('mothership', [{ type: 'mcp', params: { serverId: 'server', toolName: 'read' } }], {
       enabled: false,