Wire toolTimeout as context deadline in callBackendTool

The ToolTimeout config value was never consumed to create a context
deadline — removing http.Client.Timeout (120s) would leave HTTP backend
calls unbounded. Fix by adding context.WithTimeout(ctx, toolTimeout) in
callBackendTool as the primary enforcement point.

- Add context.WithTimeout in callBackendTool using cfg.Gateway.ToolTimeout
- Nil-check cfg.Gateway before accessing ToolTimeout (it's a pointer)
- Add TestCallBackendTool_ToolTimeoutEnforcedViaContext proving deadline
- Update CONFIGURATION.md to accurately describe enforcement scope

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lpcox

docs/CONFIGURATION.md

@@ -372,7 +372,7 @@ The `customSchemas` top-level field allows you to define custom server types bey
 | `apiKey` | API key for authentication | (disabled) |
 | `domain` | Gateway domain (`"localhost"`, `"host.docker.internal"`, or `"${VAR}"`) | (unset) |
 | `startupTimeout` | Seconds to wait for backend startup | `30` |
-| `toolTimeout` | Seconds to wait for tool execution (applies to backend request execution via request context deadlines, including HTTP backends) | `60` |
+| `toolTimeout` | Maximum seconds for a single tool call, enforced as a context deadline on all backend requests (stdio and HTTP) | `60` |
 | `payloadDir` | Directory for large payload files | `/tmp/jq-payloads` |
 | `payloadSizeThreshold` (JSON) / `payload_size_threshold` (TOML) | Size threshold in bytes; responses larger than this are stored to disk and returned as a `payloadPath` reference | `524288` (512 KB) |
 | `trustedBots` (JSON) / `trusted_bots` (TOML) | Optional list of additional bot usernames to trust with "approved" integrity level. Additive to the built-in trusted bot list. When specified, must be a non-empty array with non-empty string entries (spec §4.1.3.4); omit the field entirely if not needed. Example: `["my-bot[bot]", "org-automation"]` | (disabled) |

internal/server/call_backend_tool_test.go

@@ -7,6 +7,7 @@ import (
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/github/gh-aw-mcpg/internal/config"
 	sdk "github.com/modelcontextprotocol/go-sdk/mcp"
@@ -484,3 +485,72 @@ func TestCallBackendTool_AllowedToolsError_MessageFormat(t *testing.T) {
 	assert.True(t, strings.Contains(text, `"blocked"`), "error message should include tool name: %s", text)
 	assert.True(t, strings.Contains(text, "allowed-tools"), "error message should mention allowed-tools: %s", text)
 }
+
+// TestCallBackendTool_ToolTimeoutEnforcedViaContext verifies that the configured
+// toolTimeout is applied as a context deadline, causing slow backend calls to fail
+// with a deadline-exceeded error instead of hanging indefinitely.
+func TestCallBackendTool_ToolTimeoutEnforcedViaContext(t *testing.T) {
+	require := require.New(t)
+
+	// Create a slow backend that delays longer than our tool timeout
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req map[string]interface{}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+
+		method, _ := req["method"].(string)
+		switch method {
+		case "initialize":
+			json.NewEncoder(w).Encode(map[string]interface{}{
+				"jsonrpc": "2.0", "id": req["id"],
+				"result": map[string]interface{}{
+					"protocolVersion": "2024-11-05",
+					"capabilities":    map[string]interface{}{},
+					"serverInfo":      map[string]interface{}{"name": "slow-backend", "version": "1.0.0"},
+				},
+			})
+		case "tools/list":
+			json.NewEncoder(w).Encode(map[string]interface{}{
+				"jsonrpc": "2.0", "id": req["id"],
+				"result": map[string]interface{}{"tools": []map[string]interface{}{}},
+			})
+		case "tools/call":
+			// Simulate a slow tool: sleep longer than the configured toolTimeout.
+			// The actual tool call should return after ~1s (timeout), but the
+			// httptest.Server cleanup waits for this goroutine to finish.
+			time.Sleep(3 * time.Second)
+			json.NewEncoder(w).Encode(map[string]interface{}{
+				"jsonrpc": "2.0", "id": req["id"],
+				"result": map[string]interface{}{
+					"content": []map[string]interface{}{{"type": "text", "text": "should not reach here"}},
+				},
+			})
+		}
+	}))
+	defer backend.Close()
+
+	// Configure with a very short toolTimeout (1 second)
+	cfg := &config.Config{
+		Gateway: &config.GatewayConfig{
+			ToolTimeout: 1,
+		},
+		Servers: map[string]*config.ServerConfig{
+			"slow": {Type: "http", URL: backend.URL},
+		},
+	}
+
+	us, err := NewUnified(context.Background(), cfg)
+	require.NoError(err)
+	defer us.Close()
+
+	ctx := context.WithValue(context.Background(), SessionIDContextKey, "timeout-test")
+	result, _, callErr := us.callBackendTool(ctx, "slow", "slow_tool", map[string]interface{}{})
+
+	// The call should fail due to context deadline exceeded
+	require.Error(callErr, "Tool call should fail due to timeout")
+	require.NotNil(result, "Should return a CallToolResult even on timeout")
+	require.True(result.IsError, "Result should be marked as error")
+	t.Logf("Tool call correctly timed out: %v", callErr)
+}

internal/server/unified.go

@@ -466,6 +466,16 @@ func (us *UnifiedServer) callBackendTool(ctx context.Context, serverID, toolName
 	// The closure captures the request and validates before calling this method
 	logUnified.Printf("callBackendTool: serverID=%s, toolName=%s, args=%+v", serverID, toolName, args)
 
+	// Apply the configured tool timeout as a context deadline so backend calls
+	// (including HTTP backends) are bounded by toolTimeout rather than hanging
+	// indefinitely.  This is the primary enforcement point for the gateway's
+	// tool execution budget.
+	if us.cfg != nil && us.cfg.Gateway != nil && us.cfg.Gateway.ToolTimeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, time.Duration(us.cfg.Gateway.ToolTimeout)*time.Second)
+		defer cancel()
+	}
+
 	// Start an OTEL span for the full tool call lifecycle (spans all phases 0–6)
 	// Attribute names follow MCP Gateway Specification §4.1.3.6
 	ctx, toolSpan := us.getTracer().Start(ctx, "mcp.tool_call",