address feedback: add nil guard, add protected to preserved fields, add depth drop test, review error handling

Author: kerobbi

pkg/github/issues.go

@@ -1613,7 +1613,7 @@ func ListIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 			optimizedIssues, err := response.OptimizeList(minimalIssues)
 			if err != nil {
-				return nil, nil, fmt.Errorf("failed to optimize issues: %w", err)
+				return utils.NewToolResultErrorFromErr("failed to marshal response", err), nil, nil
 			}
 
 			// Wrap optimized issues with pagination metadata

pkg/github/repositories.go

@@ -307,7 +307,9 @@ func ListBranches(t translations.TranslationHelperFunc) inventory.ServerTool {
 				minimalBranches = append(minimalBranches, convertToMinimalBranch(branch))
 			}
 
-			r, err := response.OptimizeList(minimalBranches)
+			r, err := response.OptimizeList(minimalBranches,
+				response.WithPreservedFields("protected"),
+			)
 			if err != nil {
 				return nil, nil, fmt.Errorf("failed to marshal response: %w", err)
 			}

pkg/response/optimize.go

@@ -45,6 +45,10 @@ func WithPreservedFields(fields ...string) OptimizeListOption {
 // OptimizeList optimizes a list of items by applying flattening, URL removal, zero-value removal,
 // whitespace normalization, and fill-rate filtering.
 func OptimizeList[T any](items []T, opts ...OptimizeListOption) ([]byte, error) {
+	if items == nil {
+		return []byte("[]"), nil
+	}
+
 	cfg := OptimizeListConfig{maxDepth: defaultMaxDepth}
 	for _, opt := range opts {
 		opt(&cfg)
@@ -83,6 +87,7 @@ func flattenTo(item map[string]any, maxDepth int) map[string]any {
 }
 
 // flattenInto is the recursive worker for flattenTo.
+// Nested maps at maxDepth are intentionally dropped, as deeply nested data is not useful in list responses.
 func flattenInto(item map[string]any, prefix string, result map[string]any, depth int, maxDepth int) {
 	for key, value := range item {
 		fullKey := prefix + key

pkg/response/optimize_test.go

@@ -69,6 +69,24 @@ func TestFlatten(t *testing.T) {
 			"commit.author.date": "2026-01-01",
 		}, result)
 	})
+
+	t.Run("drops nested maps at maxDepth boundary", func(t *testing.T) {
+		input := map[string]any{
+			"title": "issue",
+			"user": map[string]any{
+				"login": "alice",
+				"org": map[string]any{
+					"name": "acme",
+				},
+			},
+		}
+		result := flattenTo(input, defaultMaxDepth)
+
+		assert.Equal(t, "issue", result["title"])
+		assert.Equal(t, "alice", result["user.login"])
+		assert.Nil(t, result["user.org"], "nested map at maxDepth is dropped")
+		assert.Nil(t, result["user.org.name"], "nested map contents at maxDepth are dropped")
+	})
 }
 
 func TestFilterByFillRate(t *testing.T) {
@@ -153,7 +171,7 @@ func TestOptimizeList_AllStrategies(t *testing.T) {
 func TestOptimizeList_NilInput(t *testing.T) {
 	raw, err := OptimizeList[map[string]any](nil)
 	require.NoError(t, err)
-	assert.Equal(t, "null", string(raw))
+	assert.Equal(t, "[]", string(raw))
 }
 
 func TestOptimizeList_SkipsFillRateBelowMinRows(t *testing.T) {