fix: include output schema in tool approval hash migration (#527)

* fix output schema hash migration

* harden output schema hash migration

* address output schema migration review

* preserve direct output schema in tools list

* fix(quarantine): only fold output schema into approval hash when present

The output-schema segment was written unconditionally, changing the
approval hash for every tool — including those with no outputSchema —
which tripped TestCalculateToolApprovalHash_Stability and forced an
unnecessary re-baseline of all approved tools on upgrade.

Gate the segment on a non-empty normalized output schema so tools
without an outputSchema keep their original hash (no re-baseline,
no re-quarantine). Tools that do expose an outputSchema still get a
new hash, handled by the version-gated migration in checkToolApprovals.

---------

Co-authored-by: Algis Dumbris <a.dumbris@gmail.com>

Author: muxammadreza

internal/config/config.go

@@ -239,9 +239,9 @@ type ServerConfig struct {
 	// when the server is configured with both Command and an HTTP/SSE URL — i.e.,
 	// mcpproxy starts the process AND connects via network. Stdio servers ignore
 	// this field. Zero or unset → 30s default.
-	LauncherWaitTimeout Duration  `json:"launcher_wait_timeout,omitempty" mapstructure:"launcher_wait_timeout" swaggertype:"string"`
-	EnabledTools        []string  `json:"enabled_tools,omitempty" mapstructure:"enabled_tools"`   // Allowlist: only these tools are exposed; mutually exclusive with disabled_tools
-	DisabledTools       []string  `json:"disabled_tools,omitempty" mapstructure:"disabled_tools"` // Denylist: these tools are hidden; mutually exclusive with enabled_tools
+	LauncherWaitTimeout Duration `json:"launcher_wait_timeout,omitempty" mapstructure:"launcher_wait_timeout" swaggertype:"string"`
+	EnabledTools        []string `json:"enabled_tools,omitempty" mapstructure:"enabled_tools"`   // Allowlist: only these tools are exposed; mutually exclusive with disabled_tools
+	DisabledTools       []string `json:"disabled_tools,omitempty" mapstructure:"disabled_tools"` // Denylist: these tools are hidden; mutually exclusive with enabled_tools
 }
 
 // OAuthConfig represents OAuth configuration for a server
@@ -523,14 +523,15 @@ func ConvertFromCursorFormat(cursorConfig *CursorMCPConfig) []*ServerConfig {
 
 // ToolMetadata represents tool information stored in the index
 type ToolMetadata struct {
-	Name        string           `json:"name"`
-	ServerName  string           `json:"server_name"`
-	Description string           `json:"description"`
-	ParamsJSON  string           `json:"params_json"`
-	Hash        string           `json:"hash"`
-	Created     time.Time        `json:"created"`
-	Updated     time.Time        `json:"updated"`
-	Annotations *ToolAnnotations `json:"annotations,omitempty"`
+	Name             string           `json:"name"`
+	ServerName       string           `json:"server_name"`
+	Description      string           `json:"description"`
+	ParamsJSON       string           `json:"params_json"`
+	OutputSchemaJSON string           `json:"output_schema_json,omitempty"`
+	Hash             string           `json:"hash"`
+	Created          time.Time        `json:"created"`
+	Updated          time.Time        `json:"updated"`
+	Annotations      *ToolAnnotations `json:"annotations,omitempty"`
 }
 
 // ToolAnnotations represents MCP tool behavior hints

internal/hash/hash.go

@@ -7,31 +7,103 @@ import (
 	"fmt"
 )
 
-// ToolHash computes SHA-256 hash for tool change detection
-// Format: sha256(serverName + toolName + description + parametersSchemaJSON)
+type toolHashContract struct {
+	ServerName       string          `json:"server_name"`
+	ToolName         string          `json:"tool_name"`
+	Description      string          `json:"description"`
+	InputSchema      json.RawMessage `json:"input_schema,omitempty"`
+	OutputSchemaJSON json.RawMessage `json:"output_schema,omitempty"`
+}
+
+// ToolHash computes SHA-256 hash for tool change detection.
+// Format: sha256(canonical JSON of serverName, toolName, description, input schema)
 func ToolHash(serverName, toolName, description string, parametersSchema interface{}) (string, error) {
-	// Serialize parameters schema to JSON for consistent hashing
-	var schemaBytes []byte
-	var err error
+	return ToolHashWithOutputSchema(serverName, toolName, description, parametersSchema, "")
+}
 
-	if parametersSchema != nil {
-		schemaBytes, err = json.Marshal(parametersSchema)
-		if err != nil {
-			return "", fmt.Errorf("failed to marshal parameters schema: %w", err)
-		}
+// ToolHashWithOutputSchema computes SHA-256 hash for the full tool contract.
+// Output schema is included because it describes the data shape returned to the
+// agent and therefore belongs to the human-approved tool contract.
+// Format: sha256(canonical JSON of serverName, toolName, description, input schema, output schema)
+func ToolHashWithOutputSchema(serverName, toolName, description string, parametersSchema interface{}, outputSchemaJSON string) (string, error) {
+	inputSchema, err := canonicalSchemaFromInterface(parametersSchema)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal parameters schema: %w", err)
 	}
 
-	// Combine server name, tool name, description, and schema JSON
-	combined := serverName + toolName + description + string(schemaBytes)
+	outputSchema, err := canonicalSchemaFromString(outputSchemaJSON)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal output schema: %w", err)
+	}
+
+	contract := toolHashContract{
+		ServerName:       serverName,
+		ToolName:         toolName,
+		Description:      description,
+		InputSchema:      inputSchema,
+		OutputSchemaJSON: outputSchema,
+	}
+
+	contractBytes, err := json.Marshal(contract)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal tool hash contract: %w", err)
+	}
 
-	// Compute SHA-256 hash
 	hasher := sha256.New()
-	hasher.Write([]byte(combined))
+	hasher.Write(contractBytes)
 	hashBytes := hasher.Sum(nil)
 
 	return hex.EncodeToString(hashBytes), nil
 }
 
+func canonicalSchemaFromInterface(schema interface{}) (json.RawMessage, error) {
+	if schema == nil {
+		return nil, nil
+	}
+
+	var raw json.RawMessage
+	switch value := schema.(type) {
+	case json.RawMessage:
+		raw = value
+	case []byte:
+		raw = value
+	case string:
+		raw = []byte(value)
+	default:
+		data, err := json.Marshal(value)
+		if err != nil {
+			return nil, err
+		}
+		raw = data
+	}
+
+	return canonicalSchemaFromBytes(raw)
+}
+
+func canonicalSchemaFromString(schemaJSON string) (json.RawMessage, error) {
+	if schemaJSON == "" {
+		return nil, nil
+	}
+	return canonicalSchemaFromBytes([]byte(schemaJSON))
+}
+
+func canonicalSchemaFromBytes(schemaJSON []byte) (json.RawMessage, error) {
+	if len(schemaJSON) == 0 {
+		return nil, nil
+	}
+
+	var parsed interface{}
+	if err := json.Unmarshal(schemaJSON, &parsed); err != nil {
+		return nil, err
+	}
+
+	canonical, err := json.Marshal(parsed)
+	if err != nil {
+		return nil, err
+	}
+	return json.RawMessage(canonical), nil
+}
+
 // StringHash computes SHA-256 hash of a string
 func StringHash(input string) string {
 	hasher := sha256.New()
@@ -60,7 +132,12 @@ func VerifyToolHash(serverName, toolName, description string, parametersSchema i
 
 // ComputeToolHash computes a SHA256 hash for a tool (alias for ToolHash that doesn't return error)
 func ComputeToolHash(serverName, toolName, description string, inputSchema interface{}) string {
-	hash, err := ToolHash(serverName, toolName, description, inputSchema)
+	return ComputeToolHashWithOutputSchema(serverName, toolName, description, inputSchema, "")
+}
+
+// ComputeToolHashWithOutputSchema computes a SHA256 hash for a tool including output schema.
+func ComputeToolHashWithOutputSchema(serverName, toolName, description string, inputSchema interface{}, outputSchemaJSON string) string {
+	hash, err := ToolHashWithOutputSchema(serverName, toolName, description, inputSchema, outputSchemaJSON)
 	if err != nil {
 		// If hashing fails, return a default hash based on server and tool name
 		fallback := StringHash(fmt.Sprintf("%s:%s", serverName, toolName))

internal/hash/hash_test.go

@@ -136,6 +136,27 @@ func TestComputeToolHash_FallbackOnMarshalError(t *testing.T) {
 	assert.NotEmpty(t, hash, "Should return fallback hash on marshal error")
 }
 
+func TestComputeToolHashWithOutputSchema_CanonicalizesOutputSchemaJSON(t *testing.T) {
+	inputSchema := map[string]interface{}{"type": "object"}
+
+	hash1 := ComputeToolHashWithOutputSchema("server", "tool", "desc", inputSchema, `{"type":"object","properties":{"url":{"type":"string"}}}`)
+	hash2 := ComputeToolHashWithOutputSchema("server", "tool", "desc", inputSchema, `{
+		"properties": {"url": {"type": "string"}},
+		"type": "object"
+	}`)
+
+	assert.Equal(t, hash1, hash2, "Semantically identical output schemas should hash the same")
+}
+
+func TestToolHashWithOutputSchema_UsesStructuredEncoding(t *testing.T) {
+	hash1, err := ToolHashWithOutputSchema("ab", "c", "d", map[string]interface{}{"type": "object"}, `{"type":"object"}`)
+	require.NoError(t, err)
+	hash2, err := ToolHashWithOutputSchema("a", "bc", "d", map[string]interface{}{"type": "object"}, `{"type":"object"}`)
+	require.NoError(t, err)
+
+	assert.NotEqual(t, hash1, hash2, "Different contract field tuples must not collide through string concatenation")
+}
+
 func TestComputeToolHash_DescriptionOnlyChange(t *testing.T) {
 	schema := map[string]interface{}{
 		"type": "object",

internal/index/bleve.go

@@ -21,14 +21,15 @@ type BleveIndex struct {
 
 // ToolDocument represents a tool document in the index
 type ToolDocument struct {
-	ToolName       string `json:"tool_name"`      // Just the tool name (without server prefix)
-	FullToolName   string `json:"full_tool_name"` // Complete server:tool format
-	ServerName     string `json:"server_name"`
-	Description    string `json:"description"`
-	ParamsJSON     string `json:"params_json"`
-	Hash           string `json:"hash"`
-	Tags           string `json:"tags"`
-	SearchableText string `json:"searchable_text"` // Combined searchable content
+	ToolName         string `json:"tool_name"`      // Just the tool name (without server prefix)
+	FullToolName     string `json:"full_tool_name"` // Complete server:tool format
+	ServerName       string `json:"server_name"`
+	Description      string `json:"description"`
+	ParamsJSON       string `json:"params_json"`
+	OutputSchemaJSON string `json:"output_schema_json,omitempty"`
+	Hash             string `json:"hash"`
+	Tags             string `json:"tags"`
+	SearchableText   string `json:"searchable_text"` // Combined searchable content
 }
 
 // NewBleveIndex creates a new Bleve index
@@ -147,14 +148,15 @@ func (b *BleveIndex) IndexTool(toolMeta *config.ToolMetadata) error {
 		toolMeta.ParamsJSON)
 
 	doc := &ToolDocument{
-		ToolName:       toolName,
-		FullToolName:   toolMeta.Name,
-		ServerName:     toolMeta.ServerName,
-		Description:    toolMeta.Description,
-		ParamsJSON:     toolMeta.ParamsJSON,
-		Hash:           toolMeta.Hash,
-		Tags:           "", // Can be extended later
-		SearchableText: searchableText,
+		ToolName:         toolName,
+		FullToolName:     toolMeta.Name,
+		ServerName:       toolMeta.ServerName,
+		Description:      toolMeta.Description,
+		ParamsJSON:       toolMeta.ParamsJSON,
+		OutputSchemaJSON: toolMeta.OutputSchemaJSON,
+		Hash:             toolMeta.Hash,
+		Tags:             "", // Can be extended later
+		SearchableText:   searchableText,
 	}
 
 	// Use server:tool format as document ID for uniqueness
@@ -249,7 +251,7 @@ func (b *BleveIndex) SearchTools(queryStr string, limit int) ([]*config.SearchRe
 	// Create search request
 	searchReq := bleve.NewSearchRequest(boolQuery)
 	searchReq.Size = limit
-	searchReq.Fields = []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "hash"}
+	searchReq.Fields = []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "output_schema_json", "hash"}
 	searchReq.Highlight = bleve.NewHighlight()
 
 	b.logger.Debug("Searching tools with enhanced query", zap.String("query", queryStr), zap.Int("limit", limit))
@@ -263,11 +265,12 @@ func (b *BleveIndex) SearchTools(queryStr string, limit int) ([]*config.SearchRe
 	var results []*config.SearchResult
 	for _, hit := range searchResult.Hits {
 		toolMeta := &config.ToolMetadata{
-			Name:        getStringField(hit.Fields, "full_tool_name"),
-			ServerName:  getStringField(hit.Fields, "server_name"),
-			Description: getStringField(hit.Fields, "description"),
-			ParamsJSON:  getStringField(hit.Fields, "params_json"),
-			Hash:        getStringField(hit.Fields, "hash"),
+			Name:             getStringField(hit.Fields, "full_tool_name"),
+			ServerName:       getStringField(hit.Fields, "server_name"),
+			Description:      getStringField(hit.Fields, "description"),
+			ParamsJSON:       getStringField(hit.Fields, "params_json"),
+			OutputSchemaJSON: getStringField(hit.Fields, "output_schema_json"),
+			Hash:             getStringField(hit.Fields, "hash"),
 		}
 
 		results = append(results, &config.SearchResult{