feat(core): add request-aware tool search filtering (#16088)

Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: 3 people

.changeset/six-badgers-drop.md

@@ -0,0 +1,15 @@
+---
+'@mastra/core': minor
+---
+
+Added request-aware filtering for ToolSearchProcessor search, load, and active tools. The filter hook receives the resolved tool ID as `toolName`.
+
+```ts
+new ToolSearchProcessor({
+  tools,
+  filter: ({ toolName, requestContext }) => {
+    const plan = requestContext?.get('plan')
+    return plan === 'pro' || !toolName.startsWith('premium_')
+  },
+})
+```

docs/src/content/en/reference/processors/tool-search-processor.mdx

@@ -76,6 +76,13 @@ const toolSearch = new ToolSearchProcessor({
             isOptional: true,
             default: '3600000',
           },
+          {
+            name: 'filter',
+            type: '(args: ToolSearchFilterArgs) => boolean | Promise<boolean>',
+            description:
+              'Optional request-aware hook for hiding tools from search results, blocking tool loading, or hiding already-loaded tools for the current request.',
+            isOptional: true,
+          },
         ],
       },
     ],
@@ -109,6 +116,35 @@ const toolSearch = new ToolSearchProcessor({
 ]}
 />
 
+## Request-aware filtering
+
+Use `filter` to apply request-specific policy to dynamic tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
+
+```typescript
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: allTools,
+  filter: ({ toolName, requestContext, phase }) => {
+    const plan = requestContext?.get('plan')
+
+    if (phase === 'search') {
+      return true
+    }
+
+    return plan === 'pro' || !toolName.startsWith('premium_')
+  },
+})
+```
+
+The `phase` value describes where the filter is being applied:
+
+- `search`: Filters results returned by `search_tools`.
+- `load`: Blocks `load_tool` from loading disallowed tools.
+- `active`: Hides already-loaded tools from the current request if they are no longer allowed.
+
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The meta-tools `search_tools` and `load_tool` are always available. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+
 ## Extended usage example
 
 ```typescript title="src/mastra/agents/dynamic-tools-agent.ts"

packages/core/src/processors/processors/index.ts

@@ -63,7 +63,12 @@ export { ToolCallFilter } from './tool-call-filter';
 
 export { AgentsMDInjector, type ToolResultReminderOptions } from '../tool-result-reminder';
 
-export { ToolSearchProcessor, type ToolSearchProcessorOptions } from './tool-search';
+export {
+  ToolSearchProcessor,
+  type ToolSearchFilterArgs,
+  type ToolSearchFilterPhase,
+  type ToolSearchProcessorOptions,
+} from './tool-search';
 export { SkillsProcessor, type SkillsProcessorOptions } from './skills';
 export { SkillSearchProcessor, type SkillSearchProcessorOptions } from './skill-search';
 export { WorkspaceInstructionsProcessor, type WorkspaceInstructionsProcessorOptions } from './workspace-instructions';

packages/core/src/processors/processors/tool-search.test.ts

@@ -474,6 +474,45 @@ describe('ToolSearchProcessor', () => {
       expect(loadResult.message).toContain('Did you mean');
     });
 
+    it('should preserve key-only suggestions when filter is omitted', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather_tool_id', 'Get weather'),
+        },
+      });
+
+      const args = createMockArgs('thread-suggestion-key');
+      const result = await processor.processInputStep(args);
+      const loadTool = result.tools?.load_tool;
+
+      const loadResult = await loadTool!.execute?.({ toolName: 'weath' }, undefined);
+
+      expect(loadResult.success).toBe(false);
+      expect(loadResult.message).toContain('Did you mean: weather');
+      expect(loadResult.message).not.toContain('weather_tool_id');
+    });
+
+    it('should preserve key-first load resolution when filter is omitted', async () => {
+      const keyedTool = createMockTool('public_weather', 'Public weather');
+      const idCollisionTool = createMockTool('weather', 'Private weather');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: keyedTool,
+          private_weather: idCollisionTool,
+        },
+      });
+
+      const args1 = createMockArgs('thread-no-filter-key-id-collision');
+      const result1 = await processor.processInputStep(args1);
+      const loadResult = await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      expect(loadResult.success).toBe(true);
+
+      const args2 = createMockArgs('thread-no-filter-key-id-collision');
+      const result2 = await processor.processInputStep(args2);
+      expect(result2.tools?.weather).toBe(keyedTool);
+    });
+
     it('should indicate when tool is already loaded', async () => {
       const processor = new ToolSearchProcessor({
         tools: {
@@ -695,6 +734,271 @@ describe('ToolSearchProcessor', () => {
     });
   });
 
+  describe('request-aware filtering', () => {
+    it('should filter search results with filter', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather forecast'),
+          weather_alerts: createMockTool('weather_alerts', 'Get weather alerts'),
+        },
+        filter: ({ toolName, phase }) => phase !== 'search' || toolName !== 'weather_alerts',
+      });
+
+      const args = createMockArgs('thread-filter-search');
+      const result = await processor.processInputStep(args);
+      const searchResult = await result.tools?.search_tools!.execute?.({ query: 'weather' }, undefined);
+
+      expect(searchResult.results.map((tool: any) => tool.name)).toEqual(['weather']);
+    });
+
+    it('should filter search results against the indexed tool id when keys collide with tool ids', async () => {
+      const privateTool = createMockTool('weather', 'Private weather forecast');
+      const publicTool = createMockTool('public_weather', 'Public weather forecast');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          private_weather: privateTool,
+          weather: publicTool,
+        },
+        filter: ({ toolName }) => toolName !== 'weather',
+      });
+
+      const args = createMockArgs('thread-filter-key-id-collision');
+      const result = await processor.processInputStep(args);
+      const searchResult = await result.tools?.search_tools!.execute?.({ query: 'weather' }, undefined);
+
+      expect(searchResult.results.map((tool: any) => tool.name)).toEqual(['public_weather']);
+    });
+
+    it('should support async filter hooks', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather forecast'),
+          calendar: createMockTool('calendar', 'Manage calendar'),
+        },
+        filter: async ({ toolName, phase }) => {
+          await Promise.resolve();
+          return phase !== 'search' || toolName !== 'calendar';
+        },
+      });
+
+      const args = createMockArgs('thread-async-filter');
+      const result = await processor.processInputStep(args);
+      const searchResult = await result.tools?.search_tools!.execute?.({ query: 'calendar' }, undefined);
+
+      expect(searchResult.results).toEqual([]);
+    });
+
+    it('should block loading disallowed tools', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather'),
+        },
+        filter: ({ phase }) => phase !== 'load',
+      });
+
+      const args1 = createMockArgs('thread-load-filter');
+      const result1 = await processor.processInputStep(args1);
+      const loadResult = await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      expect(loadResult.success).toBe(false);
+      expect(loadResult.toolName).toBe('weather');
+
+      const args2 = createMockArgs('thread-load-filter');
+      const result2 = await processor.processInputStep(args2);
+      expect(result2.tools?.weather).toBeUndefined();
+    });
+
+    it('should filter load requests against the resolved tool id when keys collide with tool ids', async () => {
+      const privateTool = createMockTool('weather', 'Private weather forecast');
+      const publicTool = createMockTool('public_weather', 'Public weather forecast');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          private_weather: privateTool,
+          weather: publicTool,
+        },
+        filter: ({ toolName }) => toolName !== 'weather',
+      });
+
+      const args1 = createMockArgs('thread-load-key-id-collision');
+      const result1 = await processor.processInputStep(args1);
+      const loadResult = await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      expect(loadResult.success).toBe(false);
+
+      const args2 = createMockArgs('thread-load-key-id-collision');
+      const result2 = await processor.processInputStep(args2);
+      expect(result2.tools?.weather).toBeUndefined();
+    });
+
+    it('should not leak disallowed tools in load suggestions', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          premium_weather: createMockTool('premium_weather', 'Premium weather'),
+          public_weather: createMockTool('public_weather', 'Public weather'),
+        },
+        filter: ({ toolName }) => toolName !== 'premium_weather',
+      });
+
+      const args = createMockArgs('thread-filter-suggestions');
+      const result = await processor.processInputStep(args);
+      const loadResult = await result.tools?.load_tool!.execute?.({ toolName: 'premium' }, undefined);
+
+      expect(loadResult.success).toBe(false);
+      expect(loadResult.message).not.toContain('premium_weather');
+    });
+
+    it('should not suggest filtered key aliases that resolve to disallowed tool ids', async () => {
+      const privateTool = createMockTool('weather', 'Private weather forecast');
+      const publicTool = createMockTool('public_weather', 'Public weather forecast');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          private_weather: privateTool,
+          weather: publicTool,
+        },
+        filter: ({ toolName }) => toolName !== 'weather',
+      });
+
+      const args = createMockArgs('thread-filter-suggestions-key-id-collision');
+      const result = await processor.processInputStep(args);
+      const loadResult = await result.tools?.load_tool!.execute?.({ toolName: 'weath' }, undefined);
+
+      expect(loadResult.success).toBe(false);
+      expect(loadResult.message).not.toContain('Did you mean: weather');
+    });
+
+    it('should fill search results from lower-ranked allowed matches', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          premium_a: createMockTool('premium_a', 'Shared capability'),
+          premium_b: createMockTool('premium_b', 'Shared capability'),
+          premium_c: createMockTool('premium_c', 'Shared capability'),
+          premium_d: createMockTool('premium_d', 'Shared capability'),
+          public_a: createMockTool('public_a', 'Shared capability'),
+          public_b: createMockTool('public_b', 'Shared capability'),
+        },
+        search: { topK: 2 },
+        filter: ({ toolName, phase }) => phase !== 'search' || toolName.startsWith('public_'),
+      });
+
+      const args = createMockArgs('thread-filter-fill');
+      const result = await processor.processInputStep(args);
+      const searchResult = await result.tools?.search_tools!.execute?.({ query: 'shared' }, undefined);
+
+      expect(searchResult.results.map((tool: any) => tool.name)).toEqual(['public_a', 'public_b']);
+    });
+
+    it('should pass resolved tool id, tool, request context, and phase to filter', async () => {
+      const calls: Array<{ toolName: string; tool: Tool<any, any>; requestContext?: RequestContext; phase: string }> =
+        [];
+      const weatherTool = createMockTool('weather_tool_id', 'Get weather');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: weatherTool,
+        },
+        filter: args => {
+          calls.push(args);
+          return true;
+        },
+      });
+
+      const args1 = createMockArgs('thread-filter-args');
+      args1.requestContext?.set('plan', 'pro');
+      const result1 = await processor.processInputStep(args1);
+      await result1.tools?.search_tools!.execute?.({ query: 'weather' }, undefined);
+      await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      const args2 = createMockArgs('thread-filter-args');
+      args2.requestContext?.set('plan', 'pro');
+      await processor.processInputStep(args2);
+
+      expect(calls.map(call => call.phase)).toEqual(['search', 'load', 'active']);
+      expect(calls.every(call => call.toolName === 'weather_tool_id')).toBe(true);
+      expect(calls.every(call => call.tool === weatherTool)).toBe(true);
+      expect(calls.every(call => call.requestContext?.get('plan') === 'pro')).toBe(true);
+    });
+
+    it('should fail closed when filter throws', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather'),
+        },
+        filter: () => {
+          throw new Error('policy unavailable');
+        },
+      });
+
+      const args = createMockArgs('thread-filter-throws');
+      const result = await processor.processInputStep(args);
+      const searchResult = await result.tools?.search_tools!.execute?.({ query: 'weather' }, undefined);
+      const loadResult = await result.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      expect(searchResult.results).toEqual([]);
+      expect(loadResult.success).toBe(false);
+    });
+
+    it('should filter active loaded tools per request without clearing thread state', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather'),
+        },
+        filter: ({ phase, requestContext }) => {
+          if (phase !== 'active') return true;
+          return requestContext?.get('allowWeather') === true;
+        },
+      });
+
+      const args1 = createMockArgs('thread-active-filter');
+      args1.requestContext?.set('allowWeather', true);
+      const result1 = await processor.processInputStep(args1);
+      await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      const disallowedArgs = createMockArgs('thread-active-filter');
+      disallowedArgs.requestContext?.set('allowWeather', false);
+      const disallowedResult = await processor.processInputStep(disallowedArgs);
+      expect(disallowedResult.tools?.weather).toBeUndefined();
+
+      const allowedArgs = createMockArgs('thread-active-filter');
+      allowedArgs.requestContext?.set('allowWeather', true);
+      const allowedResult = await processor.processInputStep(allowedArgs);
+      expect(allowedResult.tools?.weather).toBeDefined();
+    });
+
+    it('should preserve existing tools passed to processInputStep when filter is provided', async () => {
+      const existingTool = createMockTool('weather', 'Existing weather tool');
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Dynamic weather tool'),
+        },
+        filter: () => false,
+      });
+
+      const args = createMockArgs('thread-existing-filter', { weather: existingTool });
+      const result = await processor.processInputStep(args);
+
+      expect(result.tools?.weather).toBe(existingTool);
+    });
+
+    it('should keep existing behavior when filter is omitted', async () => {
+      const processor = new ToolSearchProcessor({
+        tools: {
+          weather: createMockTool('weather', 'Get weather'),
+        },
+      });
+
+      const args1 = createMockArgs('thread-no-filter');
+      const result1 = await processor.processInputStep(args1);
+      const searchResult = await result1.tools?.search_tools!.execute?.({ query: 'weather' }, undefined);
+      const loadResult = await result1.tools?.load_tool!.execute?.({ toolName: 'weather' }, undefined);
+
+      expect(searchResult.results[0].name).toBe('weather');
+      expect(loadResult.success).toBe(true);
+
+      const args2 = createMockArgs('thread-no-filter');
+      const result2 = await processor.processInputStep(args2);
+      expect(result2.tools?.weather).toBeDefined();
+    });
+  });
+
   describe('processInputStep integration', () => {
     it('should return meta-tools (search_tools and load_tool)', async () => {
       const processor = new ToolSearchProcessor({