refactor(cli): extract suggestion-engine utilities (Commit 2.12)

Author: brandonkachen

REFACTORING_PLAN.md

@@ -42,7 +42,7 @@ This document outlines a prioritized refactoring plan for the 51 issues identifi
 | 2.9 | Refactor doStream | ✅ Complete | Codebuff |
 | 2.10 | DRY up OpenRouter stream handling | ⏭️ Skipped | - |
 | 2.11 | Consolidate image handling | ✅ Not Needed | - |
-| 2.12 | Refactor suggestion-engine | ⬜ Not Started | - |
+| 2.12 | Refactor suggestion-engine | ✅ Complete | Codebuff |
 | 2.13 | Fix browser actions + string utils | ⬜ Not Started | - |
 | 2.14 | Refactor agent-builder.ts | ⬜ Not Started | - |
 | 2.15 | Refactor promptAiSdkStream | ⬜ Not Started | - |
@@ -937,19 +937,58 @@ No duplication found. Architecture follows single responsibility principle.
 
 ---
 
-### Commit 2.12: Refactor `use-suggestion-engine.ts`
+### Commit 2.12: Refactor `use-suggestion-engine.ts` ✅ COMPLETE
 **Files:** `cli/src/hooks/use-suggestion-engine.ts`  
 **Est. Time:** 2-3 hours  
-**Est. LOC Changed:** ~350-450
+**Actual Time:** ~1.5 hours  
+**Est. LOC Changed:** ~350-450  
+**Actual LOC Changed:** ~450 lines extracted (130 parsing + 320 filtering)
 
-| Task | Description |
-|------|-------------|
-| Extract `useSuggestionCache` hook | Caching logic |
-| Extract `useSuggestionRanking` hook | Ranking algorithms |
-| Extract `useSuggestionFiltering` hook | Filter logic |
-| Compose in main hook | Wire up |
+> **Note:** Plan originally called for extracting hooks (`useSuggestionCache`, etc.), but pure utility modules were more appropriate since the logic is stateless.
+
+| Task | Description | Status |
+|------|-------------|--------|
+| Create `suggestion-parsing.ts` | Parsing functions: parseSlashContext, parseMentionContext, isInsideStringDelimiters, parseAtInLine | ✅ |
+| Create `suggestion-filtering.ts` | Filtering functions: filterSlashCommands, filterAgentMatches, filterFileMatches, helpers | ✅ |
+| Update main hook | Import from extracted modules, re-export types for consumers | ✅ |
+| Run tests | 100 suggestion engine tests pass, 1902 CLI tests pass | ✅ |
+| Multi-agent review | Code-reviewer-multi-prompt reviewed extraction boundaries | ✅ |
 
-**Dependencies:** None (can run in parallel with 2.11)  
+**New Files Created:**
+- `cli/src/utils/suggestion-parsing.ts` (~130 lines) - Parsing utilities:
+  - `TriggerContext` interface - trigger state for slash/mention
+  - `parseSlashContext()` - parse `/command` triggers
+  - `parseMentionContext()` - parse `@mention` triggers
+  - `isInsideStringDelimiters()` - check if position is in quotes
+  - `parseAtInLine()` - parse @ in a single line
+- `cli/src/utils/suggestion-filtering.ts` (~320 lines) - Filtering utilities:
+  - `MatchedSlashCommand`, `MatchedAgentInfo`, `MatchedFileInfo` types
+  - `filterSlashCommands()` - filter/rank slash commands with highlighting
+  - `filterAgentMatches()` - filter/rank agents with highlighting
+  - `filterFileMatches()` - filter/rank files with path-segment matching
+  - `flattenFileTree()`, `getFileName()` - file tree helpers
+  - `createHighlightIndices()`, `createPushUnique()` - internal helpers
+
+**Hook Size Reduction:**
+- `use-suggestion-engine.ts`: ~751 → ~220 lines (-71%)
+
+**Architecture Decision:**
+Extracted pure utility modules instead of React hooks (as originally planned) because:
+1. Parsing and filtering logic is stateless - no React dependencies
+2. Pure functions are easier to test in isolation
+3. Better separation of concerns: hook manages React state/effects, utilities do computation
+
+**Review Findings:**
+- ✅ Extraction boundaries well-chosen (parsing vs filtering vs hook)
+- ✅ Types properly re-exported for backward compatibility
+- ⚠️ Fixed: Import path `../utils/local-agent-registry` → `./local-agent-registry`
+
+**Test Results:**
+- 100 suggestion engine tests pass
+- 1902 CLI tests pass
+- TypeScript compiles cleanly
+
+**Dependencies:** None  
 **Risk:** Low  
 **Rollback:** Revert single commit