Refactor agent-filtered tool registration (#12237)

Routed and unified MCP servers independently implemented near-identical
agent-policy filtering and SDK tool registration. This centralizes the
shared behavior while retaining each mode’s tool naming and handler
wiring.

- **Shared registration**
- Add `registerFilteredTools` to apply policy checks, skip unresolved
handlers, and map `ToolInfo` metadata to `sdk.Tool` consistently.

- **Mode-specific adapters**
- Routed mode supplies unprefixed tool identity and unified-handler
wrapping.
- Unified mode supplies prefixed tool identity and direct registered
handlers.

```go
registered := registerFilteredTools(
    server, tools, agentID,
    toolIdentity,
    us.agentCanUseTool,
    handlerFor,
)
```

- **Regression coverage**
- Cover allowed, denied, and missing-handler tools through the shared
helper.

<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #12208

Author: lpcox

internal/server/agent_policy_enforce.go

@@ -1,6 +1,7 @@
 package server
 
 import (
+	"context"
 	"strings"
 
 	"github.com/github/gh-aw-mcpg/internal/logger"
@@ -64,30 +65,24 @@ func createAgentFilteredUnifiedServer(us *UnifiedServer, agentID string) *sdk.Se
 	server := newSDKServer("awmg-unified", logTransport)
 
 	us.toolsMu.RLock()
-	tools := make([]*ToolInfo, 0, len(us.tools))
+	tools := make([]ToolInfo, 0, len(us.tools))
 	for _, t := range us.tools {
-		tools = append(tools, t)
+		tools = append(tools, *t)
 	}
 	us.toolsMu.RUnlock()
 
-	registered := 0
-	for _, toolInfo := range tools {
-		backendID := toolInfo.BackendID
-		unprefixed := strings.TrimPrefix(toolInfo.Name, backendID+"___")
-		if !us.agentCanUseTool(agentID, backendID, unprefixed) {
-			continue
-		}
-		if toolInfo.Handler == nil {
-			continue
-		}
-		registerToolWithoutValidation(server, &sdk.Tool{
-			Name:        toolInfo.Name,
-			Description: toolInfo.Description,
-			InputSchema: toolInfo.InputSchema,
-			Annotations: toolInfo.Annotations,
-		}, toolInfo.Handler)
-		registered++
-	}
+	registered := registerFilteredTools(
+		server,
+		tools,
+		agentID,
+		func(toolInfo ToolInfo) (string, string) {
+			return toolInfo.BackendID, strings.TrimPrefix(toolInfo.Name, toolInfo.BackendID+"___")
+		},
+		us.agentCanUseTool,
+		func(toolInfo ToolInfo) func(context.Context, *sdk.CallToolRequest, interface{}) (*sdk.CallToolResult, interface{}, error) {
+			return toolInfo.Handler
+		},
+	)
 
 	logger.LogInfo("client", "Built per-agent unified tool view: agent=%s, tools=%d",
 		util.HashIdentifierForLog(agentID), registered)

internal/server/agent_policy_visibility_test.go

@@ -37,6 +37,35 @@ func listToolsViaInMemory(t *testing.T, server *sdk.Server) []string {
 	return names
 }
 
+func TestRegisterFilteredTools(t *testing.T) {
+	server := newSDKServer("filtered-tools-test", logTransport)
+	handler := func(context.Context, *sdk.CallToolRequest, interface{}) (*sdk.CallToolResult, interface{}, error) {
+		return &sdk.CallToolResult{}, nil, nil
+	}
+	tools := []ToolInfo{
+		{Name: "allowed", BackendID: "github", InputSchema: map[string]interface{}{"type": "object"}},
+		{Name: "denied", BackendID: "github", InputSchema: map[string]interface{}{"type": "object"}},
+		{Name: "no-handler", BackendID: "github", InputSchema: map[string]interface{}{"type": "object"}},
+	}
+
+	registered := registerFilteredTools(
+		server,
+		tools,
+		"alice",
+		func(tool ToolInfo) (string, string) { return tool.BackendID, tool.Name },
+		func(_ string, _ string, toolName string) bool { return toolName != "denied" },
+		func(tool ToolInfo) func(context.Context, *sdk.CallToolRequest, interface{}) (*sdk.CallToolResult, interface{}, error) {
+			if tool.Name == "no-handler" {
+				return nil
+			}
+			return handler
+		},
+	)
+
+	assert.Equal(t, 1, registered)
+	assert.ElementsMatch(t, []string{"allowed"}, listToolsViaInMemory(t, server))
+}
+
 func agentVisibilityServer(t *testing.T) *UnifiedServer {
 	t.Helper()
 	cfg := &config.Config{

internal/server/routed.go

@@ -49,35 +49,28 @@ func createAgentFilteredServer(unifiedServer *UnifiedServer, backendID, agentID
 	logRouted.Printf("Creating filtered server for %s with %d tools", backendID, len(tools))
 	logRouted.Printf("Backend %s has %d tools available", backendID, len(tools))
 
-	// Register each tool (without prefix) using the unified server's handlers
-	for _, toolInfo := range tools {
-		// Capture for closure
-		toolNameCopy := toolInfo.Name
+	// Register each tool (without prefix) using the unified server's handlers.
+	registerFilteredTools(
+		server,
+		tools,
+		agentID,
+		func(toolInfo ToolInfo) (string, string) {
+			return backendID, toolInfo.Name
+		},
+		unifiedServer.agentCanUseTool,
+		func(toolInfo ToolInfo) func(context.Context, *sdk.CallToolRequest, interface{}) (*sdk.CallToolResult, interface{}, error) {
+			handler := unifiedServer.GetToolHandler(backendID, toolInfo.Name)
+			if handler == nil {
+				logRouted.Printf("WARNING: No handler found for %s___%s", backendID, toolInfo.Name)
+				return nil
+			}
 
-		// Per-agent tool visibility: skip tools this agent's policy does not permit.
-		if !unifiedServer.agentCanUseTool(agentID, backendID, toolNameCopy) {
-			continue
-		}
-
-		// Get the unified server's handler for this tool
-		handler := unifiedServer.GetToolHandler(backendID, toolInfo.Name)
-		if handler == nil {
-			logRouted.Printf("WARNING: No handler found for %s___%s", backendID, toolInfo.Name)
-			continue
-		}
-
-		// Use registerToolWithoutValidation to bypass JSON Schema validation, allowing
-		// InputSchema from backends using different JSON Schema versions (e.g., draft-07).
-		registerToolWithoutValidation(server, &sdk.Tool{
-			Name:        toolInfo.Name, // Without prefix for the client
-			Description: toolInfo.Description,
-			InputSchema: toolInfo.InputSchema, // Include schema for clients
-			Annotations: toolInfo.Annotations, // Preserve readOnly/destructive hints
-		}, func(ctx context.Context, req *sdk.CallToolRequest, _ interface{}) (*sdk.CallToolResult, interface{}, error) {
-			logRouted.Printf("[ROUTED] Calling unified handler for: %s", toolNameCopy)
-			return handler(ctx, req, nil)
-		})
-	}
+			return func(ctx context.Context, req *sdk.CallToolRequest, _ interface{}) (*sdk.CallToolResult, interface{}, error) {
+				logRouted.Printf("[ROUTED] Calling unified handler for: %s", toolInfo.Name)
+				return handler(ctx, req, nil)
+			}
+		},
+	)
 
 	return server
 }

internal/server/tool_registry_helpers.go

@@ -56,6 +56,38 @@ func registerToolWithoutValidation(server *sdk.Server, tool *sdk.Tool, handler f
 	})
 }
 
+// registerFilteredTools registers tools allowed for an agent and returns their count.
+func registerFilteredTools(
+	server *sdk.Server,
+	tools []ToolInfo,
+	agentID string,
+	toolIdentity func(ToolInfo) (backendID, toolName string),
+	canUseTool func(agentID, backendID, toolName string) bool,
+	handlerFor func(ToolInfo) func(context.Context, *sdk.CallToolRequest, interface{}) (*sdk.CallToolResult, interface{}, error),
+) int {
+	registered := 0
+	for _, toolInfo := range tools {
+		backendID, toolName := toolIdentity(toolInfo)
+		if !canUseTool(agentID, backendID, toolName) {
+			continue
+		}
+
+		handler := handlerFor(toolInfo)
+		if handler == nil {
+			continue
+		}
+
+		registerToolWithoutValidation(server, &sdk.Tool{
+			Name:        toolInfo.Name,
+			Description: toolInfo.Description,
+			InputSchema: toolInfo.InputSchema,
+			Annotations: toolInfo.Annotations,
+		}, handler)
+		registered++
+	}
+	return registered
+}
+
 func getToolResponseFilter(cfg *config.Config, serverID, toolName string) string {
 	if cfg == nil {
 		return ""