feat(ai): tool-level MCP capability-gating mechanism (#13745) (#13747)

Agent profiles select MCP servers all-or-nothing (Agent.servers); the Loop
exposes every tool of every connected client to the model. Add an optional
per-server `allowedTools` allowlist so a profile can expose only a subset of
a server's tools — e.g. limiting a local lower-parameter worker to a single
trap endpoint — enforced at tool-assembly via the pure resolveAllowedTools
filter. Default null = no filtering (backward-compatible).

Slice of #9980 (the tier-to-tool policy matrix stays open for
design-convergence); this is the enabling mechanism only.

Author: neo-opus-vega

ai/Agent.mjs

@@ -46,6 +46,16 @@ class Agent extends Base {
          * @member {String[]} servers=[]
          */
         servers: [],
+        /**
+         * Optional per-server tool allowlist for least-privilege capability gating. Shape:
+         * `{[serverName]: String[]}` — restricts a connected server to the named tools (e.g. limiting a
+         * local lower-parameter worker to `{'github-workflow': ['signal_state_transition']}` so it cannot
+         * initiate destructive operations it lacks the cognitive architecture to navigate). A server absent
+         * from the map keeps its full surface; `null` disables filtering entirely (the backward-compatible
+         * default). Enforced at tool-assembly via {@link Neo.ai.agent.resolveAllowedTools}.
+         * @member {Object|null} allowedTools=null
+         */
+        allowedTools: null,
         /**
          * Registered sub-agent profiles available for delegation.
          * @member {Object} subAgents
@@ -132,9 +142,10 @@ ALWAYS use your file system or knowledge base tools to read the relevant source
 
         // Create the Loop
         this.loop = Neo.create(Loop, {
-            agent: this,
+            agent       : this,
+            allowedTools: this.allowedTools,
             assembler,
-            clients: this.clients,
+            clients     : this.clients,
             provider,
             scheduler
         });
@@ -217,7 +228,7 @@ ALWAYS use your file system or knowledge base tools to read the relevant source
 
             subAgent = Neo.create(ProfileClass);
             await subAgent.ready();
-            
+
             this.activeSubAgents[profileName] = subAgent;
             this.subAgentTurns[profileName]   = 0;
         } else {
@@ -226,7 +237,7 @@ ALWAYS use your file system or knowledge base tools to read the relevant source
 
         try {
             this.subAgentTurns[profileName]++;
-            
+
             const result = await subAgent.loop.processEvent({
                 type: 'delegate',
                 data: request,

ai/agent/Loop.mjs

@@ -1,8 +1,9 @@
-import Assembler       from '../context/Assembler.mjs';
-import Base            from '../../src/core/Base.mjs';
-import ClassSystemUtil from '../../src/util/ClassSystem.mjs';
-import Provider        from '../provider/Base.mjs';
-import * as SDK        from '../services.mjs';
+import Assembler             from '../context/Assembler.mjs';
+import Base                  from '../../src/core/Base.mjs';
+import ClassSystemUtil       from '../../src/util/ClassSystem.mjs';
+import Provider              from '../provider/Base.mjs';
+import * as SDK              from '../services.mjs';
+import {resolveAllowedTools} from './resolveAllowedTools.mjs';
 
 /**
  * The cognitive event loop for the Agent.
@@ -20,6 +21,15 @@ class Loop extends Base {
          * @protected
          */
         className: 'Neo.ai.agent.Loop',
+        /**
+         * Optional per-server tool allowlist injected by the Agent for capability gating. Shape
+         * `{[serverName]: String[]}`, or null for no filtering. Applied at tool-assembly so only the
+         * permitted subset of each connected server's tools is exposed to the model — and only those are
+         * registered in `toolRegistry`, so a gated-out tool is not even routable.
+         * See {@link Neo.ai.agent.resolveAllowedTools}.
+         * @member {Object|null} allowedTools=null
+         */
+        allowedTools: null,
         /**
          * The Context Assembler instance.
          * @member {Neo.ai.context.Assembler|Object} assembler_=null
@@ -193,7 +203,12 @@ class Loop extends Base {
 
             for (const [clientName, client] of Object.entries(this.clients)) {
                 try {
-                    const clientTools = await client.listTools();
+                    // Least-privilege: expose only the profile-permitted subset of this server's tools.
+                    const clientTools = resolveAllowedTools({
+                        tools       : await client.listTools(),
+                        allowedTools: this.allowedTools,
+                        serverName  : client.serverName
+                    });
                     for (const tool of clientTools) {
                         this.tools.push(tool);
                         this.toolRegistry[tool.name] = { client, clientName, method: Neo.camel(tool.name) };
@@ -356,7 +371,7 @@ class Loop extends Base {
             // Allow up to 10 iterations of tool chaining
             for (let i = 0; i < 10; i++) {
                 const result = await this.provider.generate(messages, { tools: this.tools });
-                
+
                 if (result.content) {
                     console.log(`[Loop] Model Response:\n${result.content}`);
                 }
@@ -365,21 +380,21 @@ class Loop extends Base {
                 if (result.toolCalls && result.toolCalls.length > 0) {
                     this.state = 'acting';
                     actionResult = await this.executeTools(result.toolCalls);
-                    
+
                     // Push the model's textual response (if any)
                     messages.push({
                         role   : 'model',
                         content: result.content || `(Delegated to tools: ${result.toolCalls.map(t => t.function.name).join(', ')})`
                     });
-                    
+
                     // Format tool results as a user observation for the next LLM turn
                     const toolResponsesStr = actionResult.map(r => `[Tool Result: ${r.name}]\n${r.error || JSON.stringify(r.result)}`).join('\n\n');
-                    
+
                     messages.push({
                         role   : 'user',
                         content: `Observation from tools:\n${toolResponsesStr}\n\nPlease proceed based on the above results.`
                     });
-                    
+
                     this.state = 'thinking'; // Resume reasoning
                 } else {
                     // No further tool calls -> Final answer achieved
@@ -445,12 +460,12 @@ class Loop extends Base {
 
             if (success) {
                 console.log(`[Loop] ✓ Cycle succeeded for ${event.type}`);
-                
+
                 if (event.type === 'user:input' || event.type === 'delegate') {
                     const agentName = this.agent?.constructor?.config?.className?.split('.').pop() || 'unknown';
                     const modelName = this.provider?.model || this.provider?.modelName || 'unknown';
                     const sessionId = this.agent?.sessionId || 'default-session';
-                    
+
                     await SDK.Memory_Service.addMemory({
                         prompt: event.data,
                         thought: decision.thought || 'Internal reflection',
@@ -486,7 +501,7 @@ class Loop extends Base {
                     // Route to injected MCP client
                     const entry = this.toolRegistry[name];
                     console.log(`[Loop] Routing tool '${name}' to MCP Server '${entry.clientName}'`);
-                    
+
                     const res = await entry.client.callTool(name, args);
                     results.push({ name, result: res });
                 } else if (name === 'delegate_task') {

ai/agent/resolveAllowedTools.mjs

@@ -0,0 +1,34 @@
+/**
+ * @summary Pure least-privilege filter for an agent profile's MCP tool surface — the capability-gating mechanism.
+ *
+ * `Agent.servers` selects MCP servers all-or-nothing: `Loop.initAsync` exposes every tool of every connected
+ * client to the model. That is fine for a frontier model, but over-exposes a local lower-parameter worker (e.g.
+ * a Gemma Librarian) to an API surface it cannot navigate safely — the risk of destructive CLI/GraphQL
+ * loops. This function lets a profile additionally restrict a connected server to an explicit subset of its
+ * tools (e.g. a worker limited to the `signal_state_transition` trap endpoint) without forking the server.
+ *
+ * Pure and side-effect-free so it is testable without standing up a live MCP client; the caller (the Loop's
+ * tool-assembly) applies it per connected server. It is policy-agnostic: the tier→tool *matrix* (which tools a
+ * model tier gets) is the caller's to define — this primitive only enforces whatever allowlist it is handed.
+ *
+ * Default is fail-open per server, so the mechanism is backward-compatible and opt-in:
+ * - `allowedTools` null/undefined → no filtering anywhere (existing profiles keep their full surface).
+ * - a server **absent** from a non-null `allowedTools` map → that server's full surface (only the servers you
+ *   name are constrained, so forgetting one is not a silent capability loss).
+ * - a server **present** in the map → only its listed tools (an explicit empty list `[]` denies all of them).
+ *
+ * @param {Object}        options
+ * @param {Object[]}      options.tools              The full tool list from one server (each a `{name, ...}` schema).
+ * @param {Object|null}   [options.allowedTools=null] Per-server allowlist `{[serverName]: String[]}`, or null for none.
+ * @param {String}        options.serverName         The raw server name (matches the `Agent.servers` keys, e.g. 'github-workflow').
+ * @returns {Object[]} The permitted subset of `tools` — a new array; the input is never mutated.
+ */
+export function resolveAllowedTools({tools, allowedTools = null, serverName}) {
+    if (!allowedTools || !Object.hasOwn(allowedTools, serverName)) {
+        return tools;
+    }
+
+    const allow = new Set(allowedTools[serverName]);
+
+    return tools.filter(tool => allow.has(tool.name));
+}

test/playwright/unit/ai/resolveAllowedTools.spec.mjs

@@ -0,0 +1,60 @@
+import {test, expect}        from '@playwright/test';
+import {resolveAllowedTools} from '../../../../ai/agent/resolveAllowedTools.mjs';
+
+// Pure function — imported directly (no live MCP client), so each case is fully isolated. Tool fixtures
+// mirror a real github-workflow surface where most tools are dangerous and only one is a safe trap endpoint.
+const tools = [
+    {name: 'signal_state_transition', inputSchema: {}},
+    {name: 'create_issue',            inputSchema: {}},
+    {name: 'manage_issue_labels',     inputSchema: {}},
+    {name: 'sync_all',                inputSchema: {}}
+];
+
+test.describe('resolveAllowedTools (#9980 MCP tool-level capability gating)', () => {
+    test('returns the full surface when allowedTools is absent (backward-compatible default)', () => {
+        expect(resolveAllowedTools({tools, serverName: 'github-workflow'})).toEqual(tools);
+        expect(resolveAllowedTools({tools, allowedTools: null,      serverName: 'github-workflow'})).toEqual(tools);
+        expect(resolveAllowedTools({tools, allowedTools: undefined, serverName: 'github-workflow'})).toEqual(tools);
+    });
+
+    test('returns the full surface for a server absent from a non-null map (per-server opt-in)', () => {
+        // only knowledge-base is constrained; github-workflow is unnamed, so it keeps its full surface
+        const allowedTools = {'knowledge-base': ['ask_knowledge_base']};
+        expect(resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'})).toEqual(tools);
+    });
+
+    test('restricts a named server to its allowlisted subset (the trap-endpoint case)', () => {
+        const allowedTools = {'github-workflow': ['signal_state_transition']};
+        const result       = resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'});
+        expect(result.map(t => t.name)).toEqual(['signal_state_transition']);
+    });
+
+    test('preserves allowlist multiplicity and original order, not the allowlist order', () => {
+        const allowedTools = {'github-workflow': ['sync_all', 'signal_state_transition']};
+        const result       = resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'});
+        // filtered from the source list, so source order wins
+        expect(result.map(t => t.name)).toEqual(['signal_state_transition', 'sync_all']);
+    });
+
+    test('an explicit empty allowlist denies every tool from that server', () => {
+        const allowedTools = {'github-workflow': []};
+        expect(resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'})).toEqual([]);
+    });
+
+    test('an allowlisted name that the server does not expose is simply omitted (no throw)', () => {
+        const allowedTools = {'github-workflow': ['signal_state_transition', 'nonexistent_tool']};
+        const result       = resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'});
+        expect(result.map(t => t.name)).toEqual(['signal_state_transition']);
+    });
+
+    test('never mutates the input tool list (returns a new array)', () => {
+        const allowedTools = {'github-workflow': ['signal_state_transition']};
+        const result       = resolveAllowedTools({tools, allowedTools, serverName: 'github-workflow'});
+        expect(result).not.toBe(tools);
+        expect(tools).toHaveLength(4); // source untouched
+    });
+
+    test('an empty source surface resolves to empty regardless of allowlist', () => {
+        expect(resolveAllowedTools({tools: [], allowedTools: {'github-workflow': ['x']}, serverName: 'github-workflow'})).toEqual([]);
+    });
+});