feat(expert): human-in-the-loop tool permissions (#421)

forge/ee/routes/expert/index.js

@@ -43,8 +43,10 @@ module.exports = async function (app) {
                     error: 'unauthorized'
                 })
             }
-            // Ensure users team access is valid
-            const teamId = request.body.context?.teamId // `context.teamId` is the hash provided in the body context by the client
+            // Ensure users team access is valid. `teamId` is the team hash provided by the
+            // client — in the body context for POST routes (/chat, /mcp/features) or as a
+            // query param for GET routes (/mcp/tools, which has no body).
+            const teamId = request.body?.context?.teamId || request.query?.teamId
             if (!teamId) {
                 return reply.status(404).send({ code: 'not_found', error: 'Not Found' })
             }
@@ -480,6 +482,66 @@ module.exports = async function (app) {
             reply.code(error.response?.status || 500).send({ code: error.response?.data?.code || 'unexpected_error', error: error.response?.data?.error || error.message })
         }
     })
+
+    /**
+     * Retrieve the curated tool catalog for the Expert's human-in-the-loop permissions UI
+     * (#421). The MCP server(s) are static/global (not per-team registered), so unlike
+     * /mcp/features this is a thin read-only proxy: it forwards to the agent service's
+     * /mcp/tools endpoint, which returns friendly catalog entries only (raw MCP identifiers
+     * never leave the backend) plus a `hash` fingerprint of the catalog. Team access +
+     * feature gating are enforced by the shared preHandler above; read/write classification
+     * on each entry is what the client uses to decide which tools a role may enable.
+     */
+    app.get('/mcp/tools', {
+        schema: {
+            hide: true, // dont show in swagger
+            querystring: {
+                type: 'object',
+                properties: {
+                    teamId: { type: 'string', minLength: 10 }
+                },
+                required: ['teamId']
+            },
+            response: {
+                200: {
+                    type: 'object',
+                    properties: {
+                        catalog: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                additionalProperties: true
+                            }
+                        },
+                        hash: {
+                            type: ['string', 'null']
+                        }
+                    }
+                },
+                '4xx': {
+                    $ref: 'APIError'
+                }
+            }
+        }
+    },
+    async (request, reply) => {
+        if (!request.isExpertAssistantEnabled) {
+            return reply.status(404).send({ code: 'not_found', error: 'Not Found' })
+        }
+        try {
+            const toolsUrl = `${app.expert.expertUrl.split('/').slice(0, -1).join('/')}/mcp/tools`
+            const response = await axios.get(toolsUrl, {
+                headers: {
+                    Origin: request.headers.origin,
+                    ...(app.expert.serviceToken ? { Authorization: `Bearer ${app.expert.serviceToken}` } : {})
+                },
+                timeout: app.expert.requestTimeout
+            })
+            reply.send({ catalog: response.data?.catalog || [], hash: response.data?.hash || null })
+        } catch (error) {
+            reply.code(error.response?.status || 500).send({ code: error.response?.data?.code || 'unexpected_error', error: error.response?.data?.error || error.message })
+        }
+    })
 }
 
 /**

frontend/src/api/expert.js

@@ -48,7 +48,22 @@ const getCapabilities = async (payload) => {
     })
 }
 
+/**
+ * Fetch the curated tool catalog for the human-in-the-loop permissions UI (#421).
+ * Read-only GET — proxied by forge to the agent's /mcp/tools endpoint, which serves
+ * friendly catalog entries only (raw MCP identifiers never leave the backend) plus a
+ * `hash` fingerprint the UI uses to refetch only when the catalog changes.
+ * @param {{ teamId: string }} params
+ * @returns {Promise<{ catalog: Array, hash: string|null }>}
+ */
+const getToolCatalog = async ({ teamId } = {}) => {
+    return client.get('/api/v1/expert/mcp/tools', {
+        params: { teamId }
+    }).then(res => res.data)
+}
+
 export default {
     chat,
-    getCapabilities
+    getCapabilities,
+    getToolCatalog
 }

frontend/src/components/expert/components/ExpertChatInput.vue

@@ -105,6 +105,11 @@
                         data-el="expert-question-cadence"
                     />
                 </div>
+                <div class="expert-settings__group">
+                    <FormHeading>Tool permissions</FormHeading>
+                    <p>Choose which actions the Expert can run, and which need your approval.</p>
+                    <tool-permissions-settings :in-editor="isImmersive" />
+                </div>
             </div>
         </ff-dialog>
     </div>
@@ -118,6 +123,7 @@ import FormHeading from '../../FormHeading.vue'
 import ResizeBar from '../../ResizeBar.vue'
 
 import CapabilitiesSelector from './CapabilitiesSelector.vue'
+import ToolPermissionsSettings from './ToolPermissionsSettings.vue'
 import DefaultChip from './chips/DefaultChip.vue'
 import ContextSelector from './context-selection/index.vue'
 
@@ -135,7 +141,8 @@ export default {
         ContextSelector,
         DefaultChip,
         FormHeading,
-        ResizeBar
+        ResizeBar,
+        ToolPermissionsSettings
     },
     inject: {
         togglePinWithWidth: {
@@ -292,10 +299,14 @@ export default {
             minHeight: 120,
             maxViewportMarginY: 80
         })
+        // Fetch the tool catalog as soon as the Expert panel mounts (not only in the
+        // editor) so the permissions settings can render everywhere. Flow-building
+        // tools are still only usable from an instance editor (see isImmersive below).
+        this.fetchToolCatalog()
     },
     methods: {
         ...mapActions(useProductAssistantStore, ['resetContextSelection']),
-        ...mapActions(useProductExpertStore, ['startOver', 'handleQuery', 'setPendingInput', 'setQuestionCadence', 'setPlanMode']),
+        ...mapActions(useProductExpertStore, ['startOver', 'handleQuery', 'setPendingInput', 'setQuestionCadence', 'setPlanMode', 'fetchToolCatalog']),
         openSettings () {
             this.$refs.settingsDialog.show()
         },