diff --git a/scripts/tier2/artifacts/module_taxonomy_refactor_20260627/bulk_move.py b/scripts/tier2/artifacts/module_taxonomy_refactor_20260627/bulk_move.py
new file mode 100644
index 00000000..2667e5c0
--- /dev/null
+++ b/scripts/tier2/artifacts/module_taxonomy_refactor_20260627/bulk_move.py
@@ -0,0 +1,103 @@
+"""Bulk-move remaining dataclasses from src/models.py to their target modules.
+
+Phase 3.5-3.9 of module_taxonomy_refactor_20260627.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+ROOT = Path(".")
+MODELS = ROOT / "src" / "models.py"
+
+# Map: (class_name, target_file, optional region_header_for_target)
+MOVES = [
+    ("Tool",                ROOT / "src" / "tool_presets.py",    "#region: Tool + ToolPreset Dataclasses (moved from src/models.py Phase 3.5)"),
+    ("ToolPreset",          ROOT / "src" / "tool_presets.py",    None),
+    ("BiasProfile",         ROOT / "src" / "tool_bias.py",       "#region: BiasProfile Dataclass (moved from src/models.py Phase 3.6)"),
+    ("TextEditorConfig",    ROOT / "src" / "external_editor.py","#region: Editor Config Dataclasses (moved from src/models.py Phase 3.7)"),
+    ("ExternalEditorConfig",ROOT / "src" / "external_editor.py", None),
+    ("MCPServerConfig",     ROOT / "src" / "mcp_client.py",      "#region: MCP Config Dataclasses (moved from src/models.py Phase 3.8)"),
+    ("MCPConfiguration",    ROOT / "src" / "mcp_client.py",      None),
+    ("VectorStoreConfig",   ROOT / "src" / "mcp_client.py",      None),
+    ("RAGConfig",           ROOT / "src" / "mcp_client.py",      None),
+    ("WorkspaceProfile",    ROOT / "src" / "workspace_manager.py","#region: WorkspaceProfile Dataclass (moved from src/models.py Phase 3.9)"),
+]
+
+
+def find_class_block(lines: list[str], class_name: str) -> tuple[int, int]:
+    """Return (start_line, end_line) 0-indexed, [start, end) for the class block.
+
+    Includes the @dataclass decorator line(s) if present.
+    """
+    start = None
+    for i, line in enumerate(lines):
+        if line.startswith(f"class {class_name}:"):
+            start = i
+            break
+    if start is None:
+        raise ValueError(f"Class {class_name} not found")
+    # Look backwards for @dataclass
+    decorator_start = start
+    for i in range(start - 1, -1, -1):
+        line = lines[i].strip()
+        if line.startswith("@dataclass"):
+            decorator_start = i
+            break
+        if line.startswith("class ") or line.startswith("#region:") or line.startswith("#endregion:"):
+            break
+        if line == "":
+            continue
+        break  # non-decorator line
+    # Find end: next class/def at column 0 (excluding inner methods)
+    end = len(lines)
+    for i in range(decorator_start + 1, len(lines)):
+        line = lines[i]
+        if line and not line.startswith(" ") and not line.startswith("\t"):
+            stripped = line.lstrip()
+            if re.match(r"^(class |def |@dataclass|#region:|#endregion:)", stripped):
+                end = i
+                break
+    return decorator_start, end
+
+
+def main() -> None:
+    source = MODELS.read_text(encoding="utf-8")
+    lines = source.splitlines(keepends=True)
+
+    # Verify each class exists first
+    ranges = []
+    for class_name, target_file, region_header in MOVES:
+        s, e = find_class_block(lines, class_name)
+        ranges.append((class_name, target_file, region_header, s, e))
+        print(f"Found {class_name}: lines {s+1}-{e} ({e-s} lines)")
+
+    # Write each target file (append)
+    by_target: dict[Path, list] = {}
+    for class_name, target_file, region_header, s, e in ranges:
+        by_target.setdefault(target_file, []).append((class_name, region_header, s, e))
+
+    for target_file, items in by_target.items():
+        with target_file.open("a", encoding="utf-8") as f:
+            for class_name, region_header, _, _ in items:
+                s, e = find_class_block(lines, class_name)
+                block = "".join(lines[s:e])
+                if region_header:
+                    f.write(f"\n\n{region_header}\n{block}")
+                else:
+                    f.write(f"\n\n{block}")
+        print(f"Appended {len(items)} classes to {target_file}")
+
+    # Remove from models.py in reverse line order
+    sorted_ranges = sorted(ranges, key=lambda r: r[3], reverse=True)
+    new_lines = list(lines)
+    for class_name, _, _, s, e in sorted_ranges:
+        del new_lines[s:e]
+        print(f"Removed {class_name} from models.py")
+
+    MODELS.write_text("".join(new_lines), encoding="utf-8")
+    print("models.py updated")
+
+
+if __name__ == "__main__":
+    main()
\ No newline at end of file
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/migrate_models_attr.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/migrate_models_attr.py
new file mode 100644
index 00000000..8b32a9d8
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/migrate_models_attr.py
@@ -0,0 +1,120 @@
+"""Fix script: replace 'models.<moved_class>' with '<moved_class>' and add imports.
+
+After the migration of 'from src.models import X' to direct imports,
+the 'models.<moved_class>' attribute access pattern still exists in
+many files. The shim previously supported this via __getattr__, but
+Phase 2.3 removed the shim. This script:
+ 1. Finds all 'models.<moved_class>' references
+ 2. For each file, adds 'from src.<destination> import <moved_class>' at
+    the top (if not already present)
+ 3. Replaces 'models.<moved_class>' with '<moved_class>' in the body
+
+NOT touched:
+ - models.GenerateRequest, models.ConfirmRequest (Phase 4)
+ - models.DEFAULT_TOOL_CATEGORIES (Phase 3)
+ - models.PROVIDERS, models.Metadata (kept on models)
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+CLASS_TO_MODULE: dict[str, str] = {
+    "Ticket": "mma",
+    "Track": "mma",
+    "WorkerContext": "mma",
+    "TrackState": "mma",
+    "TrackMetadata": "mma",
+    "ThinkingSegment": "mma",
+    "EMPTY_TRACK_STATE": "mma",
+    "ProjectContext": "project",
+    "ProjectMeta": "project",
+    "ProjectOutput": "project",
+    "ProjectFiles": "project",
+    "ProjectScreenshots": "project",
+    "ProjectDiscussion": "project",
+    "EMPTY_PROJECT_CONTEXT": "project",
+    "FileItem": "project_files",
+    "Preset": "project_files",
+    "ContextPreset": "project_files",
+    "ContextFileEntry": "project_files",
+    "NamedViewPreset": "project_files",
+    "Tool": "tool_presets",
+    "ToolPreset": "tool_presets",
+    "BiasProfile": "tool_bias",
+    "TextEditorConfig": "external_editor",
+    "ExternalEditorConfig": "external_editor",
+    "EMPTY_TEXT_EDITOR_CONFIG": "external_editor",
+    "Persona": "personas",
+    "WorkspaceProfile": "workspace_manager",
+    "MCPServerConfig": "mcp_client",
+    "MCPConfiguration": "mcp_client",
+    "VectorStoreConfig": "mcp_client",
+    "RAGConfig": "mcp_client",
+    "load_mcp_config": "mcp_client",
+}
+
+
+def migrate_file(path: Path) -> int:
+    """Rewrite 'models.<moved_class>' references in path. Returns count of changed lines."""
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return 0
+    original = content
+    used_classes: set[str] = set()
+
+    for cls in CLASS_TO_MODULE:
+        pattern = re.compile(rf"\bmodels\.{re.escape(cls)}\b")
+        if pattern.search(content):
+            content = pattern.sub(cls, content)
+            used_classes.add(cls)
+    if content == original:
+        return 0
+
+    for cls in sorted(used_classes):
+        mod = CLASS_TO_MODULE[cls]
+        import_line = f"from src.{mod} import {cls}"
+        if re.search(rf"^from\s+src\.{re.escape(mod)}\s+import\s+.*\b{re.escape(cls)}\b", content, re.MULTILINE):
+            continue
+        if not re.search(rf"^from\s+src\.{mod}\s+import\s", content, re.MULTILINE):
+            content = re.sub(
+                r"^(from __future__ import annotations\n)",
+                rf"\1{import_line}\n",
+                content,
+                count=1,
+            )
+        else:
+            content = re.sub(
+                rf"^(from\s+src\.{re.escape(mod)}\s+import\s+[^\n]+)$",
+                rf"\1, {cls}",
+                content,
+                count=1,
+                flags=re.MULTILINE,
+            )
+    try:
+        path.write_text(content, encoding="utf-8", newline="")
+    except OSError:
+        return 0
+    return len(used_classes)
+
+
+def main() -> int:
+    root = Path(".")
+    src_files = sorted(root.glob("src/*.py")) + sorted(root.glob("tests/*.py"))
+    total_files = 0
+    total_classes = 0
+    for path in src_files:
+        count = migrate_file(path)
+        if count > 0:
+            total_files += 1
+            total_classes += count
+            print(f"  {path}: {count} class ref(s) updated")
+    print(f"\nTotal: {total_classes} class ref(s) updated in {total_files} file(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_ai_client.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_ai_client.py
new file mode 100644
index 00000000..8e8f5a3e
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_ai_client.py
@@ -0,0 +1,3553 @@
+# ai_client.py
+from __future__ import annotations
+"""
+Note(Gemini):
+Acts as the unified interface for multiple LLM providers (Anthropic, Gemini).
+Abstracts away the differences in how they handle tool schemas, history, and caching.
+
+For Anthropic: aggressively manages the ~200k token limit by manually culling
+stale [FILES UPDATED] entries and dropping the oldest message pairs.
+
+For Gemini: injects the initial context directly into system_instruction
+during chat creation to avoid massive history bloat.
+
+HEAVY IMPORTS (startup_speedup_20260606): The heavy SDKs (anthropic,
+google.genai, openai, google.genai.types, requests) are NOT imported
+at module level. They are warmed on AppController's _io_pool at
+startup and accessed via _require_warmed() below. This keeps the
+main thread's import chain lean and the GUI responsive on startup.
+"""
+
+import importlib
+import asyncio
+import datetime
+import difflib
+import hashlib
+import json
+import os
+import sys
+import threading
+import time
+import tomllib
+from dataclasses import dataclass
+
+# TODO(Ed): Eliminate These?
+from collections import deque
+from pathlib     import Path as _P
+from pathlib     import Path
+from typing      import Optional, Callable, Any, List, Union, cast, Iterable
+
+from src import project_manager
+from src import file_cache
+from src import mcp_client
+from src import mcp_tool_specs
+from src import mma_prompts
+from src import performance_monitor
+from src import project_manager
+from src import provider_state
+from src.events             import EventEmitter
+from src.gemini_cli_adapter import GeminiCliAdapter
+from src.models             import FileItem, ToolPreset, BiasProfile, Tool
+from src.paths              import get_credentials_path
+from src.tool_bias          import ToolBiasEngine
+from src.tool_presets       import ToolPresetManager
+
+# VendorCapabilities, get_capabilities, list_models_for_vendor, register
+# are defined in this file (see '#region: Vendor Capabilities'). Previously
+# imported from src/vendor_capabilities.py (deleted in
+# module_taxonomy_refactor_20260627 Phase 2.1).
+
+PROVIDERS: List[str] = ["gemini", "anthropic", "gemini_cli", "deepseek", "minimax", "qwen", "grok", "llama"]
+
+# _require_warmed lives
+# _require_warmed lives in src/module_loader.py to avoid duplicating the
+# lookup logic across files that need heavy modules. Re-exported here so
+# existing call sites and the T3.1 test (which asserts
+# hasattr(src.ai_client, '_require_warmed')) continue to work.
+from src.module_loader import _require_warmed  # noqa: E402,F401
+from src.result_types  import ErrorInfo, ErrorKind, Result  # noqa: E402,F401
+from src.type_aliases import (
+ CommsLog,
+ CommsLogCallback,
+ CommsLogEntry,
+ FileItem,
+ FileItems,
+ History,
+ HistoryMessage,
+ Metadata,
+ ToolCall,
+ ToolDefinition,
+)
+
+_provider:    str   = "gemini"
+_model:       str   = "gemini-2.5-flash-lite"
+_temperature: float = 0.0
+_top_p:       float = 1.0
+_max_tokens:  int   = 8192
+
+_history_trunc_limit: int = 8000
+
+# Global event emitter for API lifecycle events
+events: EventEmitter = EventEmitter()
+
+#region: Provider Configuration
+
+def set_model_params(temp: float, max_tok: int, trunc_limit: int = 8000, top_p: float = 1.0) -> None:
+ """Sets global generation parameters like temperature and max tokens."""
+ global _temperature, _max_tokens, _history_trunc_limit, _top_p
+ _temperature         = temp
+ _max_tokens          = max_tok
+ _history_trunc_limit = trunc_limit
+ _top_p               = top_p
+
+_gemini_client:            Optional[genai.Client] = None
+_gemini_chat:              Any             = None
+_gemini_cache:             Any             = None
+_gemini_cache_md_hash:     Optional[str]   = None
+_gemini_cache_created_at:  Optional[float] = None
+_gemini_cached_file_paths: list[str]       = []
+
+# Gemini cache TTL in seconds. Caches are created with this TTL and
+# proactively rebuilt at 90% of this value to avoid stale-reference errors.
+_GEMINI_CACHE_TTL: int = 3600
+
+_anthropic_client:       Optional[anthropic.Anthropic] = None
+
+_deepseek_client:       Any                  = None
+
+_minimax_client:       Any                  = None
+
+_qwen_client:       Any                  = None
+_qwen_region:       str            = "china"
+
+_grok_client:       Any                  = None
+
+_llama_client:       Any                  = None
+_llama_base_url:     str = "http://localhost:11434/v1"
+_llama_api_key:      str = "ollama"
+
+_send_lock: threading.Lock = threading.Lock()
+
+_BIAS_ENGINE = ToolBiasEngine()
+_active_tool_preset:  Optional[ToolPreset] = None
+_active_bias_profile: Optional[BiasProfile] = None
+
+_gemini_cli_adapter: Optional[GeminiCliAdapter] = None
+
+# Injected by gui.py - called when AI wants to run a command.
+confirm_and_run_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]], Optional[Callable[[str, str], Result[str]]]], Optional[str]]] = None
+
+# Injected by gui.py - called whenever a comms entry is appended.
+# Use get_comms_log_callback/set_comms_log_callback for thread-safe access.
+comms_log_callback: Optional[CommsLogCallback] = None
+
+# Injected by gui.py - called whenever a tool call completes.
+tool_log_callback: Optional[Callable[[str, str], None]] = None
+
+_local_storage = threading.local()
+
+_tool_approval_modes: dict[str, str] = {}
+
+def get_current_tier_result() -> Result[str]:
+ """Returns the current tier from thread-local storage as a Result."""
+ return Result(data=getattr(_local_storage, "current_tier", None))
+
+def set_current_tier(tier: Optional[str]) -> None:
+ """Sets the current tier in thread-local storage."""
+ _local_storage.current_tier = tier
+
+# Increased to allow thorough code exploration before forcing a summary
+MAX_TOOL_ROUNDS: int = 10
+
+# Maximum cumulative bytes of tool output allowed per send() call.
+_MAX_TOOL_OUTPUT_BYTES: int = 500_000
+
+# Maximum characters per text chunk sent to Anthropic.
+_ANTHROPIC_CHUNK_SIZE: int = 120_000
+
+_SYSTEM_PROMPT: str = (
+ "You are a helpful coding assistant with access to a PowerShell tool (run_powershell) and MCP tools (file access: read_file, list_directory, search_files, get_file_summary, web access: web_search, fetch_url). "
+ "When calling file/directory tools, always use the 'path' parameter for the target path. "
+ "When asked to create or edit files, prefer targeted edits over full rewrites. "
+ "Always explain what you are doing before invoking the tool.\n\n"
+ "When writing or rewriting large files (especially those containing quotes, backticks, or special characters), "
+ "avoid python -c with inline strings. Instead: (1) write a .py helper script to disk using a PS here-string "
+ "(@'...'@ for literal content), (2) run it with `python <script>`, (3) delete the helper. "
+ "For small targeted edits, use PowerShell's (Get-Content) / .Replace() / Set-Content or Add-Content directly.\n\n"
+ "When making function calls using tools that accept array or object parameters "
+ "ensure those are structured using JSON. For example:\n"
+ "When you need to verify a change, rely on the exit code and stdout/stderr from the tool \u2014 "
+ "the user's context files are automatically refreshed after every tool call, so you do NOT "
+ "need to re-read files that are already provided in the <context> block."
+)
+
+_custom_system_prompt:           str = ""
+_base_system_prompt_override:    str = ""
+_use_default_base_system_prompt: bool = True
+_project_context_marker:         str = ""
+
+#endregion: Provider Configuration
+
+#region: Vendor Capabilities (moved from src/vendor_capabilities.py)
+
+@dataclass(frozen=True)
+class VendorCapabilities:
+ vendor:               str
+ model:                str
+ vision:               bool = False
+ tool_calling:         bool = True
+ caching:              bool = False
+ streaming:            bool = True
+ model_discovery:      bool = True
+ context_window:       int = 8192
+ cost_tracking:        bool = True
+ cost_input_per_mtok:  float = 0.0
+ cost_output_per_mtok: float = 0.0
+ notes:                str = ''
+ local:             bool = False
+ reasoning:         bool = False
+ structured_output: bool = False
+ code_execution:    bool = False
+ web_search:        bool = False
+ x_search:          bool = False
+ file_search:       bool = False
+ mcp_support:       bool = False
+ audio:             bool = False
+ video:             bool = False
+ grounding:         bool = False
+ computer_use:      bool = False
+
+_VENDOR_REGISTRY: dict[tuple[str, str], "VendorCapabilities"] = {}
+
+def register(cap: "VendorCapabilities") -> None:
+ _VENDOR_REGISTRY[(cap.vendor, cap.model)] = cap
+
+def get_capabilities(vendor: str, model: str) -> "VendorCapabilities":
+ if (vendor, model) in _VENDOR_REGISTRY: return _VENDOR_REGISTRY[(vendor, model)]
+ if (vendor, '*')   in _VENDOR_REGISTRY: return _VENDOR_REGISTRY[(vendor, '*')]
+ raise KeyError(f'No capabilities registered for vendor={vendor!r} model={model!r}')
+
+def list_models_for_vendor(vendor: str) -> list[str]:
+ return sorted({m for v, m in _VENDOR_REGISTRY if v == vendor and m != '*'})
+
+register(VendorCapabilities(vendor='minimax',   model='*',            context_window=131072, cost_input_per_mtok=0.20, cost_output_per_mtok=0.20))
+register(VendorCapabilities(vendor='minimax',   model='MiniMax-M2.7', context_window=131072, cost_input_per_mtok=0.20, cost_output_per_mtok=0.20, reasoning=True))
+register(VendorCapabilities(vendor='minimax',   model='MiniMax-M2.5', context_window=131072, cost_input_per_mtok=0.20, cost_output_per_mtok=0.20, reasoning=True))
+register(VendorCapabilities(vendor='minimax',   model='MiniMax-M2.1', context_window=131072, cost_input_per_mtok=0.20, cost_output_per_mtok=0.20))
+register(VendorCapabilities(vendor='minimax',   model='MiniMax-M2',   context_window=131072, cost_input_per_mtok=0.20, cost_output_per_mtok=0.20))
+register(VendorCapabilities(vendor='grok',      model='*',                          context_window=131072, cost_input_per_mtok=2.00, cost_output_per_mtok=10.00, web_search=True, x_search=True))
+register(VendorCapabilities(vendor='grok',      model='grok-2',                     context_window=131072,                                                       web_search=True, x_search=True))
+register(VendorCapabilities(vendor='grok',      model='grok-2-vision', vision=True, context_window=32768,                                                        web_search=True, x_search=True))
+register(VendorCapabilities(vendor='grok',      model='grok-beta',                  context_window=131072, cost_input_per_mtok=5.00, cost_output_per_mtok=15.00, web_search=True, x_search=True))
+register(VendorCapabilities(vendor='llama',     model='*',                                         context_window=131072))
+register(VendorCapabilities(vendor='llama',     model='llama-3.1-8b-instant',                      context_window=131072, cost_input_per_mtok=0.05, cost_output_per_mtok=0.08))
+register(VendorCapabilities(vendor='llama',     model='llama-3.1-70b-versatile',                   context_window=131072, cost_input_per_mtok=0.59, cost_output_per_mtok=0.79))
+register(VendorCapabilities(vendor='llama',     model='llama-3.1-405b-reasoning',                  context_window=131072, cost_input_per_mtok=3.00, cost_output_per_mtok=3.00, reasoning=True))
+register(VendorCapabilities(vendor='llama',     model='llama-3.2-1b-preview',                      context_window=131072, cost_input_per_mtok=0.04, cost_output_per_mtok=0.04))
+register(VendorCapabilities(vendor='llama',     model='llama-3.2-3b-preview',                      context_window=131072, cost_input_per_mtok=0.06, cost_output_per_mtok=0.06))
+register(VendorCapabilities(vendor='llama',     model='llama-3.2-11b-vision-preview', vision=True, context_window=131072, cost_input_per_mtok=0.18, cost_output_per_mtok=0.18))
+register(VendorCapabilities(vendor='llama',     model='llama-3.2-90b-vision-preview', vision=True, context_window=131072, cost_input_per_mtok=0.90, cost_output_per_mtok=0.90))
+register(VendorCapabilities(vendor='llama',     model='llama-3.3-70b-specdec',                     context_window=131072, cost_input_per_mtok=0.59, cost_output_per_mtok=0.79))
+register(VendorCapabilities(vendor='qwen',      model='*',                         context_window=32768))
+register(VendorCapabilities(vendor='qwen',      model='qwen-turbo',                context_window=1000000, cost_input_per_mtok=0.05,  cost_output_per_mtok=0.10))
+register(VendorCapabilities(vendor='qwen',      model='qwen-plus',                 context_window=131072,  cost_input_per_mtok=0.40,  cost_output_per_mtok=1.20))
+register(VendorCapabilities(vendor='qwen',      model='qwen-max',                  context_window=32768,   cost_input_per_mtok=2.00,  cost_output_per_mtok=6.00))
+register(VendorCapabilities(vendor='qwen',      model='qwen-long',                 context_window=1000000, cost_input_per_mtok=0.07,  cost_output_per_mtok=0.28, caching=True, notes='qwen-long supports custom chunked long-context caching'))
+register(VendorCapabilities(vendor='qwen',      model='qwen-vl-plus', vision=True, context_window=131072,  cost_input_per_mtok=0.21,  cost_output_per_mtok=0.63))
+register(VendorCapabilities(vendor='qwen',      model='qwen-vl-max', vision=True,  context_window=32768,   cost_input_per_mtok=0.50,  cost_output_per_mtok=1.50))
+register(VendorCapabilities(vendor='qwen',      model='qwen-audio',                context_window=32768,   cost_input_per_mtok=0.10,  cost_output_per_mtok=0.30, audio=True, notes='Audio input support added 2026-06-11 (v2 matrix)'))
+register(VendorCapabilities(vendor='anthropic', model='*',                          context_window=200000, cost_input_per_mtok=3.00,  cost_output_per_mtok=15.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True, notes='Anthropic wildcard: Sonnet defaults. Per-model variations below.'))
+register(VendorCapabilities(vendor='anthropic', model='claude-sonnet-4-5-20250929', context_window=200000, cost_input_per_mtok=3.00,  cost_output_per_mtok=15.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-sonnet-4-20250514',   context_window=200000, cost_input_per_mtok=3.00,  cost_output_per_mtok=15.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-sonnet-4-6',          context_window=200000, cost_input_per_mtok=3.00,  cost_output_per_mtok=15.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-1-20250805',   context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-20250514',     context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-5-20251101',   context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-6',            context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-7',            context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-opus-4-8',            context_window=200000, cost_input_per_mtok=15.00, cost_output_per_mtok=75.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-haiku-4-5-20251001',  context_window=200000, cost_input_per_mtok=1.00,  cost_output_per_mtok=5.00,  caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='anthropic', model='claude-fable-5',         context_window=200000,  cost_input_per_mtok=3.00,  cost_output_per_mtok=15.00, caching=True, structured_output=True, file_search=True, mcp_support=True, computer_use=True))
+register(VendorCapabilities(vendor='gemini',    model='*',                      context_window=1000000, cost_input_per_mtok=1.25,  cost_output_per_mtok=5.00,  caching=True, vision=True, video=True, audio=True, grounding=True, structured_output=True, notes='Gemini wildcard: 1M+ context window. Per-model variations below.'))
+register(VendorCapabilities(vendor='gemini',    model='gemini-3.1-pro-preview', context_window=1000000, cost_input_per_mtok=3.50,  cost_output_per_mtok=10.50, caching=True, vision=True, video=True, audio=True, grounding=True, structured_output=True))
+register(VendorCapabilities(vendor='gemini',    model='gemini-3-flash-preview', context_window=1000000, cost_input_per_mtok=0.15,  cost_output_per_mtok=0.60,  caching=True, vision=True, video=True, audio=True, grounding=True, structured_output=True))
+register(VendorCapabilities(vendor='gemini',    model='gemini-2.5-flash',       context_window=1000000, cost_input_per_mtok=0.15,  cost_output_per_mtok=0.60,  caching=True, vision=True, video=True, audio=True, grounding=True, structured_output=True))
+register(VendorCapabilities(vendor='gemini',    model='gemini-2.5-flash-lite',  context_window=1000000, cost_input_per_mtok=0.075, cost_output_per_mtok=0.30,  caching=True, vision=True,                         grounding=True, structured_output=True))
+register(VendorCapabilities(vendor='deepseek',  model='*',                 context_window=32768, cost_input_per_mtok=0.27, cost_output_per_mtok=1.10, reasoning=True, structured_output=True, notes='DeepSeek wildcard: V3 defaults. R1/reasoner variants below.'))
+register(VendorCapabilities(vendor='deepseek',  model='deepseek-v3',       context_window=32768, cost_input_per_mtok=0.27, cost_output_per_mtok=1.10,                 structured_output=True))
+register(VendorCapabilities(vendor='deepseek',  model='deepseek-reasoner', context_window=32768, cost_input_per_mtok=0.55, cost_output_per_mtok=2.19, reasoning=True, structured_output=True))
+register(VendorCapabilities(vendor='deepseek',  model='deepseek-r1',       context_window=32768, cost_input_per_mtok=0.55, cost_output_per_mtok=2.19, reasoning=True, structured_output=True))
+
+#endregion: Vendor Capabilities
+
+#region: Vendor State (moved from src/vendor_state.py)
+
+@dataclass(frozen=True)
+class VendorMetric:
+ key:     str
+ label:   str
+ value:   str
+ state:   str
+ tooltip: str
+
+#endregion: Vendor State
+
+#region: System Prompt Management
+
+def set_custom_system_prompt(prompt: str) -> None:
+ """Sets a custom system prompt to be combined with the default instructions."""
+ global _custom_system_prompt
+ _custom_system_prompt = prompt
+
+def set_base_system_prompt(prompt: str) -> None:
+ global _base_system_prompt_override
+ _base_system_prompt_override = prompt
+
+def set_use_default_base_prompt(use_default: bool) -> None:
+ global _use_default_base_system_prompt
+ _use_default_base_system_prompt = use_default
+
+def set_project_context_marker(marker: str) -> None:
+ global _project_context_marker
+ _project_context_marker = marker
+
+def _get_context_marker() -> str:
+ return _project_context_marker if _project_context_marker.strip() else "[SYSTEM: FILES UPDATED]"
+
+def _get_combined_system_prompt(preset: Optional[ToolPreset] = None, bias: Optional[BiasProfile] = None) -> str:
+ if preset is None: preset = _active_tool_preset
+ if bias   is None: bias   = _active_bias_profile
+ if _use_default_base_system_prompt:
+  base = _SYSTEM_PROMPT
+ else:
+  base = _base_system_prompt_override
+ if _custom_system_prompt.strip():
+  base = f"{base}\n\n[USER SYSTEM PROMPT]\n{_custom_system_prompt}"
+ if preset and bias:
+  strategy = _BIAS_ENGINE.generate_tooling_strategy(preset, bias)
+  if strategy:
+   base += f"\n\n{strategy}"
+ return base
+
+def get_combined_system_prompt(preset: Optional[ToolPreset] = None, bias: Optional[BiasProfile] = None) -> str:
+ return _get_combined_system_prompt(preset, bias)
+
+_comms_log: deque[CommsLogEntry] = deque(maxlen=1000)
+
+COMMS_CLAMP_CHARS: int = 300
+
+#endregion: System Prompt Management
+
+#region: Comms Log
+
+def get_comms_log_callback_result() -> Result[CommsLogCallback]:
+ tl_cb = getattr(_local_storage, "comms_log_callback", None)
+ if tl_cb: return Result(data=tl_cb)
+ return Result(data=comms_log_callback)
+
+def set_comms_log_callback(cb: Optional[CommsLogCallback]) -> None:
+ global comms_log_callback
+ comms_log_callback = cb
+ _local_storage.comms_log_callback = cb
+
+def _append_comms(direction: str, kind: str, payload: Metadata) -> None:
+ entry: Metadata = {
+  "ts":          datetime.datetime.now().strftime("%H:%M:%S"),
+  "direction":   direction,
+  "kind":        kind,
+  "provider":    _provider,
+  "model":       _model,
+  "payload":     payload,
+  "source_tier": get_current_tier_result().data,
+  "local_ts":    time.time(),
+ }
+ _comms_log.append(entry)
+ _cb = get_comms_log_callback_result().data
+ if _cb is not None:
+  _cb(entry)
+
+def get_comms_log() -> list[Metadata]:
+ return list(_comms_log)
+
+def clear_comms_log() -> None:
+ _comms_log.clear()
+
+def get_credentials_path() -> Path:
+ return Path(os.environ.get("SLOP_CREDENTIALS", str(Path(__file__).parent.parent / "credentials.toml")))
+
+def _load_credentials() -> Metadata:
+ cred_path = get_credentials_path()
+ try:
+  with open(cred_path, "rb") as f:
+   return tomllib.load(f)
+ except FileNotFoundError as e:
+  raise FileNotFoundError(
+   f"Credentials file not found: {cred_path}\n"
+   f"Create a credentials.toml with:\n"
+   f"  [gemini]\n  api_key = \"your-key\"\n"
+   f"  [anthropic]\n  api_key = \"your-key\"\n"
+   f"  [deepseek]\n  api_key = \"your-key\"\n"
+   f"  [minimax]\n  api_key = \"your-key\"\n"
+   f"Or set SLOP_CREDENTIALS env var to a custom path."
+  ) from e
+
+def _try_warm_sdk_result(name: str) -> Result[Any]:
+ """Try to get a warmed SDK module. Returns Result[Any].
+
+ Lazy-loading sentinel: the caller checks result.ok and uses result.data
+ on success. On failure, returns Result(errors=[ErrorInfo]). The caller
+ falls back to body-string matching, preserving the original behavior.
+ Per Phase 11 anti-sliming protocol: NOT a sentinel-None return; the
+ caller observes the Result explicitly.
+ """
+ try:
+  return Result(data=_require_warmed(name))
+ except (ImportError, AttributeError) as e:
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"SDK module '{name}' unavailable: {e}", source=f"ai_client._try_warm_sdk_result", original=e)],
+  )
+
+def _classify_anthropic_error(exc: Exception, source: str = "ai_client.anthropic") -> ErrorInfo:
+ sdk_result = _try_warm_sdk_result("anthropic")
+ if sdk_result.ok:
+  anthropic = sdk_result.data
+  if isinstance(exc, anthropic.RateLimitError):        return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=str(exc), source=source, original=exc)
+  if isinstance(exc, anthropic.AuthenticationError):   return ErrorInfo(kind=ErrorKind.AUTH,       message=str(exc), source=source, original=exc)
+  if isinstance(exc, anthropic.PermissionDeniedError): return ErrorInfo(kind=ErrorKind.AUTH,       message=str(exc), source=source, original=exc)
+  if isinstance(exc, anthropic.APIConnectionError):    return ErrorInfo(kind=ErrorKind.NETWORK,    message=str(exc), source=source, original=exc)
+  if isinstance(exc, anthropic.APIStatusError):
+   status = getattr(exc, "status_code", 0)
+   body = str(exc).lower()
+   if status == 429:        return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=str(exc), source=source, original=exc)
+   if status in (401, 403): return ErrorInfo(kind=ErrorKind.AUTH,       message=str(exc), source=source, original=exc)
+   if status == 402:        return ErrorInfo(kind=ErrorKind.BALANCE,    message=str(exc), source=source, original=exc)
+   if "credit" in body or "balance" in body or "billing" in body: return ErrorInfo(kind=ErrorKind.BALANCE, message=str(exc), source=source, original=exc)
+   if "quota" in body or "limit" in body or "exceeded" in body:   return ErrorInfo(kind=ErrorKind.QUOTA, message=str(exc), source=source, original=exc)
+ return ErrorInfo(kind=ErrorKind.UNKNOWN, message=str(exc), source=source, original=exc)
+
+def _classify_gemini_error(exc: Exception, source: str = "ai_client.gemini") -> ErrorInfo:
+ body = str(exc).lower()
+ sdk_result = _try_warm_sdk_result("google.api_core.exceptions")
+ if sdk_result.ok:
+  gac = sdk_result.data
+  if isinstance(exc, gac.ResourceExhausted):                       return ErrorInfo(kind=ErrorKind.QUOTA,      message=str(exc), source=source, original=exc)
+  if isinstance(exc, gac.TooManyRequests):                         return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=str(exc), source=source, original=exc)
+  if isinstance(exc, (gac.Unauthenticated, gac.PermissionDenied)): return ErrorInfo(kind=ErrorKind.AUTH,       message=str(exc), source=source, original=exc)
+  if isinstance(exc, gac.ServiceUnavailable):                      return ErrorInfo(kind=ErrorKind.NETWORK,    message=str(exc), source=source, original=exc)
+ if "429"        in body or  "quota"   in body or "resource exhausted" in body: return ErrorInfo(kind=ErrorKind.QUOTA, message=str(exc), source=source, original=exc)
+ if "rate"       in body and "limit"   in body:                                 return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=str(exc), source=source, original=exc)
+ if "401"        in body or  "403"     in body or "api key"     in body or "unauthenticated" in body: return ErrorInfo(kind=ErrorKind.AUTH, message=str(exc), source=source, original=exc)
+ if "402"        in body or  "billing" in body or "balance"     in body or "payment"     in body:         return ErrorInfo(kind=ErrorKind.BALANCE, message=str(exc), source=source, original=exc)
+ if "connection" in body or "timeout"  in body or "unreachable" in body:                              return ErrorInfo(kind=ErrorKind.NETWORK, message=str(exc), source=source, original=exc)
+ return ErrorInfo(kind=ErrorKind.UNKNOWN, message=str(exc), source=source, original=exc)
+
+def _classify_deepseek_error(exc: Exception, source: str = "ai_client.deepseek") -> ErrorInfo:
+ requests = _require_warmed("requests")
+ body = ""
+ if isinstance(exc, requests.exceptions.HTTPError) and exc.response is not None:
+  try:
+   # Try to get the detailed error from DeepSeek's JSON response
+   err_data = exc.response.json()
+   if "error" in err_data: body = str(err_data["error"].get("message", exc.response.text))
+   else:                   body = exc.response.text
+  except (ValueError, AttributeError) as e:
+   # JSON parse failed; cannot classify specific error codes.
+   # Return structured UNKNOWN error with original exception preserved.
+   return ErrorInfo(kind=ErrorKind.UNKNOWN, message=exc.response.text, source=source, original=e)
+ else:
+  body = str(exc)
+ 
+ body_l = body.lower()
+ if "429"        in body_l or "rate"           in body_l:                                            return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=body, source=source, original=exc)
+ if "401"        in body_l or "403"            in body_l or "auth" in body_l or "api key" in body_l: return ErrorInfo(kind=ErrorKind.AUTH,       message=body, source=source, original=exc)
+ if "402"        in body_l or "balance"        in body_l or "billing" in body_l:                     return ErrorInfo(kind=ErrorKind.BALANCE,    message=body, source=source, original=exc)
+ if "quota"      in body_l or "limit exceeded" in body_l:                                            return ErrorInfo(kind=ErrorKind.QUOTA,      message=body, source=source, original=exc)
+ if "connection" in body_l or "timeout"        in body_l or "network" in body_l:                     return ErrorInfo(kind=ErrorKind.NETWORK,    message=body, source=source, original=exc)
+ # If we have a body for a 400 error, wrap it
+ if "400" in body_l or "bad request" in body_l: return ErrorInfo(kind=ErrorKind.UNKNOWN, message=f"DeepSeek Bad Request: {body}", source=source, original=exc)
+ return ErrorInfo(kind=ErrorKind.UNKNOWN, message=body, source=source, original=exc)
+
+def _classify_minimax_error(exc: Exception, source: str = "ai_client.minimax") -> ErrorInfo:
+ requests = _require_warmed("requests")
+ body = ""
+ if isinstance(exc, requests.exceptions.HTTPError) and exc.response is not None:
+  try:
+   err_data = exc.response.json()
+   if "error" in err_data: body = str(err_data["error"].get("message", exc.response.text))
+   else:                   body = exc.response.text
+  except (ValueError, AttributeError) as e:
+   return ErrorInfo(kind=ErrorKind.UNKNOWN, message=exc.response.text, source=source, original=e)
+ else:
+  body = str(exc)
+ 
+ body_l = body.lower()
+ if "429"        in body_l or "rate"           in body_l:                                            return ErrorInfo(kind=ErrorKind.RATE_LIMIT, message=body, source=source, original=exc)
+ if "401"        in body_l or "403"            in body_l or "auth" in body_l or "api key" in body_l: return ErrorInfo(kind=ErrorKind.AUTH, message=body, source=source, original=exc)
+ if "402"        in body_l or "balance"        in body_l or "billing" in body_l: return ErrorInfo(kind=ErrorKind.BALANCE, message=body, source=source, original=exc)
+ if "quota"      in body_l or "limit exceeded" in body_l:                        return ErrorInfo(kind=ErrorKind.QUOTA, message=body, source=source, original=exc)
+ if "connection" in body_l or "timeout"        in body_l or "network" in body_l: return ErrorInfo(kind=ErrorKind.NETWORK, message=body, source=source, original=exc)
+ 
+ if "400" in body_l or "bad request" in body_l: return ErrorInfo(kind=ErrorKind.UNKNOWN, message=f"MiniMax Bad Request: {body}", source=source, original=exc)
+ return ErrorInfo(kind=ErrorKind.UNKNOWN, message=body, source=source, original=exc)
+
+def _set_minimax_provider_result(model: str) -> Result[list[str]]:
+ """Load minimax credentials and fetch the list of valid models.
+
+ Returns the list of valid model names. On credentials load failure,
+ returns Result(data=[], errors=[ErrorInfo(...)]). The legacy caller
+ (set_provider) inspects result.ok to decide whether to use the
+ fetched list or fall back to _list_minimax_models_result("") for empty key.
+ """
+ try:
+  creds = _load_credentials()
+  api_key = creds.get("minimax", {}).get("api_key", "")
+  return Result(data=_list_minimax_models_result(api_key).data)
+ except (OSError, ValueError) as e:
+  return Result(
+   data=[],
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to load minimax credentials: {e}", source="ai_client._set_minimax_provider_result", original=e)],
+  )
+
+
+def set_provider(provider: str, model: str, validate: bool = True) -> None:
+ """Updates the active LLM provider and model name.
+
+ When validate is True (default), the model is checked against the provider's
+ LIVE model list, which for gemini_cli/minimax means a blocking subprocess /
+ network call (and importing the provider SDK). Pass validate=False during
+ startup so the GUI's first frame is not blocked ΓÇö AppController._fetch_models
+ corrects the model against the live list shortly after, off the main thread.
+ """
+ global _provider, _model
+ _provider = provider
+ if not validate:
+  _model = model
+  return
+ if provider == "gemini_cli":
+  valid_models = _list_gemini_cli_models()
+  if model != "mock" and (model not in valid_models or model.startswith("deepseek")):
+   _model = "gemini-3-flash-preview"
+  else:
+   _model = model
+ elif provider == "minimax":
+  result = _set_minimax_provider_result(model)
+  fallback_result = _list_minimax_models_result("")
+  valid_models = result.data if result.ok else fallback_result.data
+  if model not in valid_models:
+   _model = "MiniMax-M2.5"
+  else:
+   _model = model
+ else:
+  _model = model
+
+def get_provider() -> str:
+ """Returns the current active provider name."""
+ return _provider
+
+def cleanup() -> None:
+ """Performs cleanup operations like deleting server-side Gemini caches."""
+ global _gemini_client,    _gemini_cache, _gemini_cached_file_paths
+ if     _gemini_client and _gemini_cache:
+  _delete_gemini_cache_result()
+ _gemini_cached_file_paths = []
+
+def reset_session() -> None:
+ """Clears conversation history and resets provider-specific session state."""
+ global _gemini_client,        _gemini_chat,            _gemini_cache
+ global _gemini_cache_md_hash, _gemini_cache_created_at, _gemini_cached_file_paths
+ global _anthropic_client
+ global _deepseek_client
+ global _minimax_client
+ global _qwen_client
+ global _CACHED_ANTHROPIC_TOOLS, _CACHED_DEEPSEEK_TOOLS
+ global _gemini_cli_adapter
+ if _gemini_client and _gemini_cache:
+  _delete_gemini_cache_result()
+ _gemini_client            = None
+ _gemini_chat              = None
+ _gemini_cache             = None
+ _gemini_cache_md_hash     = None
+ _gemini_cache_created_at  = None
+ _gemini_cached_file_paths = []
+
+ # Preserve binary_path if adapter exists
+ old_path            = _gemini_cli_adapter.binary_path if _gemini_cli_adapter else "gemini"
+ _gemini_cli_adapter = GeminiCliAdapter(binary_path=old_path)
+
+ _anthropic_client = None
+ provider_state.clear_all()
+ _deepseek_client    = None
+ _minimax_client    = None
+ _qwen_client    = None
+ _grok_client = None
+ _llama_client  = None
+ _llama_base_url = "http://localhost:11434/v1"
+ _llama_api_key  = "ollama"
+ _CACHED_ANTHROPIC_TOOLS = None
+ _CACHED_DEEPSEEK_TOOLS  = None
+ file_cache.reset_client()
+
+def list_models(provider: str) -> list[str]:
+ creds = _load_credentials()
+ if   provider == "gemini":
+  result = _list_gemini_models_result(creds["gemini"]["api_key"])
+  return result.data if result.ok else []
+ elif provider == "anthropic":
+  result = _list_anthropic_models_result()
+  return result.data if result.ok else []
+ elif provider == "deepseek":   return _list_deepseek_models(creds["deepseek"]["api_key"])
+ elif provider == "gemini_cli": return _list_gemini_cli_models()
+ elif provider == "minimax":
+  result = _list_minimax_models_result(creds["minimax"]["api_key"])
+  return result.data if result.ok else []
+ elif provider == "qwen":       return _list_qwen_models()
+ elif provider == "grok":       return _list_grok_models()
+ elif provider == "llama":      return _list_llama_models()
+ return []
+
+#endregion: Comms Log
+
+TOOL_NAME: str = "run_powershell"
+
+_agent_tools: dict[str, bool] = {}
+
+#region: Tool Configuration
+
+def set_agent_tools(tools: dict[str, bool]) -> None:
+ """Configures which tools are enabled for the AI agent."""
+ global _agent_tools, _CACHED_ANTHROPIC_TOOLS, _CACHED_DEEPSEEK_TOOLS
+ _agent_tools            = tools
+ _CACHED_ANTHROPIC_TOOLS = None
+ _CACHED_DEEPSEEK_TOOLS  = None
+
+def _set_tool_preset_result(preset_name: Optional[str]) -> Result[None]:
+ """Load a tool preset by name and apply it. Returns Result[None].
+
+ On I/O or parsing failure, returns Result(data=None, errors=[ErrorInfo])
+ capturing the original exception. The legacy caller (set_tool_preset)
+ calls this helper for the load step; on Result errors, the caller still
+ completes (state remains partially-set; the cache invalidation runs).
+
+ IMPORTANT: This function MODIFIES module-level globals (_active_tool_preset,
+ _tool_approval_modes, _agent_tools). Without 'global' declarations, the
+ assignments would create local variables that are discarded on return.
+ """
+ global _active_tool_preset, _tool_approval_modes, _agent_tools
+ if not preset_name or preset_name == "None":
+  return Result(data=None)
+ try:
+  manager = ToolPresetManager()
+  presets = manager.load_all()
+  if preset_name in presets:
+   preset = presets[preset_name]
+   _active_tool_preset  = preset
+   new_tools            = {name: False for name in mcp_tool_specs.tool_names()}
+   new_tools[TOOL_NAME] = False
+   for cat in preset.categories.values():
+    for tool in cat:
+     name                       = tool.name
+     new_tools[name]            = True
+     _tool_approval_modes[name] = tool.approval
+   _agent_tools = new_tools
+  return Result(data=None)
+ except (OSError, ValueError, AttributeError) as e:
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to set tool preset '{preset_name}': {e}", source="ai_client._set_tool_preset_result", original=e)],
+  )
+
+
+def set_tool_preset(preset_name: Optional[str]) -> None:
+ """Loads a tool preset and applies it via set_agent_tools."""
+ global _agent_tools, _CACHED_ANTHROPIC_TOOLS, _CACHED_DEEPSEEK_TOOLS, _tool_approval_modes, _active_tool_preset
+ _tool_approval_modes = {}
+ if not preset_name or preset_name == "None":
+  # Enable all tools if no preset
+  _agent_tools            = {name: True for name in mcp_tool_specs.tool_names()}
+  _agent_tools[TOOL_NAME] = True
+  _active_tool_preset     = None
+ else:
+  _set_tool_preset_result(preset_name)
+ _CACHED_ANTHROPIC_TOOLS = None
+ _CACHED_DEEPSEEK_TOOLS  = None
+
+def _set_bias_profile_result(profile_name: Optional[str]) -> Result[None]:
+ """Load a bias profile by name and apply it. Returns Result[None].
+
+ On I/O or parsing failure, returns Result(data=None, errors=[ErrorInfo]).
+ The legacy caller (set_bias_profile) delegates to this helper.
+ """
+ if not profile_name or profile_name == "None":
+  return Result(data=None)
+ try:
+  manager  = ToolPresetManager()
+  profiles = manager.load_all_bias_profiles()
+  if profile_name in profiles:
+   _active_bias_profile = profiles[profile_name]
+  return Result(data=None)
+ except (OSError, ValueError, AttributeError) as e:
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to set bias profile '{profile_name}': {e}", source="ai_client._set_bias_profile_result", original=e)],
+  )
+
+
+def set_bias_profile(profile_name: Optional[str]) -> None:
+ """Sets the active tool bias profile for tuning model behavior."""
+ global _active_bias_profile
+ if not profile_name or profile_name == "None":
+  _active_bias_profile = None
+ else:
+  _set_bias_profile_result(profile_name)
+
+def get_bias_profile_result() -> Result[str]:
+ """Returns the name of the currently active bias profile."""
+ return Result(data=_active_bias_profile.name if _active_bias_profile else None)
+
+def _build_anthropic_tools() -> list[ToolDefinition]:
+ """
+  [C: tests/test_agent_tools_wiring.py:test_build_anthropic_tools_conversion, tests/test_tool_access_exclusion.py:test_build_anthropic_tools_excludes_disabled]
+ """
+ raw_tools: list[Metadata] = []
+ for spec in mcp_client.get_tool_schemas():
+  if _agent_tools.get(spec["name"], True):
+   raw_tools.append({
+     "name":         spec["name"],
+     "description":  spec["description"],
+     "input_schema": spec["parameters"],
+    })
+ if _agent_tools.get(TOOL_NAME, True):
+  raw_tools.append({
+   "name": TOOL_NAME,
+   "description": (
+    "Run a PowerShell script within the project base_dir. "
+    "Use this to create, edit, rename, or delete files and directories. "
+    "The working directory is set to base_dir automatically. "
+    "Always prefer targeted edits over full rewrites where possible. "
+    "stdout and stderr are returned to you as the result."
+   ),
+   "input_schema": {
+    "type": "object",
+    "properties": {
+     "script": {
+      "type":        "string",
+      "description": "The PowerShell script to execute."
+     }
+    },
+    "required": ["script"]
+   }
+  })
+ if _active_tool_preset:
+  _BIAS_ENGINE.apply_semantic_nudges(raw_tools, _active_tool_preset)
+ if raw_tools:
+  raw_tools[-1]["cache_control"] = {"type": "ephemeral"}
+ return raw_tools
+
+_CACHED_ANTHROPIC_TOOLS: Optional[FileItems] = None
+
+def _get_anthropic_tools() -> list[Metadata]:
+ """
+  [C: tests/test_bias_efficacy.py:test_bias_efficacy_prompt_generation, tests/test_bias_efficacy.py:test_bias_parameter_nudging, tests/test_bias_integration.py:test_tool_declaration_biasing_anthropic]
+ """
+ global _CACHED_ANTHROPIC_TOOLS
+ if _CACHED_ANTHROPIC_TOOLS is None:
+  _CACHED_ANTHROPIC_TOOLS = _build_anthropic_tools()
+ return _CACHED_ANTHROPIC_TOOLS
+
+
+def _gemini_tool_declaration_result() -> Result[types.Tool]:
+ """Result-returning variant of _gemini_tool_declaration."""
+ # Note: We look up the PARENT package `google.genai` and access `.types`
+ # as an attribute, not `_require_warmed("google.genai.types")` directly.
+ # The latter triggers a latent circular-import bug in google-genai's
+ # __init__.py chain in fresh pytest processes. Using the parent
+ # completes the chain once, then `.types` is just an attribute access.
+ genai = _require_warmed("google.genai")
+ types = genai.types
+ raw_tools: list[Metadata] = []
+ for spec in mcp_client.get_tool_schemas():
+  if _agent_tools.get(spec["name"], True):
+   raw_tools.append({
+    "name":        spec["name"],
+    "description": spec["description"],
+    "parameters":  spec["parameters"]
+   })
+ if _agent_tools.get(TOOL_NAME, True):
+  raw_tools.append({
+   "name": TOOL_NAME,
+   "description": (
+    "Run a PowerShell script within the project base_dir. "
+    "Use this to create, edit, rename, or delete files and directories. "
+    "The working directory is set to base_dir automatically. "
+    "Always prefer targeted edits over full rewrites where possible. "
+    "stdout and stderr are returned to you as the result."
+   ),
+   "parameters": {
+    "type": "object",
+    "properties": {
+     "script": {
+      "type":        "string",
+      "description": "The PowerShell script to execute."
+     }
+    },
+    "required": ["script"]
+   }
+  })
+ if _active_tool_preset:
+  _BIAS_ENGINE.apply_semantic_nudges(raw_tools, _active_tool_preset)
+ declarations: list[types.FunctionDeclaration] = []
+ for tool_def in raw_tools:
+  props  = {}
+  params = tool_def.get("parameters", {})
+  for pname, pdef in params.get("properties", {}).items():
+   ptype_str    = pdef.get("type", "string").upper()
+   ptype        = getattr(types.Type, ptype_str, types.Type.STRING)
+   props[pname] = types.Schema(
+    type=ptype,
+    description=pdef.get("description", ""),
+   )
+  declarations.append(types.FunctionDeclaration(
+   name        = tool_def["name"],
+   description = tool_def["description"],
+   parameters  = types.Schema(
+    type       = types.Type.OBJECT,
+    properties = props,
+    required   = params.get("required", []),
+   ),
+  ))
+ if not declarations:
+  return Result(data=None, errors=[ErrorInfo(kind=ErrorKind.NOT_FOUND, message="No tool declarations to build", source="ai_client._gemini_tool_declaration_result")])
+ return Result(data=types.Tool(function_declarations=declarations))
+
+#endregion: Tool Configuration
+
+#region: Tool Execution
+
+def _parse_tool_args_result(tool_args_str: str) -> Result[Metadata]:
+ """Parse tool call arguments from JSON. Returns Result[dict, ErrorInfo].
+
+ On JSON parse failure, returns Result(data={}, errors=[ErrorInfo(...)]).
+ The legacy caller accumulates errors into file_errors and falls back to
+ empty args (preserving original behavior). Per TIER1_REVIEW 2026-06-20:
+ empty-default is NOT a drain ΓÇö the caller must observe the errors.
+ """
+ try:
+  return Result(data=json.loads(tool_args_str))
+ except (ValueError, TypeError) as e:
+  return Result(
+   data={},
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to parse tool args: {e}", source="ai_client._parse_tool_args_result", original=e)],
+  )
+
+
+async def _execute_tool_calls_concurrently(
+ calls:             list[Any],
+ base_dir:          str,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]],
+ qa_callback:       Optional[Callable[[str], str]],
+ r_idx:             int,
+ provider:          str,
+ patch_callback:    Optional[Callable[[str, str], Result[str]]] = None
+) -> list[tuple[str, str, str, str]]: # tool_name, call_id, output, original_name
+ """
+  Executes tool calls concurrently using asyncio.gather.
+
+  Functional Purpose:
+   Concurrently dispatches tool calls to _execute_single_tool_call_async.
+
+  Parameters & Inputs:
+   calls (list[Any]): List of tool calls.
+   base_dir (str): Workspace path.
+   pre_tool_callback (Optional[Callable]): HITL/approval callback.
+   qa_callback (Optional[Callable]): QA verification callback.
+   r_idx (int): Round index.
+   provider (str): LLM provider.
+   patch_callback (Optional[Callable]): Patch verification callback.
+
+  Returns:
+   list[tuple[str, str, str, str]]: List of (tool_name, call_id, output, original_name).
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: run_with_tool_loop
+   Calls: _execute_single_tool_call_async
+
+  SSDL:
+   `[I:gather] => o-> [I:_execute_single_tool_call_async] -> [M] -> [T:tool_results]`
+
+  Thread Boundaries:
+   Runs in the active asyncio event loop thread.
+
+  [C: tests/test_async_tools.py:test_execute_tool_calls_concurrently_exception_handling, tests/test_async_tools.py:test_execute_tool_calls_concurrently_timing]
+ """
+ monitor = performance_monitor.get_monitor()
+ if monitor.enabled: monitor.start_component("ai_client._execute_tool_calls_concurrently")
+ tier  = get_current_tier_result().data
+ file_errors: list[ErrorInfo] = []
+ tasks = []
+ for fc in calls:
+  if   provider == "gemini":     name, args, call_id = fc.name, dict(fc.args), fc.name # Gemini 1.0.0 doesn't have call IDs in types.Part
+  elif provider == "gemini_cli": name, args, call_id = cast(str, fc.get("name")), cast(Metadata, fc.get("args", {})), cast(str, fc.get("id"))
+  elif provider == "anthropic":  name, args, call_id = cast(str, getattr(fc, "name")), cast(Metadata, getattr(fc, "input")), cast(str, getattr(fc, "id"))
+  elif provider == "deepseek":
+   tool_info     = fc.get("function", {})
+   name          = cast(str, tool_info.get("name"))
+   tool_args_str = cast(str, tool_info.get("arguments", "{}"))
+   call_id       = cast(str, fc.get("id"))
+   parsed = _parse_tool_args_result(tool_args_str)
+   if parsed.errors:
+    file_errors.extend(parsed.errors)
+   args = parsed.data
+  elif provider == "minimax":
+   tool_info     = fc.get("function", {})
+   name          = cast(str, tool_info.get("name"))
+   tool_args_str = cast(str, tool_info.get("arguments", "{}"))
+   call_id       = cast(str, fc.get("id"))
+   parsed = _parse_tool_args_result(tool_args_str)
+   if parsed.errors:
+    file_errors.extend(parsed.errors)
+   args = parsed.data
+  else:
+   continue
+  
+  tasks.append(_execute_single_tool_call_async(name, args, call_id, base_dir, pre_tool_callback, qa_callback, r_idx, tier, patch_callback))
+ 
+ results = await asyncio.gather(*tasks)
+ if monitor.enabled: monitor.end_component("ai_client._execute_tool_calls_concurrently")
+ return results
+
+def run_with_tool_loop(
+ client:  Any,
+ request: Union[OpenAICompatibleRequest, Callable[[int], OpenAICompatibleRequest]],
+ *,
+ capabilities:        Optional[VendorCapabilities] = None,
+ pre_tool_callback:   Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback:         Optional[Callable[[str], str]]  = None,
+ stream_callback:     Optional[Callable[[str], None]] = None,
+ patch_callback:      Optional[Callable[[str, str], Result[str]]] = None,
+ base_dir:            str,
+ vendor_name:         str,
+ history_lock:        Optional[threading.Lock] = None,
+ history:             Optional[FileItems] = None,
+ trim_func:           Optional[Callable[[list[Metadata]], None]] = None,
+ reasoning_extractor: Optional[Callable[[Any], str]] = None,
+ send_func:           Optional[Callable[[int], NormalizedResponse]] = None,
+ on_pre_dispatch:     Optional[Callable[[int, list[Metadata]], list[Metadata]]] = None,
+ wrap_reasoning_in_text: bool = False,
+) -> str:
+ """
+  Orchestrates the LLM conversation loop, executing tool calls and updating history.
+
+  Functional Purpose:
+   Runs a multi-round tool loop (up to MAX_TOOL_ROUNDS + 2). It dispatches client requests,
+   executes any generated tool calls concurrently, updates history, and repeats until completion.
+
+  Parameters & Inputs:
+   client (Any): Active client instance.
+   request (Union[OpenAICompatibleRequest, Callable]): Initial request or builder callback.
+   capabilities (Optional[VendorCapabilities]): Capabilities config.
+   pre_tool_callback (Optional[Callable]): Human-in-the-loop validation callback.
+   qa_callback (Optional[Callable]): QA verification callback.
+   stream_callback (Optional[Callable]): Streaming callback.
+   patch_callback (Optional[Callable]): Verification callback for code patches.
+   base_dir (str): Base workspace directory.
+   vendor_name (str): The vendor name.
+   history_lock (Optional[threading.Lock]): Lock for thread safety on history.
+   history (Optional[FileItems]): Conversation history.
+   trim_func (Optional[Callable]): Trimming callback for history.
+   reasoning_extractor (Optional[Callable]): Callback to extract reasoning content.
+   send_func (Optional[Callable]): Dispatch sender callback.
+   on_pre_dispatch (Optional[Callable]): Callback to adjust tools.
+   wrap_reasoning_in_text (bool): When True and reasoning_content is non-empty, the
+    returned text is prepended with `<thinking>...</thinking>` wrapping the
+    reasoning. This lets thinking_parser.parse_thinking_trace extract a
+    ThinkingSegment for the discussion entry. Default False (callers that
+    already wrap inline, e.g. DeepSeek, pass False).
+
+  Returns:
+   str: The final text response returned by the LLM.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: _send_anthropic, _send_deepseek, _send_minimax, _send_qwen, _send_llama,
+              _send_grok, _send_llama_native
+   Calls: dispatch_send, _execute_tool_calls_concurrently
+
+  SSDL:
+   `o-> [I:dispatch_send] -> [B:tool_calls?] => [I:_execute_tool_calls_concurrently] -> [T:response_text]`
+
+  Thread Boundaries:
+   Runs synchronously in caller thread; synchronizes history modifications using history_lock.
+ """
+ def _default_send(_round_idx: int) -> NormalizedResponse:
+  from src.openai_compatible import send_openai_compatible as _send_oc
+  assert capabilities is not None, "capabilities required when send_func is not provided"
+  res = _send_oc(client, request_builder(_round_idx), capabilities=capabilities)
+  if not res.ok:
+   if res.errors and res.errors[0].original:
+    raise res.errors[0].original from None
+   raise RuntimeError(res.errors[0].message if res.errors else "Unknown OpenAI error") from None
+  return res.data
+ request_builder: Callable[[int], OpenAICompatibleRequest] = (request if callable(request) else (lambda _i: request))
+ dispatch_send:   Callable[[int], NormalizedResponse]      = send_func or _default_send
+ response_text:   str = ""
+ for _round_idx in range(MAX_TOOL_ROUNDS + 2):
+  response               = dispatch_send(_round_idx)
+  reasoning_content: str = reasoning_extractor(response.raw_response) if reasoning_extractor else ""
+  response_text          = response.text or ""
+  if history_lock is not None and history is not None:
+   with history_lock:
+    msg:                    Metadata           = {"role": "assistant", "content": response.text or None}
+    if reasoning_content:   msg["reasoning_content"] = reasoning_content
+    if response.tool_calls: msg["tool_calls"]        = response.tool_calls
+    history.append(msg)
+  if not response.tool_calls: break
+  if on_pre_dispatch is not None: _adjusted_calls = on_pre_dispatch(_round_idx, response.tool_calls)
+  else:                           _adjusted_calls = response.tool_calls
+  try:
+   loop    = asyncio.get_running_loop()
+   results = asyncio.run_coroutine_threadsafe(
+    _execute_tool_calls_concurrently(
+     _adjusted_calls, base_dir, pre_tool_callback, qa_callback, _round_idx, vendor_name, patch_callback,
+    ),
+    loop,
+   ).result()
+  except RuntimeError:
+   results = asyncio.run(_execute_tool_calls_concurrently(
+    _adjusted_calls, base_dir, pre_tool_callback, qa_callback, _round_idx, vendor_name, patch_callback,
+   ))
+  if history_lock is not None and history is not None:
+   with history_lock:
+    for _i, (tool_name, call_id, out, _err) in enumerate(results):
+     history.append({
+      "role":         "tool",
+      "tool_call_id": call_id,
+      "content":      str(out) if out else "",
+     })
+  if trim_func is not None: trim_func(history)
+ if wrap_reasoning_in_text and reasoning_content:
+  response_text = f"<thinking>\n{reasoning_content}\n</thinking>\n\n{response_text}"
+ return response_text
+
+async def _execute_single_tool_call_async(
+ name:              str,
+ args:              Metadata,
+ call_id:           str,
+ base_dir:          str,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]],
+ qa_callback:       Optional[Callable[[str], str]],
+ r_idx:             int,
+ tier:              str | None = None,
+ patch_callback:    Optional[Callable[[str, str], Result[str]]] = None
+) -> tuple[str, str, str, str]:
+ """
+  Executes a single tool call asynchronously, checking the approval clutch.
+
+  Functional Purpose:
+   Executes a tool call (either PowerShell script or MCP tool) based on tool approval clutch settings.
+   Uses pre_tool_callback for human approval when required.
+
+  Parameters & Inputs:
+   name (str): The name of the tool to execute.
+   args (Metadata): Arguments passed to the tool.
+   call_id (str): Unique call identifier.
+   base_dir (str): Workspace root directory.
+   pre_tool_callback (Optional[Callable]): Hook for HITL validation.
+   qa_callback (Optional[Callable]): QA verification callback.
+   r_idx (int): Current tool loop round index.
+   tier (str | None): Active MMA orchestration tier.
+   patch_callback (Optional[Callable]): Verification callback for code patches.
+
+  Returns:
+   tuple[str, str, str, str]: A tuple containing (tool_name, call_id, output, original_name).
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: _execute_tool_calls_concurrently
+   Calls: set_current_tier, events.emit, _append_comms, _run_script,
+          pre_tool_callback, mcp_client.async_dispatch
+
+  SSDL:
+   `[I:CheckClutch] -> [B:Approved?] -> [I:run_powershell] -> [T:output]`
+
+  Thread Boundaries:
+   Runs in the active asyncio event loop thread; offloads blocking synchronous calls
+   (like pre_tool_callback and _run_script) to separate worker threads using asyncio.to_thread.
+ """
+ set_current_tier(tier)
+ out           = ""
+ tool_executed = False
+ events.emit("tool_execution", payload = {"status": "started", "tool": name, "args": args, "round": r_idx})
+ 
+ # Check for auto approval mode
+ approval_mode = _tool_approval_modes.get(name, "ask")
+
+ # Check for run_powershell
+ if name == TOOL_NAME:
+  scr = cast(str, args.get("script", ""))
+  _append_comms("OUT", "tool_call", {"name": TOOL_NAME, "id": call_id, "script": scr})
+  if approval_mode == "auto":
+   out = await asyncio.to_thread(_run_script, scr, base_dir, qa_callback, patch_callback)
+   tool_executed = True
+  elif pre_tool_callback:
+   # pre_tool_callback is synchronous and might block for HITL
+   res = await asyncio.to_thread(pre_tool_callback, scr, base_dir, qa_callback)
+   if res is None: out = "USER REJECTED: tool execution cancelled"
+   else:           out = res
+   tool_executed = True
+
+ if not tool_executed:
+  is_native   = name in mcp_tool_specs.tool_names()
+  ext_tools   = mcp_client.get_external_mcp_manager().get_all_tools()
+  is_external = name in ext_tools
+  if name and (is_native or is_external):
+   _append_comms("OUT", "tool_call", {"name": name, "id": call_id, "args": args})
+   should_approve = (name in mcp_client.MUTATING_TOOLS or is_external) and approval_mode != "auto" and pre_tool_callback
+   if should_approve:
+    label = "MCP MUTATING" if is_native else "EXTERNAL MCP"
+    desc  = f"# {label} TOOL: {name}\n" + "\n".join(f"#   {k}: {repr(v)}" for k, v in args.items())
+    _res  = await asyncio.to_thread(pre_tool_callback, desc, base_dir, qa_callback)
+    out   = "USER REJECTED: tool execution cancelled" if _res is None else await mcp_client.async_dispatch(name, args)
+   else:
+    out = await mcp_client.async_dispatch(name, args)
+   if tool_log_callback:
+    tool_log_callback(f"# MCP TOOL: {name}\n{json.dumps(args, indent=1)}", out)
+  elif name == TOOL_NAME:
+   scr = cast(str, args.get("script", ""))
+   _append_comms("OUT", "tool_call", {"name": TOOL_NAME, "id": call_id, "script": scr})
+   out = await asyncio.to_thread(_run_script, scr, base_dir, qa_callback, patch_callback)
+  else:
+   out = f"ERROR: unknown tool '{name}'"
+   if tool_log_callback:
+    tool_log_callback(f"ERROR: {name}", out)
+ 
+ return (name, call_id, out, name)
+
+def _run_script(script: str, base_dir: str, qa_callback: Optional[Callable[[str], str]] = None, patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> str:
+ if confirm_and_run_callback is None:
+  return "ERROR: no confirmation handler registered"
+ result = confirm_and_run_callback(script, base_dir, qa_callback, patch_callback)
+ if result is None: output = "USER REJECTED: command was not executed"
+ else:              output = result
+ if tool_log_callback is not None: tool_log_callback(script, output)
+ return output
+
+def _truncate_tool_output(output: str) -> str:
+ if _history_trunc_limit > 0 and len(output) > _history_trunc_limit:
+  return output[:_history_trunc_limit] + "\n\n... [TRUNCATED BY SYSTEM TO SAVE TOKENS.]"
+ return output
+
+#endregion: Tool Execution
+
+#region: File Context Building
+
+def _reread_file_items_result(file_items: FileItems) -> Result[FileItemsDiff]:
+ """Re-reads file items, returns (refreshed, changed) tuple.
+
+ Per-file read errors are accumulated into Result.errors (structured
+ ErrorInfo with original exception preserved). The legacy caller
+ _reread_file_items ignores errors (preserving original behavior);
+ future callers should check result.errors to detect file re-read
+ failures.
+ """
+ refreshed: list[Metadata] = []
+ changed:   list[Metadata] = []
+ errors:    list[ErrorInfo] = []
+ for item in file_items:
+  path = item.get("path")
+  if path is None:
+   refreshed.append(item)
+   continue
+  p = path if isinstance(path, _P) else _P(path)
+  try:
+   current_mtime = p.stat().st_mtime
+   prev_mtime    = cast(float, item.get("mtime", 0.0))
+   if current_mtime == prev_mtime:
+    refreshed.append(item)
+    continue
+   content  = p.read_text(encoding="utf-8")
+   new_item = {**item, "old_content": item.get("content", ""), "content": content, "error": False, "mtime": current_mtime}
+   refreshed.append(new_item)
+   changed.append(new_item)
+  except (OSError, UnicodeDecodeError) as e:
+   err_item = {**item, "content": f"ERROR re-reading {p}: {e}", "error": True, "mtime": 0.0}
+   refreshed.append(err_item)
+   changed.append(err_item)
+   errors.append(ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to re-read {p}: {e}", source="ai_client._reread_file_items_result", original=e))
+ return Result(data=FileItemsDiff(refreshed=refreshed, changed=changed), errors=errors)
+
+
+def _build_file_context_text(file_items: FileItems) -> str:
+ if not file_items:
+  return ""
+ parts: list[str] = []
+ for item in file_items:
+  path    = item.get("path") or item.get("entry", "unknown")
+  suffix  = str(path).rsplit(".", 1)[-1] if "." in str(path) else "text"
+  content = item.get("content", "")
+  parts.append(f"### `{path}`\n\n```{suffix}\n{content}\n```")
+ return "\n\n---\n\n".join(parts)
+
+_DIFF_LINE_THRESHOLD: int = 200
+
+def _build_file_diff_text(changed_items: FileItems) -> str:
+ """
+  Generates unified diffs or full file dumps for changed files in the context.
+
+  Functional Purpose:
+   Formats file modifications for the LLM prompt. If a file change is small or lacks prior content,
+   the full file is dumped; otherwise, a unified diff is constructed.
+
+  Parameters & Inputs:
+   changed_items (list[Metadata]): List of file dictionaries that have changed.
+
+  Returns:
+   str: Combined markdown string representing the changes or full files.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: _send_gemini
+   Calls: difflib.unified_diff
+
+  SSDL:
+   `o-> [I:get_mtime] -> [B:changed?] -> [I:read_file] -> [T:diff_text]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread.
+ """
+ if not changed_items:
+  return ""
+ parts: list[str] = []
+ for item in changed_items:
+  path        = item.get("path") or item.get("entry", "unknown")
+  content     = cast(str, item.get("content", ""))
+  old_content = cast(str, item.get("old_content", ""))
+  new_lines   = content.splitlines(keepends=True)
+  if len(new_lines) <= _DIFF_LINE_THRESHOLD or not old_content:
+   suffix = str(path).rsplit(".", 1)[-1] if "." in str(path) else "text"
+   parts.append(f"### `{path}` (full)\n\n```{suffix}\n{content}\n```")
+  else:
+   old_lines = old_content.splitlines(keepends=True)
+   diff      = difflib.unified_diff(old_lines, new_lines, fromfile=str(path), tofile=str(path), lineterm="")
+   diff_text = "\n".join(diff)
+   if diff_text: parts.append(f"### `{path}` (diff)\n\n```diff\n{diff_text}\n```")
+   else:         parts.append(f"### `{path}` (no changes detected)")
+ return "\n\n---\n\n".join(parts)
+
+def _build_deepseek_tools() -> list[ToolDefinition]:
+ raw_tools: list[Metadata] = []
+ for spec in mcp_client.get_tool_schemas():
+  if _agent_tools.get(spec["name"], True):
+   raw_tools.append({
+    "name":        spec["name"],
+    "description": spec["description"],
+    "parameters":  spec["parameters"]
+   })
+ if _agent_tools.get(TOOL_NAME, True):
+  raw_tools.append({
+   "name": TOOL_NAME,
+   "description": (
+    "Run a PowerShell script within the project base_dir. "
+    "Use this to create, edit, rename, or delete files and directories. "
+    "The working directory is set to base_dir automatically. "
+    "Always prefer targeted edits over full rewrites where possible. "
+    "stdout and stderr are returned to you as the result."
+   ),
+   "parameters": {
+    "type": "object",
+    "properties": {
+     "script": {
+      "type":        "string",
+      "description": "The PowerShell script to execute."
+     }
+    },
+    "required": ["script"]
+   }
+  })
+ if _active_tool_preset:
+  _BIAS_ENGINE.apply_semantic_nudges(raw_tools, _active_tool_preset)
+ tools_list: list[Metadata] = []
+ for tool_def in raw_tools:
+  tools_list.append({
+   "type": "function",
+   "function": {
+    "name":        tool_def["name"],
+    "description": tool_def["description"],
+    "parameters":  tool_def["parameters"],
+   }
+  })
+ return tools_list
+
+_CACHED_DEEPSEEK_TOOLS: Optional[FileItems] = None
+
+def _get_deepseek_tools() -> list[Metadata]:
+ global _CACHED_DEEPSEEK_TOOLS
+ if _CACHED_DEEPSEEK_TOOLS is None:
+  _CACHED_DEEPSEEK_TOOLS = _build_deepseek_tools()
+ return _CACHED_DEEPSEEK_TOOLS
+
+def _content_block_to_dict(block: Any) -> Metadata:
+ if isinstance(block, dict):      return block
+ if hasattr(block, "model_dump"): return cast(Metadata, block.model_dump())
+ if hasattr(block, "to_dict"):    return cast(Metadata, block.to_dict())
+ block_type = getattr(block, "type", None)
+ if block_type == "text":     return {"type": "text", "text": block.text}
+ if block_type == "tool_use": return {"type": "tool_use", "id": getattr(block, "id"), "name": getattr(block, "name"), "input": getattr(block, "input")}
+ return {"type": "text", "text": str(block)}
+
+#endregion: File Context Building
+
+#region: Token Estimation
+
+_CHARS_PER_TOKEN:             float = 3.5
+_ANTHROPIC_MAX_PROMPT_TOKENS: int   = 180_000
+_GEMINI_MAX_INPUT_TOKENS:     int   = 900_000
+_FILE_REFRESH_MARKER:         str   = _project_context_marker if _project_context_marker.strip() else "[SYSTEM: FILES UPDATED]"
+
+def _estimate_message_tokens(msg: Metadata) -> int:
+ cached = msg.get("_est_tokens")
+ if cached is not None: return cast(int, cached)
+ total_chars = 0
+ content     = msg.get("content", "")
+ if isinstance(content, str): 
+  total_chars += len(content)
+ elif isinstance(content, list):
+  for block in content:
+   if isinstance(block, dict):
+    text = block.get("text", "") or block.get("content", "")
+    if isinstance(text, str):
+     total_chars += len(text)
+    inp = block.get("input")
+    if isinstance(inp, dict):
+     total_chars += len(json.dumps(inp, ensure_ascii=False))
+   elif isinstance(block, str):
+    total_chars += len(block)
+ est = max(1, int(total_chars / _CHARS_PER_TOKEN))
+ msg["_est_tokens"] = est
+ return est
+
+def _invalidate_token_estimate(msg: Metadata) -> None:
+ msg.pop("_est_tokens", None)
+
+def _estimate_prompt_tokens(system_blocks: list[Metadata], history: list[Metadata]) -> int:
+ total = 0
+ for block in system_blocks:
+  text   = cast(str, block.get("text", ""))
+  total += max(1, int(len(text) / _CHARS_PER_TOKEN))
+ total += 2500
+ for msg in history:
+  total += _estimate_message_tokens(msg)
+ return total
+
+def _strip_stale_file_refreshes(history: list[Metadata]) -> None:
+ if len(history) < 2:
+  return
+ last_user_idx = -1
+ for i in range(len(history) - 1, -1, -1):
+  if history[i].get("role") == "user":
+   last_user_idx = i
+   break
+ for i, msg in enumerate(history):
+  if msg.get("role") != "user" or i == last_user_idx:
+   continue
+  content = msg.get("content")
+  if not isinstance(content, list):
+   continue
+  cleaned: list[Metadata] = []
+  for block in content:
+   if isinstance(block, dict) and block.get("type") == "text":
+    text = cast(str, block.get("text", ""))
+    if text.startswith(_FILE_REFRESH_MARKER):
+     continue
+   cleaned.append(block)
+  if len(cleaned) < len(content):
+   msg["content"] = cleaned
+   _invalidate_token_estimate(msg)
+
+def _chunk_text(text: str, chunk_size: int) -> list[str]:
+ return [text[i:i + chunk_size] for i in range(0, len(text), chunk_size)]
+
+def _build_chunked_context_blocks(md_content: str) -> list[Metadata]:
+ chunks = _chunk_text(md_content, _ANTHROPIC_CHUNK_SIZE)
+ blocks: list[Metadata] = []
+ for i, chunk in enumerate(chunks):
+  block: Metadata = {"type": "text", "text": chunk}
+  if i == len(chunks) - 1:
+   block["cache_control"] = {"type": "ephemeral"}
+  blocks.append(block)
+ return blocks
+
+def _strip_cache_controls(history: list[Metadata]) -> None:
+ for msg in history:
+  content = msg.get("content")
+  if isinstance(content, list):
+   for block in content:
+    if isinstance(block, dict):
+     block.pop("cache_control", None)
+
+def _add_history_cache_breakpoint(history: list[Metadata]) -> None:
+ user_indices = [i for i, m in enumerate(history) if m.get("role") == "user"]
+ if len(user_indices) < 2: return
+ target_idx = user_indices[-2]
+ content    = history[target_idx].get("content")
+ if isinstance(content, list) and content:
+  last_block = content[-1]
+  if isinstance(last_block, dict):
+   last_block["cache_control"] = {"type": "ephemeral"}
+ elif isinstance(content, str):
+  history[target_idx]["content"] = [
+   {"type": "text", "text": content, "cache_control": {"type": "ephemeral"}}
+  ]
+
+#endregion: Token Estimation
+
+#region: Anthropic Provider
+
+def _list_anthropic_models_result() -> Result[list[str]]:
+ """List available Anthropic models via the SDK.
+
+ Returns Result(data=sorted_models) on success, Result(data=[],
+ errors=[ErrorInfo]) on SDK or credentials failure.
+
+ The previous version had:
+     except Exception as exc:
+         raise _classify_anthropic_error(exc) from exc
+ which raised an ErrorInfo as an Exception ΓÇö a runtime bug. This
+ migration follows the Phase 9 redo precedent: convert to Result[T].
+ """
+ try:
+  anthropic = _require_warmed("anthropic")
+  creds     = _load_credentials()
+  client    = anthropic.Anthropic(api_key=creds["anthropic"]["api_key"])
+  models: list[str] = []
+  for m in client.models.list(): models.append(m.id)
+  return Result(data=sorted(models))
+ except Exception as exc:
+  return Result(
+   data=[],
+   errors=[_classify_anthropic_error(exc, source="ai_client._list_anthropic_models_result")],
+  )
+
+
+def _ensure_anthropic_client() -> None:
+ global _anthropic_client
+ anthropic = _require_warmed("anthropic")
+ if _anthropic_client is None:
+  creds = _load_credentials()
+  _anthropic_client = anthropic.Anthropic(
+   api_key         = creds["anthropic"]["api_key"],
+   default_headers = {"anthropic-beta": "prompt-caching-2024-07-31"}
+  )
+
+def _trim_anthropic_history(system_blocks: list[Metadata], history: list[Metadata]) -> int:
+ _strip_stale_file_refreshes(history)
+ est = _estimate_prompt_tokens(system_blocks, history)
+ if est <= _ANTHROPIC_MAX_PROMPT_TOKENS: return 0
+ dropped = 0
+ while len(history) > 3 and est > _ANTHROPIC_MAX_PROMPT_TOKENS:
+  if history[1].get("role") == "assistant" and len(history) > 2 and history[2].get("role") == "user":
+   removed_asst = history.pop(1)
+   removed_user = history.pop(1)
+   dropped     += 2
+   est         -= _estimate_message_tokens(removed_asst)
+   est         -= _estimate_message_tokens(removed_user)
+   while len(history) > 2 and history[1].get("role") == "assistant" and history[2].get("role") == "user":
+    content = history[2].get("content", [])
+    if isinstance(content, list) and content and isinstance(content[0], dict) and content[0].get("type") == "tool_result":
+     r_a = history.pop(1)
+     r_u = history.pop(1)
+     dropped += 2
+     est -= _estimate_message_tokens(r_a)
+     est -= _estimate_message_tokens(r_u)
+    else:
+     break
+  else:
+   removed  = history.pop(1)
+   dropped += 1
+   est     -= _estimate_message_tokens(removed)
+ return dropped
+
+def _repair_anthropic_history(history: list[Metadata]) -> None:
+ if not history: return
+ last = history[-1]
+ if last.get("role") != "assistant": return
+ content = last.get("content", [])
+ tool_use_ids: list[str] = []
+ for block in content:
+  if isinstance(block, dict):
+   if block.get("type") == "tool_use":
+    tool_use_ids.append(cast(str, block["id"]))
+ if not tool_use_ids:
+  return
+ history.append({
+   "role": "user",
+   "content": [
+    {
+     "type":        "tool_result",
+     "tool_use_id": tid,
+     "content":     "Tool call was not completed (session interrupted).",
+    }
+    for tid in tool_use_ids
+   ],
+  })
+
+def _send_anthropic(
+  md_content:         str,
+  user_message:       str,
+  base_dir:           str,
+  file_items:         list[Metadata] | None = None,
+  discussion_history: str = "",
+  pre_tool_callback:  Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+  qa_callback:        Optional[Callable[[str], str]] = None,
+  stream_callback:    Optional[Callable[[str], None]] = None,
+  patch_callback:     Optional[Callable[[str, str], Result[str]]] = None
+ ) -> Result[str]:
+ """
+  Functional Purpose:
+   Sends requests to Anthropic models, managing conversation history, prompt caching, token limits, and executing tool loops.
+  Parameters & Inputs:
+   - md_content, user_message, base_dir, file_items, discussion_history: Context and input parameters.
+   - pre_tool_callback, qa_callback, stream_callback, patch_callback: Execution control callbacks.
+  Immediate-Mode DAG / Thread Context:
+   - Called by: send
+   - Calls: _ensure_anthropic_client, _trim_anthropic_history, client.messages.create, run_with_tool_loop
+  SSDL:
+   [I:_ensure_anthropic_client] -> [I:_trim_anthropic_history] -> [I:client.messages.create] -> [T:Result]
+  Thread Boundaries:
+   Runs on whichever thread calls send (typically an async worker thread).
+ """
+ anthropic = _require_warmed("anthropic")
+ genai     = _require_warmed("google.genai")
+ types     = genai.types
+ monitor   = performance_monitor.get_monitor()
+ if monitor.enabled: monitor.start_component("ai_client._send_anthropic")
+ try:
+  _ensure_anthropic_client()
+  mcp_client.configure(file_items or [], [base_dir])
+  history = provider_state.get_history("anthropic")
+  stable_prompt = _get_combined_system_prompt()
+  stable_blocks: list[Metadata] = [{"type": "text", "text": stable_prompt, "cache_control": {"type": "ephemeral"}}]
+  context_text   = f"\n\n<context>\n{md_content}\n</context>"
+  context_blocks = _build_chunked_context_blocks(context_text)
+  system_blocks  = stable_blocks + context_blocks
+  if discussion_history and not history:
+   user_content: list[Metadata] = [{"type": "text", "text": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"}]
+  else:
+   user_content = [{"type": "text", "text": user_message}]
+  for msg in history:
+   if msg.get("role") == "user" and isinstance(msg.get("content"), list):
+    modified = False
+    for block in cast(List[dict[str, Any]], msg["content"]):
+     if isinstance(block, dict) and block.get("type") == "tool_result":
+      t_content = block.get("content", "")
+      if _history_trunc_limit > 0 and isinstance(t_content, str) and len(t_content) > _history_trunc_limit:
+       block["content"] = t_content[:_history_trunc_limit] + "\n\n... [TRUNCATED BY SYSTEM TO SAVE TOKENS. Original output was too large.]"
+       modified = True
+    if modified: _invalidate_token_estimate(msg)
+  _strip_cache_controls(history)
+  _repair_anthropic_history(history)
+  history.append({"role": "user", "content": user_content})
+  _add_history_cache_breakpoint(history)
+  all_text_parts: list[str] = []
+  _cumulative_tool_bytes    = 0
+  
+  def _strip_private_keys(history: list[Metadata]) -> list[Metadata]:
+   return [{k: v for k, v in m.items() if not k.startswith("_")} for m in history]
+  
+  for round_idx in range(MAX_TOOL_ROUNDS + 2):
+   response: Any = None
+   dropped       = _trim_anthropic_history(system_blocks, history)
+   if dropped > 0:
+    est_tokens = _estimate_prompt_tokens(system_blocks, history)
+    _append_comms("OUT", "request", {
+      "message": (
+       f"[HISTORY TRIMMED: dropped {dropped} old messages to fit token budget. "
+       f"Estimated {est_tokens} tokens remaining. {len(history)} messages in history.]"
+      ),
+     })
+   
+   events.emit("request_start", payload={"provider": "anthropic", "model": _model, "round": round_idx})
+   assert _anthropic_client is not None
+   if stream_callback:
+    with _anthropic_client.messages.stream(
+     model       = _model,
+     max_tokens  = _max_tokens,
+     temperature = _temperature,
+     top_p       = _top_p,
+     system      = cast(Iterable[anthropic.types.TextBlockParam], system_blocks),
+     tools       = cast(Iterable[anthropic.types.ToolParam], _get_anthropic_tools()),
+     messages    = cast(Iterable[anthropic.types.MessageParam], _strip_private_keys(history)),
+    ) as stream:
+     for event in stream:
+      if isinstance(event, anthropic.types.ContentBlockDeltaEvent) and event.delta.type == "text_delta":
+       stream_callback(event.delta.text)
+     response = stream.get_final_message()
+   else:
+    response = _anthropic_client.messages.create(
+     model       = _model,
+     max_tokens  = _max_tokens,
+     temperature = _temperature,
+     top_p       = _top_p,
+     system      = cast(Iterable[anthropic.types.TextBlockParam], system_blocks),
+     tools       = cast(Iterable[anthropic.types.ToolParam], _get_anthropic_tools()),
+     messages    = cast(Iterable[anthropic.types.MessageParam], _strip_private_keys(history)),
+    )
+   serialised_content = [_content_block_to_dict(b) for b in response.content]
+   history.append({
+     "role":    "assistant",
+     "content": serialised_content,
+    })
+   text_blocks = [b.text for b in response.content if hasattr(b, "text") and b.text]
+   if text_blocks:
+    all_text_parts.append("\n".join(text_blocks))
+   tool_use_blocks = [
+    {"id": getattr(b, "id"), "name": getattr(b, "name"), "input": getattr(b, "input")}
+    for b in response.content
+    if getattr(b, "type", None) == "tool_use"
+   ]
+   usage_dict: Metadata = {}
+   if response.usage:
+    usage_dict["input_tokens"]  = response.usage.input_tokens
+    usage_dict["output_tokens"] = response.usage.output_tokens
+    cache_creation              = getattr(response.usage, "cache_creation_input_tokens", None)
+    cache_read                  = getattr(response.usage, "cache_read_input_tokens",     None)
+    if cache_creation is not None: usage_dict["cache_creation_input_tokens"] = cache_creation
+    if cache_read     is not None: usage_dict["cache_read_input_tokens"]     = cache_read
+   events.emit("response_received", payload={"provider": "anthropic", "model": _model, "usage": usage_dict, "round": round_idx})
+   _append_comms("IN", "response", {
+     "round":       round_idx,
+     "stop_reason": response.stop_reason,
+     "text":        "\n".join(text_blocks),
+     "tool_calls":  tool_use_blocks,
+     "usage":       usage_dict,
+    })
+   if response.stop_reason != "tool_use" or not tool_use_blocks: break
+   if round_idx             > MAX_TOOL_ROUNDS:                   break
+   
+   # Execute tools concurrently
+   try:
+    loop    = asyncio.get_running_loop()
+    results = asyncio.run_coroutine_threadsafe(
+     _execute_tool_calls_concurrently(response.content, base_dir, pre_tool_callback, qa_callback, round_idx, "anthropic", patch_callback),
+     loop
+    ).result()
+   except RuntimeError:
+    results = asyncio.run(_execute_tool_calls_concurrently(response.content, base_dir, pre_tool_callback, qa_callback, round_idx, "anthropic", patch_callback))
+   
+   tool_results: list[Metadata] = []
+   for i, (name, call_id, out, _) in enumerate(results):
+    truncated = _truncate_tool_output(out)
+    _cumulative_tool_bytes += len(truncated)
+    tool_results.append({
+      "type":        "tool_result",
+      "tool_use_id": call_id,
+      "content":     truncated,
+     })
+    _append_comms("IN", "tool_result", {"name": name, "id": call_id, "output": out})
+    events.emit("tool_execution", payload={"status": "completed", "tool": name, "result": out, "round": round_idx})
+   
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    tool_results.append({
+      "type": "text",
+      "text": f"SYSTEM WARNING: Cumulative tool output exceeded {_MAX_TOOL_OUTPUT_BYTES // 1000}KB budget. Provide your final answer now."
+     })
+    _append_comms("OUT", "request", {"message": f"[TOOL OUTPUT BUDGET EXCEEDED: {_cumulative_tool_bytes} bytes]"})
+   if file_items:
+    _reread_result = _reread_file_items_result(file_items)
+    file_items, changed = _reread_result.data
+    refreshed_ctx       = _build_file_diff_text(changed)
+    if refreshed_ctx:
+     tool_results.append({
+      "type": "text",
+      "text": (
+       f"{_get_context_marker()}\n\n"
+       + refreshed_ctx
+      ),
+     })
+   if round_idx == MAX_TOOL_ROUNDS:
+    tool_results.append({
+      "type": "text",
+      "text": "SYSTEM WARNING: MAX TOOL ROUNDS REACHED. YOU MUST PROVIDE YOUR FINAL ANSWER NOW WITHOUT CALLING ANY MORE TOOLS."
+     })
+   history.append({
+     "role":    "user",
+     "content": tool_results,
+    })
+   _append_comms("OUT", "tool_result_send", {
+     "results": [
+      {"tool_use_id": r["tool_use_id"], "content": r["content"]}
+      for r in tool_results if r.get("type") == "tool_result"
+     ],
+    })
+  final_text = "\n\n".join(all_text_parts)
+  res        = final_text if final_text.strip() else "(No text returned by the model)"
+  if monitor.enabled: monitor.end_component("ai_client._send_anthropic")
+  return Result(data=res)
+ except Exception as exc:
+  if monitor.enabled: monitor.end_component("ai_client._send_anthropic")
+  return Result(data="", errors=[_classify_anthropic_error(exc, source="ai_client.anthropic")])
+
+#endregion: Anthropic Provider
+
+#region: Gemini Provider
+
+def get_gemini_cache_stats() -> Metadata:
+ _ensure_gemini_client()
+ if not _gemini_client: return {"cache_count": 0, "total_size_bytes": 0, "cached_files": []}
+ caches_iterator  = _gemini_client.caches.list()
+ caches           = list(caches_iterator)
+ total_size_bytes = sum(getattr(c, 'size_bytes', 0) for c in caches)
+ return {
+  "cache_count":      len(caches),
+  "total_size_bytes": total_size_bytes,
+  "cached_files":     _gemini_cached_file_paths,
+ }
+
+def _list_gemini_cli_models() -> list[str]:
+ return [
+  "gemini-3-flash-preview",
+  "gemini-3.1-pro-preview",
+  "gemini-2.5-pro",
+  "gemini-2.5-flash",
+  "gemini-2.0-flash",
+  "gemini-2.5-flash-lite",
+ ]
+
+def _list_gemini_models_result(api_key: str) -> Result[list[str]]:
+ """List available Gemini models via google-genai SDK.
+
+ Returns the sorted list of Gemini model names. On SDK or network failure,
+ returns Result(data=[], errors=[ErrorInfo(...)]). The legacy caller
+ (_list_gemini_models) returns result.data directly (preserving original
+ behavior); callers that need to surface errors should call this helper
+ and inspect result.errors.
+ """
+ try:
+  genai  = _require_warmed("google.genai")
+  client = genai.Client(api_key=api_key)
+  models: list[str] = []
+  for m in client.models.list():
+   name = m.name
+   if name and name.startswith("models/"): name = name[len("models/"):]
+   if name and "gemini" in name.lower():   models.append(name)
+  return Result(data=sorted(models))
+ except Exception as exc:
+  return Result(
+   data=[],
+   errors=[_classify_gemini_error(exc, source="ai_client._list_gemini_models_result")],
+  )
+
+
+def _ensure_gemini_client() -> None:
+  global _gemini_client
+  genai = _require_warmed("google.genai")
+  if _gemini_client is None:
+   creds          = _load_credentials()
+   _gemini_client = genai.Client(api_key=creds["gemini"]["api_key"])
+
+def _delete_gemini_cache_result() -> Result[None]:
+ """Delete the active Gemini cache. Returns Result[None].
+
+ On SDK failure, returns Result(data=None, errors=[ErrorInfo]) and logs
+ a warning to comms. The caller ignores errors (cache-delete is a
+ best-effort cleanup; the caller proceeds to rebuild cache state).
+ """
+ if _gemini_cache is None or _gemini_client is None:
+  return Result(data=None)
+ try:
+  _gemini_client.caches.delete(name=_gemini_cache.name)
+  return Result(data=None)
+ except Exception as e:
+  _append_comms("OUT", "request", {"message": f"[CACHE DELETE WARN] {e}"})
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to delete gemini cache: {e}", source="ai_client._delete_gemini_cache_result", original=e)],
+  )
+
+_GEMINI_CACHE_TOKEN_THRESHOLD: int = 2048
+
+def _should_cache_gemini_result(sys_instr: str) -> Result[bool]:
+ """Decide whether the current Gemini context warrants caching.
+
+ Returns Result(data=True) if token count >= 2048, Result(data=False)
+ if below threshold (with a [CACHING SKIPPED] comms note), or
+ Result(data=False, errors=[ErrorInfo]) on SDK failure.
+
+ The caller (_send_gemini) ignores errors and treats failure as
+ 'do not cache' (safe default: cache create is expensive; skipping
+ on count failure is a soft fallback to inline system_instruction).
+ """
+ if _gemini_client is None:
+  return Result(data=False)
+ try:
+  count_resp = _gemini_client.models.count_tokens(model=_model, contents=[sys_instr])
+  total      = count_resp.total_tokens
+  if total and total >= _GEMINI_CACHE_TOKEN_THRESHOLD:
+   return Result(data=True)
+  _append_comms("OUT", "request", {"message": f"[CACHING SKIPPED] Context too small ({total} tokens < {_GEMINI_CACHE_TOKEN_THRESHOLD})"})
+  return Result(data=False)
+ except Exception as e:
+  _append_comms("OUT", "request", {"message": f"[COUNT FAILED] {e}"})
+  return Result(
+   data=False,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to count gemini tokens: {e}", source="ai_client._should_cache_gemini_result", original=e)],
+  )
+
+def _create_gemini_cache_result(sys_instr: str, tools_decl: Any, file_items: list[Metadata] | None) -> Result[Any]:
+ """Create a Gemini cache and the corresponding GenerateContentConfig.
+
+ Returns Result(data=chat_config_with_cached_content) on success and
+ Result(data=None, errors=[ErrorInfo]) on SDK failure. Side effects on
+ globals _gemini_cache, _gemini_cache_created_at, _gemini_cached_file_paths
+ are managed inside the helper (set on success, reset on failure to match
+ original semantics).
+ """
+ global _gemini_cache, _gemini_cache_created_at, _gemini_cached_file_paths
+ types = _require_warmed("google.genai").types
+ try:
+  _gemini_cache = _gemini_client.caches.create(
+   model=_model,
+   config=types.CreateCachedContentConfig(
+    system_instruction=sys_instr,
+    tools=cast(Any, tools_decl),
+    ttl=f"{_GEMINI_CACHE_TTL}s",
+   )
+  )
+  _gemini_cache_created_at = time.time()
+  _gemini_cached_file_paths = [str(item.get("path", "")) for item in (file_items or []) if item.get("path")]
+  chat_config = types.GenerateContentConfig(
+   cached_content=_gemini_cache.name,
+   temperature=_temperature,
+   max_output_tokens=_max_tokens,
+   safety_settings=[types.SafetySetting(category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=types.HarmBlockThreshold.BLOCK_ONLY_HIGH)]
+  )
+  _append_comms("OUT", "request", {"message": f"[CACHE CREATED] {_gemini_cache.name}"})
+  return Result(data=chat_config)
+ except Exception as e:
+  _gemini_cache             = None
+  _gemini_cache_created_at  = None
+  _gemini_cached_file_paths = []
+  _append_comms("OUT", "request", {"message": f"[CACHE FAILED] {type(e).__name__}: {e} \u2014 falling back to inline system_instruction"})
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to create gemini cache: {type(e).__name__}: {e}", source="ai_client._create_gemini_cache_result", original=e)],
+  )
+
+def _send_cli_round_result(r_idx: int, adapter: Any, payload: Any, safety_settings: list[Any], sys_instr: str, stream_callback: Optional[Callable[[str], None]]) -> Result[Metadata]:
+ """Call the Gemini CLI adapter for one round. Returns Result[resp_data].
+
+ On SDK failure, emits a response_received event with the error info
+ (preserving the original side-effect semantics) and returns
+ Result(errors=[ErrorInfo]). The caller (_send in _send_gemini_cli)
+ re-raises the original exception to preserve the outer catch flow.
+ """
+ events.emit("request_start", payload={"provider": "gemini_cli", "model": _model, "round": r_idx})
+ if r_idx > 0:
+  _append_comms("OUT", "request", {"message": f"[CLI] [round {r_idx}] [msg {len(payload)}]"})
+ send_payload: Any = json.dumps(payload) if isinstance(payload, list) else payload
+ try:
+  resp_data = adapter.send(cast(str, send_payload), safety_settings=safety_settings, system_instruction=sys_instr, model=_model, stream_callback=stream_callback)
+  return Result(data=resp_data)
+ except Exception as e:
+  events.emit("response_received", payload={"provider": "gemini_cli", "model": _model, "usage": {}, "latency": 0, "round": r_idx, "error": str(e)})
+  return Result(
+   data=None,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=str(e), source="ai_client._send_cli_round_result", original=e)],
+  )
+
+def _extract_gemini_thoughts_result(resp: Any) -> Result[str]:
+ """Extracts concatenated thinking text from a Gemini response object's parts.
+
+ Per the data-oriented convention: returns Result(data=thinking_text) on
+ success, Result(data="", errors=[ErrorInfo]) if attribute access fails.
+ The legacy caller (_extract_gemini_thoughts) returns result.data
+ (preserving the original str signature; an empty string signals "no
+ thoughts" to the caller).
+ """
+ chunks: list[str] = []
+ try:
+  candidates = getattr(resp, "candidates", None) or []
+  for cand in candidates:
+   content = getattr(cand, "content", None)
+   if content is None: continue
+   parts = getattr(content, "parts", None) or []
+   for p in parts:
+    if getattr(p, "thought", False) and getattr(p, "text", None):
+     chunks.append(p.text)
+  return Result(data="".join(chunks).strip())
+ except Exception as e:
+  return Result(
+   data="",
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to extract gemini thoughts: {e}", source="ai_client._extract_gemini_thoughts_result", original=e)],
+  )
+
+
+def _get_gemini_history_list(chat: Any | None) -> list[Any]:
+ if not chat: return []
+ if hasattr(chat, "_history"):    return cast(list[Any], chat._history)
+ if hasattr(chat, "history"):     return cast(list[Any], chat.history)
+ if hasattr(chat, "get_history"): return cast(list[Any], chat.get_history())
+ return []
+
+def _send_gemini(md_content: str, user_message: str, base_dir: str,
+  file_items:         list[Metadata] | None = None,
+  discussion_history: str = "",
+  pre_tool_callback:  Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+  qa_callback:        Optional[Callable[[str], str]] = None,
+  enable_tools:       bool = True,
+  stream_callback:    Optional[Callable[[str], None]] = None,
+  patch_callback:     Optional[Callable[[str, str], Result[str]]] = None
+ ) -> Result[str]:
+ """
+  Functional Purpose: Sends requests to Gemini via google-genai SDK, handling context caching, chat history, and tools.
+  Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, callbacks, enable_tools.
+  Immediate-Mode DAG / Thread Context: Called by: send; Calls: _ensure_gemini_client, client.caches.create, client.chats.create, run_with_tool_loop
+  SSDL: [I:_ensure_gemini_client] -> [B:Cache Changed?] -> [I:client.caches.create] -> [I:client.chats.create] -> [T:Result]
+  Thread Boundaries: Runs on caller thread (typically an async worker thread).
+ """
+ global _gemini_chat, _gemini_cache, _gemini_cache_md_hash, _gemini_cache_created_at, _gemini_cached_file_paths
+ genai   = _require_warmed("google.genai")
+ types   = genai.types
+ monitor = performance_monitor.get_monitor()
+ if monitor.enabled: monitor.start_component("ai_client._send_gemini")
+ try:
+  _ensure_gemini_client(); mcp_client.configure(file_items or [], [base_dir])
+  sys_instr       = f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>"
+  td              = _gemini_tool_declaration_result().data if enable_tools else None
+  tools_decl      = [td] if td else None
+  current_md_hash = hashlib.md5(md_content.encode()).hexdigest()
+  old_history     = None
+  assert _gemini_client is not None
+  if _gemini_chat and _gemini_cache_md_hash != current_md_hash:
+   old_history = list(_get_gemini_history_list(_gemini_chat)) if _get_gemini_history_list(_gemini_chat) else []
+   if _gemini_cache:
+    _delete_gemini_cache_result()
+   _gemini_chat              = None
+   _gemini_cache             = None
+   _gemini_cache_created_at  = None
+   _gemini_cached_file_paths = []
+   _append_comms("OUT", "request", {"message": "[CONTEXT CHANGED] Rebuilding cache and chat session..."})
+  if _gemini_chat and _gemini_cache and _gemini_cache_created_at:
+   elapsed = time.time() - _gemini_cache_created_at
+   if elapsed > _GEMINI_CACHE_TTL * 0.9:
+    old_history = list(_get_gemini_history_list(_gemini_chat)) if _get_gemini_history_list(_gemini_chat) else []
+    _delete_gemini_cache_result()
+    _gemini_chat              = None
+    _gemini_cache             = None
+    _gemini_cache_created_at  = None
+    _gemini_cached_file_paths = []
+    _append_comms("OUT", "request", {"message": f"[CACHE TTL] Rebuilding cache (expired after {int(elapsed)}s)..."})
+  
+  if not _gemini_chat:
+   chat_config = types.GenerateContentConfig(
+    system_instruction = sys_instr,
+    tools              = cast(Any, tools_decl),
+    temperature        = _temperature,
+    top_p              = _top_p,
+    max_output_tokens  = _max_tokens,
+    safety_settings    = [types.SafetySetting(category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=types.HarmBlockThreshold.BLOCK_ONLY_HIGH)]
+   )
+   
+   should_cache = _should_cache_gemini_result(sys_instr).data
+   if should_cache and _gemini_client:
+    cached_config_result = _create_gemini_cache_result(sys_instr, tools_decl, file_items)
+    if cached_config_result.ok:
+     chat_config = cached_config_result.data
+   kwargs: Metadata = {"model": _model, "config": chat_config}
+   if old_history:
+    kwargs["history"] = old_history
+   if _gemini_client:
+    _gemini_chat = _gemini_client.chats.create(**kwargs)
+    _gemini_cache_md_hash = current_md_hash
+    if discussion_history and not old_history:
+     _gemini_chat.send_message(f"[DISCUSSION HISTORY]\n\n{discussion_history}")
+     _append_comms("OUT", "request", {"message": f"[HISTORY INJECTED] {len(discussion_history)} chars"})
+  payload: str | list[types.Part] = user_message
+  all_text: list[str] = []
+  _cumulative_tool_bytes = 0
+  if _gemini_chat and _get_gemini_history_list(_gemini_chat):
+   for msg in _get_gemini_history_list(_gemini_chat):
+    if msg.role == "user" and hasattr(msg, "parts"):
+     for p in msg.parts:
+      if hasattr(p, "function_response") and p.function_response and hasattr(p.function_response, "response"):
+       r = p.function_response.response
+       if isinstance(r, dict) and "output" in r:
+        val = r["output"]
+        if isinstance(val, str):
+         marker = _get_context_marker()
+         if marker in val:
+          val = val.split(marker)[0].strip()
+         if _history_trunc_limit > 0 and len(val) > _history_trunc_limit:
+          val = val[:_history_trunc_limit] + "\n\n... [TRUNCATED BY SYSTEM TO SAVE TOKENS.]"
+         r["output"] = val
+  for r_idx in range(MAX_TOOL_ROUNDS + 2):
+   events.emit("request_start", payload={"provider": "gemini", "model": _model, "round": r_idx})
+
+   # Shared config for this round
+   td = _gemini_tool_declaration_result().data if enable_tools else None
+   config = types.GenerateContentConfig(
+    tools=[td] if td else [],
+    temperature=_temperature,
+    top_p=_top_p,
+    max_output_tokens=_max_tokens,
+   )
+
+   if stream_callback:
+    resp = _gemini_chat.send_message_stream(payload, config=config)
+    txt_chunks: list[str] = []
+    calls = []
+    usage = {}
+    reason = "STOP"
+    final_resp = None
+    for chunk in resp:
+     if chunk.text:
+      txt_chunks.append(chunk.text)
+      stream_callback(chunk.text)
+     if chunk.candidates:
+      c = chunk.candidates[0]
+      if c.content and c.content.parts:
+       calls.extend([p.function_call for p in c.content.parts if p.function_call])
+      if hasattr(c, "finish_reason") and c.finish_reason:
+       reason = c.finish_reason.name
+     if chunk.usage_metadata:
+      usage = {
+       "input_tokens": chunk.usage_metadata.prompt_token_count,
+       "output_tokens": chunk.usage_metadata.candidates_token_count,
+       "total_tokens": chunk.usage_metadata.total_token_count,
+       "cache_read_input_tokens": getattr(chunk.usage_metadata, "cached_content_token_count", 0)
+      }
+     final_resp = chunk
+    txt = "".join(txt_chunks)
+    if txt: all_text.append(txt)
+    # Final validation of response object for subsequent code
+    resp = final_resp 
+    events.emit("response_received", payload={"provider": "gemini", "model": _model, "usage": usage, "round": r_idx})
+   else:
+    resp = _gemini_chat.send_message(payload, config=config)
+    txt = resp.text or ""
+    if txt: all_text.append(txt)
+    calls = [p.function_call for c in resp.candidates if getattr(c, "content", None) for p in c.content.parts if p.function_call]
+    usage = {
+     "input_tokens": getattr(resp.usage_metadata, "prompt_token_count", 0), 
+     "output_tokens": getattr(resp.usage_metadata, "candidates_token_count", 0),
+     "total_tokens": getattr(resp.usage_metadata, "total_token_count", 0),
+     "cache_read_input_tokens": getattr(resp.usage_metadata, "cached_content_token_count", 0)
+    }
+    reason = resp.candidates[0].finish_reason.name if (resp.candidates and hasattr(resp.candidates[0], "finish_reason")) else "STOP"
+   events.emit("response_received", payload={"provider": "gemini", "model": _model, "usage": usage, "round": r_idx})
+
+   _append_comms("IN", "response", {"round": r_idx, "stop_reason": reason, "text": txt, "tool_calls": [{"name": c.name, "args": dict(c.args)} for c in calls], "usage": usage})
+   total_in = usage.get("input_tokens", 0)
+   if total_in > _GEMINI_MAX_INPUT_TOKENS * 0.4 and _gemini_chat and _get_gemini_history_list(_gemini_chat):
+    hist = _get_gemini_history_list(_gemini_chat)
+    dropped = 0
+    while len(hist) > 4 and total_in > _GEMINI_MAX_INPUT_TOKENS * 0.3:
+     saved = 0
+     for _ in range(2):
+      if not hist: break
+      for p in hist[0].parts:
+       if hasattr(p, "text") and p.text:
+        saved += int(len(p.text) / _CHARS_PER_TOKEN)
+       elif hasattr(p, "function_response") and p.function_response:
+        r = getattr(p.function_response, "response", {})
+        if isinstance(r, dict):
+         saved += int(len(str(r.get("output", ""))) / _CHARS_PER_TOKEN)
+      hist.pop(0)
+      dropped += 1
+     total_in -= max(saved, 200)
+    if dropped > 0:
+     _append_comms("OUT", "request", {"message": f"[GEMINI HISTORY TRIMMED: dropped {dropped} old entries to stay within token budget]"})
+   if not calls or r_idx > MAX_TOOL_ROUNDS: break
+   f_resps: list[types.Part] = []
+   log: list[Metadata] = []
+   
+   # Execute tools concurrently
+   try:
+    loop = asyncio.get_running_loop()
+    results = asyncio.run_coroutine_threadsafe(
+     _execute_tool_calls_concurrently(calls, base_dir, pre_tool_callback, qa_callback, r_idx, "gemini", patch_callback),
+     loop
+    ).result()
+   except RuntimeError:
+    results = asyncio.run(_execute_tool_calls_concurrently(calls, base_dir, pre_tool_callback, qa_callback, r_idx, "gemini", patch_callback))
+
+   for i, (name, call_id, out, _) in enumerate(results):
+    # Check if this is the last tool to trigger file refresh
+    if i == len(results) - 1:
+     if file_items:
+      _reread_result = _reread_file_items_result(file_items)
+      file_items, changed = _reread_result.data
+      ctx = _build_file_diff_text(changed)
+      if ctx:
+       out += f"\n\n{_get_context_marker()}\n\n{ctx}"
+     if r_idx == MAX_TOOL_ROUNDS: out += "\n\n[SYSTEM: MAX ROUNDS. PROVIDE FINAL ANSWER.]"
+    
+    out = _truncate_tool_output(out)
+    _cumulative_tool_bytes += len(out)
+    f_resps.append(types.Part(function_response=types.FunctionResponse(name=cast(str, name), response={"output": out})))
+    log.append({"tool_use_id": name, "content": out})
+    events.emit("tool_execution", payload={"status": "completed", "tool": name, "result": out, "round": r_idx})
+
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    f_resps.append(types.Part(text=
+      f"SYSTEM WARNING: Cumulative tool output exceeded {_MAX_TOOL_OUTPUT_BYTES // 1000}KB budget. Provide your final answer now."
+     ))
+    _append_comms("OUT", "request", {"message": f"[TOOL OUTPUT BUDGET EXCEEDED: {_cumulative_tool_bytes} bytes]"})
+   _append_comms("OUT", "tool_result_send", {"results": log})
+   payload = f_resps
+  res = "\n\n".join(all_text) if all_text else "(No text returned)"
+  thought_text_result = _extract_gemini_thoughts_result(final_resp if stream_callback else resp)
+  thought_text = thought_text_result.data if thought_text_result.ok else ""
+  if thought_text:
+   res = f"<thinking>\n{thought_text}\n</thinking>\n\n{res}"
+  if monitor.enabled: monitor.end_component("ai_client._send_gemini")
+  return Result(data=res)
+ except Exception as e:
+  if monitor.enabled: monitor.end_component("ai_client._send_gemini")
+  return Result(data="", errors=[_classify_gemini_error(e, source="ai_client.gemini")])
+
+def _send_gemini_cli(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ from src.openai_compatible import OpenAICompatibleRequest, NormalizedResponse
+ from src.openai_schemas import UsageStats
+ """
+  [C: src/ai_server.py:_handle_send]
+  Functional Purpose: Sends requests to Gemini via the headless Gemini CLI subprocess adapter.
+  Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, callbacks.
+  Immediate-Mode DAG / Thread Context: Called by: send; Calls: run_with_tool_loop, GeminiCliAdapter.send
+  SSDL:
+   [I:run_with_tool_loop] -> [I:GeminiCliAdapter.send] -> [T:Result]
+  Thread Boundaries: Runs on caller thread (typically an async worker thread).
+ """
+ global _gemini_cli_adapter
+ try:
+  if _gemini_cli_adapter is None:
+   _gemini_cli_adapter = GeminiCliAdapter(binary_path="gemini")
+  adapter = _gemini_cli_adapter
+  mcp_client.configure(file_items or [], [base_dir])
+  sys_instr = f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>"
+  safety_settings = [{'category': 'HARM_CATEGORY_DANGEROUS_CONTENT', 'threshold': 'BLOCK_ONLY_HIGH'}]
+  payload: Union[str, list[Metadata]] = user_message
+  if adapter.session_id is None:
+   if discussion_history:
+    payload = f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"
+  all_text: list[str] = []
+  cumulative_tool_bytes = 0
+
+  def _send(r_idx: int) -> NormalizedResponse:
+   if adapter is None:
+    return NormalizedResponse(text="(adapter unavailable)", tool_calls=[], usage=UsageStats(input_tokens=0, output_tokens=0, cache_read_tokens=0, cache_creation_tokens=0), raw_response=None)
+   send_result = _send_cli_round_result(r_idx, adapter, payload, safety_settings, sys_instr, stream_callback)
+   if not send_result.ok:
+    raise cast(Exception, send_result.errors[0].original) from None
+   resp_data = send_result.data
+   cli_stderr = resp_data.get("stderr", "")
+   if cli_stderr:
+    sys.stderr.write(f"\n--- Gemini CLI stderr ---\n{cli_stderr}\n-------------------------\n")
+    sys.stderr.flush()
+   txt = cast(str, resp_data.get("text", ""))
+   if txt: all_text.append(txt)
+   calls = cast(List[dict[str, Any]], resp_data.get("tool_calls", []))
+   usage = adapter.last_usage or {}
+   latency = adapter.last_latency
+   events.emit("response_received", payload={"provider": "gemini_cli", "model": _model, "usage": usage, "latency": latency, "round": r_idx})
+   log_calls: list[Metadata] = []
+   for c in calls:
+    log_calls.append({"name": c.get("name"), "args": c.get("args"), "id": c.get("id")})
+   _append_comms("IN", "response", {
+    "round": r_idx,
+    "stop_reason": "TOOL_USE" if calls else "STOP",
+    "text": txt,
+    "tool_calls": log_calls,
+    "usage": usage
+   })
+   if txt and calls:
+    cb = get_comms_log_callback_result().data
+    if cb:
+     cb({
+      "ts": project_manager.now_ts(),
+      "direction": "IN",
+      "kind": "history_add",
+      "payload": {"role": "AI", "content": txt}
+     })
+   return NormalizedResponse(text=txt, tool_calls=calls, usage=UsageStats(input_tokens=usage.get("prompt_tokens", 0), output_tokens=usage.get("completion_tokens", 0), cache_read_tokens=0, cache_creation_tokens=0), raw_response=resp_data)
+
+  def _pre_dispatch(r_idx: int, calls: list[Metadata]) -> list[Metadata]:
+   nonlocal payload, cumulative_tool_bytes, file_items
+   tool_results_for_cli: list[Metadata] = []
+   results_iter: list[tuple[str, str, str, str]] = []
+   from src.ai_client import _execute_tool_calls_concurrently as _executor
+   try:
+    loop = asyncio.get_running_loop()
+    results_iter = loop.run_until_complete(_executor(calls, base_dir, pre_tool_callback, qa_callback, r_idx, "gemini_cli", patch_callback)) if False else asyncio.run_coroutine_threadsafe(_executor(calls, base_dir, pre_tool_callback, qa_callback, r_idx, "gemini_cli", patch_callback), loop).result()
+   except RuntimeError:
+    results_iter = asyncio.run(_executor(calls, base_dir, pre_tool_callback, qa_callback, r_idx, "gemini_cli", patch_callback))
+   for i, (name, call_id, out, _) in enumerate(results_iter):
+    if i == len(results_iter) - 1:
+     if file_items:
+      _reread_result = _reread_file_items_result(file_items)
+      file_items, changed = _reread_result.data
+      ctx = _build_file_diff_text(changed)
+      if ctx:
+       out += f"\n\n{_get_context_marker()}\n\n{ctx}"
+     if r_idx == MAX_TOOL_ROUNDS:
+      out += "\n\n[SYSTEM: MAX ROUNDS. PROVIDE FINAL ANSWER.]"
+    out = _truncate_tool_output(out)
+    cumulative_tool_bytes += len(out)
+    tool_results_for_cli.append({"role": "tool", "tool_call_id": call_id, "name": name, "content": out})
+    _append_comms("IN", "tool_result", {"name": name, "id": call_id, "output": out})
+    events.emit("tool_execution", payload={"status": "completed", "tool": name, "result": out, "round": r_idx})
+   payload = tool_results_for_cli
+   if cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    _append_comms("OUT", "request", {"message": f"[TOOL OUTPUT BUDGET EXCEEDED: {cumulative_tool_bytes} bytes]"})
+   return calls
+
+  run_with_tool_loop(
+   client=adapter, request=lambda _i: cast(OpenAICompatibleRequest, None),
+   base_dir=base_dir, vendor_name="gemini_cli",
+   pre_tool_callback=pre_tool_callback, qa_callback=qa_callback,
+   stream_callback=stream_callback, patch_callback=patch_callback,
+   send_func=_send, on_pre_dispatch=_pre_dispatch,
+  )
+  final_text = all_text[-1] if all_text else "(No text returned)"
+  return Result(data=final_text)
+ except Exception as e:
+  return Result(data="", errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=str(e), source="ai_client.gemini_cli", original=e)])
+
+#endregion: Gemini Provider
+
+#region: DeepSeek Provider
+
+def _list_deepseek_models(api_key: str) -> list[str]:
+ return ["deepseek-chat", "deepseek-reasoner"]
+
+def _repair_deepseek_history(history: list[Metadata]) -> None:
+ if not history:
+  return
+ last = history[-1]
+ if last.get("role") != "assistant":
+  return
+ tool_calls = last.get("tool_calls", [])
+ if not tool_calls:
+  return
+ call_ids = [tc.get("id") for tc in tool_calls if tc.get("id")]
+ for cid in call_ids:
+  # Check if already present in tail (to be safe, though usually missing if we're here)
+  already_has = any(m.get("role") == "tool" and m.get("tool_call_id") == cid for m in history[-len(call_ids)-1:])
+  if not already_has:
+   history.append({
+     "role": "tool",
+
+     "tool_call_id": cid,
+     "content": "ERROR: Session was interrupted before tool result was recorded.",
+    })
+
+def _ensure_deepseek_client() -> None:
+ global _deepseek_client
+ if _deepseek_client is None:
+  _load_credentials()
+  pass
+
+def _send_deepseek(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  [C: src/ai_server.py:_handle_send]
+  Functional Purpose: Sends requests to DeepSeek via requests.post API call, managing history repairs and tools.
+  Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, stream, callbacks.
+  Immediate-Mode DAG / Thread Context: Called by: send; Calls: _ensure_deepseek_client, _repair_deepseek_history, requests.post
+  SSDL:
+   [I:_ensure_deepseek_client] -> [I:_repair_deepseek_history] -> [I:requests.post] -> [T:Result]
+  Thread Boundaries: Runs on caller thread (typically an async worker thread).
+ """
+ requests = _require_warmed("requests")
+ monitor = performance_monitor.get_monitor()
+ if monitor.enabled: monitor.start_component("ai_client._send_deepseek")
+ try:
+  mcp_client.configure(file_items or [], [base_dir])
+  creds = _load_credentials()
+  api_key = creds.get("deepseek", {}).get("api_key")
+  if not api_key:
+   if monitor.enabled: monitor.end_component("ai_client._send_deepseek")
+   raise ValueError("DeepSeek API key not found in credentials.toml")
+  history = provider_state.get_history("deepseek")
+  api_url = "https://api.deepseek.com/chat/completions"
+  headers = {
+   "Authorization": f"Bearer {api_key}",
+   "Content-Type": "application/json",
+  }
+  
+  is_reasoner = _model in ("deepseek-reasoner", "deepseek-r1")
+  
+  # Update history following Anthropic pattern
+  with history.lock:
+   _repair_deepseek_history(history)
+   if discussion_history and not history:
+    user_content = f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"
+   else:
+    user_content = user_message
+   history.append({"role": "user", "content": user_content})
+  
+  all_text_parts: list[str] = []
+  _cumulative_tool_bytes = 0
+  
+  for round_idx in range(MAX_TOOL_ROUNDS + 2):
+   current_api_messages: list[Metadata] = []
+   
+   # DeepSeek R1 (Reasoner) can be extremely strict about the 'system' role.
+   # For maximum compatibility, we'll only use 'system' for non-reasoner models.
+   if not is_reasoner:
+    sys_msg = {"role": "system", "content": f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>"}
+    current_api_messages.append(sys_msg)
+   
+   with history.lock:
+    from src.openai_schemas import ChatMessage as _ChatMessage
+    for i, msg_raw in enumerate(history):
+     msg = _ChatMessage.from_dict(msg_raw)
+     api_msg = {"role": msg.role}
+     
+     content = msg.content
+     if i == 0 and is_reasoner:
+      content = f"System Instructions:\n{_get_combined_system_prompt()}\n\nContext:\n{md_content}\n\n---\n\n{content}"
+     
+     if msg.role == "assistant":
+      if msg.tool_calls:
+       api_msg["content"] = content or None
+       api_msg["tool_calls"] = [tc.to_dict() for tc in msg.tool_calls]
+      else:
+       api_msg["content"] = content or ""
+      if msg_raw.get("reasoning_content"):
+       api_msg["reasoning_content"] = msg_raw["reasoning_content"]
+     elif msg.role == "tool":
+      api_msg["content"] = content or ""
+      api_msg["tool_call_id"] = msg.tool_call_id
+     else:
+      api_msg["content"] = content or ""
+     
+     current_api_messages.append(api_msg)
+   
+   request_payload: Metadata = {
+    "model": _model,
+    "messages": current_api_messages,
+    "stream": stream,
+   }
+   
+   if stream:
+    request_payload["stream_options"] = {"include_usage": True}
+   
+   if not is_reasoner:
+    request_payload["temperature"] = _temperature
+    request_payload["top_p"] = _top_p
+    # DeepSeek max_tokens is for the output, clamp to 8192 which is their hard limit for V3/Chat
+    request_payload["max_tokens"] = min(_max_tokens, 8192)
+    tools = _get_deepseek_tools()
+    if tools:
+     request_payload["tools"] = tools
+   
+   events.emit("request_start", payload={"provider": "deepseek", "model": _model, "round": round_idx, "streaming": stream})
+   
+   try:
+    response = requests.post(api_url, headers=headers, json=request_payload, timeout=120, stream=stream)
+    response.raise_for_status()
+   except requests.exceptions.RequestException as e:
+    if monitor.enabled: monitor.end_component("ai_client._send_deepseek")
+    return Result(data="", errors=[_classify_deepseek_error(e, source="ai_client.deepseek")])
+
+   assistant_text = ""
+   tool_calls_raw = []
+   reasoning_content = ""
+   finish_reason = "stop"
+   usage = {}
+
+   if stream:
+    aggregated_content = ""
+    aggregated_tool_calls: list[Metadata] = []
+    aggregated_reasoning = ""
+    current_usage: Metadata = {}
+    final_finish_reason = "stop"
+    for line in response.iter_lines():
+     if not line:
+      continue
+     decoded = line.decode('utf-8')
+     if decoded.startswith('data: '):
+      chunk_str = decoded[len('data: '):]
+      if chunk_str.strip() == '[DONE]':
+       continue
+      try:
+       chunk = json.loads(chunk_str)
+       if not chunk.get("choices"):
+        if chunk.get("usage"):
+         current_usage = cast(Metadata, chunk["usage"])
+        continue
+       delta = cast(Metadata, chunk.get("choices", [{}])[0].get("delta", {}))
+       if delta.get("content"):
+        content_chunk = cast(str, delta["content"])
+        aggregated_content += content_chunk
+        if stream_callback:
+         stream_callback(content_chunk)
+       if delta.get("reasoning_content"):
+        aggregated_reasoning += cast(str, delta["reasoning_content"])
+       if delta.get("tool_calls"):
+        for tc_delta in cast(List[dict[str, Any]], delta["tool_calls"]):
+         idx = cast(int, tc_delta.get("index", 0))
+         while len(aggregated_tool_calls) <= idx:
+          aggregated_tool_calls.append({"id": "", "type": "function", "function": {"name": "", "arguments": ""}})
+         target = aggregated_tool_calls[idx]
+         if tc_delta.get("id"):
+          target["id"] = cast(str, tc_delta["id"])
+         if tc_delta.get("function", {}).get("name"):
+          target["function"]["name"] += cast(str, tc_delta["function"]["name"])
+         if tc_delta.get("function", {}).get("arguments"):
+          target["function"]["arguments"] += cast(str, tc_delta["function"]["arguments"])
+       if chunk.get("choices", [{}])[0].get("finish_reason"):
+        final_finish_reason = cast(str, chunk["choices"][0]["finish_reason"])
+       if chunk.get("usage"):
+        current_usage = cast(Metadata, chunk["usage"])
+      except json.JSONDecodeError:
+       continue
+    assistant_text = aggregated_content
+    tool_calls_raw = aggregated_tool_calls
+    reasoning_content = aggregated_reasoning
+    finish_reason = final_finish_reason
+    usage = current_usage
+   else:
+    response_data = response.json()
+    choices = response_data.get("choices", [])
+    if not choices:
+     _append_comms("IN", "response", {"round": round_idx, "text": "(No choices returned)", "usage": response_data.get("usage", {})})
+     break
+    choice = choices[0]
+    from src.openai_schemas import ChatMessage as _CM
+    message = _CM.from_dict(choice.get("message", {}))
+    assistant_text = message.content or ""
+    tool_calls_raw = [tc.to_dict() for tc in message.tool_calls] if message.tool_calls else []
+    reasoning_content = choice.get("message", {}).get("reasoning_content", "")
+    finish_reason = choice.get("finish_reason", "stop")
+    usage = response_data.get("usage", {})
+
+   thinking_tags = ""
+   if reasoning_content:
+    thinking_tags = f"<thinking>\n{reasoning_content}\n</thinking>\n"
+   full_assistant_text = thinking_tags + assistant_text
+   
+   with history.lock:
+    # DeepSeek/OpenAI: If tool_calls are present, content can be null but should usually be present
+    msg_to_store: Metadata = {"role": "assistant", "content": assistant_text or None}
+    if reasoning_content:
+     msg_to_store["reasoning_content"] = reasoning_content
+    if tool_calls_raw:
+     msg_to_store["tool_calls"] = tool_calls_raw
+    history.append(msg_to_store)
+   
+   if full_assistant_text:
+    all_text_parts.append(full_assistant_text)
+   
+   _append_comms("IN", "response", {
+     "round": round_idx,
+     "stop_reason": finish_reason,
+     "text": full_assistant_text,
+     "tool_calls": tool_calls_raw,
+     "usage": usage,
+     "streaming": stream
+    })
+   
+   if finish_reason != "tool_calls" and not tool_calls_raw:
+    break
+   if round_idx > MAX_TOOL_ROUNDS:
+    break
+   
+   # Execute tools concurrently
+   try:
+    loop = asyncio.get_running_loop()
+    results = asyncio.run_coroutine_threadsafe(
+     _execute_tool_calls_concurrently(tool_calls_raw, base_dir, pre_tool_callback, qa_callback, round_idx, "deepseek", patch_callback),
+     loop
+    ).result()
+   except RuntimeError:
+    results = asyncio.run(_execute_tool_calls_concurrently(tool_calls_raw, base_dir, pre_tool_callback, qa_callback, round_idx, "deepseek", patch_callback))
+
+   tool_results_for_history: list[Metadata] = []
+   for i, (name, call_id, out, _) in enumerate(results):
+    if i == len(results) - 1:
+     if file_items:
+      _reread_result = _reread_file_items_result(file_items)
+      file_items, changed = _reread_result.data
+      ctx = _build_file_diff_text(changed)
+      if ctx:
+       out += f"\n\n{_get_context_marker()}\n\n{ctx}"
+     if round_idx == MAX_TOOL_ROUNDS:
+      out += "\n\n[SYSTEM: MAX ROUNDS. PROVIDE FINAL ANSWER.]"
+    
+    truncated = _truncate_tool_output(out)
+    _cumulative_tool_bytes += len(truncated)
+    tool_results_for_history.append({
+      "role": "tool",
+      "tool_call_id": call_id,
+      "content": truncated,
+     })
+    _append_comms("IN", "tool_result", {"name": name, "id": call_id, "output": out})
+    events.emit("tool_execution", payload={"status": "completed", "tool": name, "result": out, "round": round_idx})
+
+   if _cumulative_tool_bytes > _MAX_TOOL_OUTPUT_BYTES:
+    tool_results_for_history.append({
+      "role": "user",
+      "content": f"SYSTEM WARNING: Cumulative tool output exceeded {_MAX_TOOL_OUTPUT_BYTES // 1000}KB budget. Provide your final answer now."
+     })
+    _append_comms("OUT", "request", {"message": f"[TOOL OUTPUT BUDGET EXCEEDED: {_cumulative_tool_bytes} bytes]"})
+   
+   with history.lock:
+    for tr in tool_results_for_history:
+     history.append(tr)
+   
+  res = "\n\n".join(all_text_parts) if all_text_parts else "(No text returned)"
+  if monitor.enabled: monitor.end_component("ai_client._send_deepseek")
+  return Result(data=res)
+ except Exception as e:
+  if monitor.enabled: monitor.end_component("ai_client._send_deepseek")
+  return Result(data="", errors=[_classify_deepseek_error(e, source="ai_client.deepseek")])
+
+#endregion: DeepSeek Provider
+
+#region: MiniMax Provider
+
+_MINIMAX_DEFAULT_MODELS: list[str] = ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.1", "MiniMax-M2"]
+
+#TODO(Ed): This causes a pause on gui thread, this should be cached.
+def _list_minimax_models_result(api_key: str) -> Result[list[str]]:
+ """List available MiniMax models via the OpenAI-compatible SDK.
+
+ Returns Result(data=sorted_models) on success, Result(data=defaults, errors=[ErrorInfo])
+ on SDK failure. The legacy caller (_list_minimax_models) returns result.data
+ (preserving the original list[str] signature; defaults are returned on failure
+ to maintain the original behavior).
+ """
+ try:
+  openai = _require_warmed("openai")
+  OpenAI = openai.OpenAI
+  creds = _load_credentials()
+  base_url = creds.get("minimax", {}).get("base_url") or "https://api.minimax.io/v1"
+  client = OpenAI(api_key=api_key, base_url=base_url)
+  models_list = client.models.list()
+  found = [m.id for m in models_list]
+  if found:
+   return Result(data=sorted(found))
+  return Result(data=_MINIMAX_DEFAULT_MODELS)
+ except Exception as e:
+  return Result(
+   data=_MINIMAX_DEFAULT_MODELS,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to list minimax models: {e}", source="ai_client._list_minimax_models_result", original=e)],
+  )
+
+
+def _repair_minimax_history(history: list[Metadata]) -> None:
+ if not history: return
+ last = history[-1]
+ if last.get("role") != "assistant": return
+ tool_calls = last.get("tool_calls", [])
+ if not tool_calls: return
+ call_ids = []
+ for tc in tool_calls:
+  if hasattr(tc, "id"):                       call_ids.append(tc.id)
+  elif isinstance(tc, dict) and tc.get("id"): call_ids.append(tc["id"])
+ 
+ for cid in call_ids:
+  from src.openai_schemas import ChatMessage as _CM
+  already_has = any(_CM.from_dict(m).role == "tool" and _CM.from_dict(m).tool_call_id == cid for m in history[-len(call_ids)-1:])
+  if not already_has:
+   history.append({
+     "role":         "tool",
+     "tool_call_id": cid,
+     "content":      "ERROR: Session was interrupted before tool result was recorded.",
+    })
+
+def _trim_minimax_history(system_blocks: list[Metadata], history: list[Metadata]) -> int:
+ est = _estimate_prompt_tokens(system_blocks, history)
+ limit = 180_000
+ if est <= limit:
+  return 0
+ dropped = 0
+ while len(history) > 3 and est > limit:
+  if history[1].get("role") == "assistant" and len(history) > 2 and history[2].get("role") == "user":
+   removed_asst = history.pop(1)
+   removed_user = history.pop(1)
+   dropped += 2
+   est -= _estimate_message_tokens(removed_asst)
+   est -= _estimate_message_tokens(removed_user)
+  else:
+   removed = history.pop(1)
+   dropped += 1
+   est -= _estimate_message_tokens(removed)
+   
+  # Ensure we don't leave dangling 'tool' messages if their parent 'assistant' was dropped.
+  # MiniMax strictly requires 'tool' messages to immediately follow 'assistant' with tool_calls.
+  while len(history) > 1 and history[1].get("role") == "tool":
+   removed_tool = history.pop(1)
+   dropped += 1
+   est -= _estimate_message_tokens(removed_tool)
+ return dropped
+
+def _ensure_minimax_client() -> None:
+ global _minimax_client
+ openai = _require_warmed("openai")
+ if _minimax_client is None:
+  creds = _load_credentials()
+  api_key = creds.get("minimax", {}).get("api_key")
+  if not api_key:
+   raise ValueError("MiniMax API key not found in credentials.toml")
+  base_url = creds.get("minimax", {}).get("base_url") or "https://api.minimax.io/v1"
+  _minimax_client = openai.OpenAI(api_key=api_key, base_url=base_url)
+
+def _ensure_grok_client() -> Any:
+ global _grok_client
+ if _grok_client is None:
+  openai = _require_warmed("openai")
+  creds = _load_credentials()
+  api_key = creds.get("grok", {}).get("api_key")
+  if not api_key:
+   raise ValueError("Grok API key not found in credentials.toml")
+  _grok_client = openai.OpenAI(api_key=api_key, base_url="https://api.x.ai/v1")
+ return _grok_client
+
+def _send_grok(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  Dispatches queries to Grok (x.ai) model endpoint using OpenAI compatible client.
+
+  Functional Purpose:
+   Initializes/ensures Grok client, sets up tool schema, appends new messages to Grok history,
+   constructs the Grok request structure, and executes it via the run_with_tool_loop.
+
+  Parameters & Inputs:
+   md_content (str): Markdown formatted context content.
+   user_message (str): User prompt text.
+   base_dir (str): Workspace root directory.
+   file_items (Optional[FileItems]): Media or file items for multimodal queries.
+   discussion_history (str): Contextual discussion text.
+   stream (bool): Whether to stream output.
+   pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation.
+   qa_callback (Optional[Callable]): Verification callback for QA checks.
+   stream_callback (Optional[Callable]): Callback function for streaming chunks.
+   patch_callback (Optional[Callable]): Validation callback for code edits.
+
+  Returns:
+   Result[str]: Wrap of string response and potential errors.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send
+   Calls: _ensure_grok_client, _get_deepseek_tools, get_capabilities, run_with_tool_loop
+
+  SSDL:
+   `[I:_ensure_grok_client] -> [I:run_with_tool_loop] -> [T:Result]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread; synchronizes Grok history using _grok_history_lock.
+ """
+ from src.openai_compatible import OpenAICompatibleRequest, _classify_openai_compatible_error
+ from src.openai_schemas import ChatMessage, UsageStats
+ try:
+  client = _ensure_grok_client()
+  tools: list[Metadata] | None = _get_deepseek_tools() or None
+  caps = get_capabilities("grok", _model)
+  history = provider_state.get_history("grok")
+  with history.lock:
+   user_content = user_message
+   if file_items:
+    for fi in file_items:
+     if fi.get("is_image") and fi.get("base64_data"):
+      from src.project_files import FileItem
+      fi_item = fi if isinstance(fi, FileItem) else FileItem.from_dict(fi)
+      user_content = f"[IMAGE: {fi_item.path or 'attachment'}]\n{user_content}"
+   if discussion_history and not history:
+    history.append({"role": "user", "content": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"})
+   else:
+    history.append({"role": "user", "content": user_content})
+  def _build_grok_request(_round_idx: int) -> OpenAICompatibleRequest:
+   with history.lock:
+    history_msgs: list[ChatMessage] = [ChatMessage(role=m["role"], content=m["content"]) for m in history]
+    messages: list[ChatMessage] = [ChatMessage(role="system", content=f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>")]
+    messages.extend(history_msgs)
+   extra_body: Metadata = {}
+   if caps.web_search:
+    extra_body["search_parameters"] = {"mode": "auto"}
+   if caps.x_search:
+    extra_body.setdefault("search_parameters", {})
+    extra_body["search_parameters"]["sources"] = [{"type": "x"}]
+   return OpenAICompatibleRequest(
+    messages=messages, model=_model, temperature=_temperature, top_p=_top_p,
+    max_tokens=_max_tokens, stream=stream, stream_callback=stream_callback,
+    tools=tools, tool_choice="auto" if tools else "auto",
+    extra_body=extra_body or None,
+   )
+  return Result(data=run_with_tool_loop(
+   client, _build_grok_request, capabilities=caps,
+   pre_tool_callback=pre_tool_callback, qa_callback=qa_callback, stream_callback=stream_callback,
+   patch_callback=patch_callback, base_dir=base_dir, vendor_name="grok",
+   history_lock=history.lock, history=history,
+  ))
+ except Exception as exc:
+  return Result(data="", errors=[_classify_openai_compatible_error(exc, source="ai_client.grok")])
+
+def _list_grok_models() -> list[str]:
+ return list_models_for_vendor("grok")
+
+def _send_minimax(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  Dispatches queries to the MiniMax provider using OpenAI compatible client.
+
+  Functional Purpose:
+   Ensures client setup, performs MiniMax-specific history repairs, appends new messages,
+   constructs the MiniMax request structure, extracts reasoning content, and executes it via the tool loop.
+
+  Parameters & Inputs:
+   md_content (str): Markdown formatted context content.
+   user_message (str): User prompt text.
+   base_dir (str): Workspace root directory.
+   file_items (Optional[FileItems]): Media or file items for multimodal queries.
+   discussion_history (str): Contextual discussion text.
+   stream (bool): Whether to stream output.
+   pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation.
+   qa_callback (Optional[Callable]): Verification callback for QA checks.
+   stream_callback (Optional[Callable]): Callback function for streaming chunks.
+   patch_callback (Optional[Callable]): Validation callback for code edits.
+
+  Returns:
+   Result[str]: Wrap of string response and potential errors.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send
+   Calls: _ensure_minimax_client, _repair_minimax_history, _get_deepseek_tools,
+          get_capabilities, run_with_tool_loop
+
+  SSDL:
+   `[I:_ensure_minimax_client] -> [I:_repair_minimax_history] -> [I:run_with_tool_loop] -> [T:Result]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread; synchronizes MiniMax history using _minimax_history_lock.
+ """
+ from src.openai_compatible import OpenAICompatibleRequest
+ from src.openai_schemas import ChatMessage
+ try:
+  _ensure_minimax_client()
+  history = provider_state.get_history("minimax")
+  tools: list[Metadata] | None = _get_deepseek_tools() or None
+  _repair_minimax_history(history)
+  if discussion_history and not history:
+   history.append({"role": "user", "content": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"})
+  else:
+   history.append({"role": "user", "content": user_message})
+  def _build_minimax_request(_round_idx: int) -> OpenAICompatibleRequest:
+   with history.lock:
+    history_msgs: list[ChatMessage] = [ChatMessage(role=m["role"], content=m["content"]) for m in history]
+    messages: list[ChatMessage] = [ChatMessage(role="system", content=f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>")]
+    messages.extend(history_msgs)
+   return OpenAICompatibleRequest(
+    messages=messages, model=_model, temperature=_temperature, top_p=_top_p,
+    max_tokens=min(_max_tokens, 8192), stream=stream, stream_callback=stream_callback,
+    tools=tools, tool_choice="auto" if tools else "auto",
+   )
+  def _extract_minimax_reasoning(raw_response: Any) -> str:
+   if raw_response and hasattr(raw_response, "choices"):
+    choice = raw_response.choices[0]
+    if hasattr(choice.message, "reasoning_details") and choice.message.reasoning_details:
+     return choice.message.reasoning_details[0].get("text", "") or ""
+   return ""
+  caps = get_capabilities("minimax", _model)
+  return Result(data=run_with_tool_loop(
+   _minimax_client, _build_minimax_request, capabilities=caps,
+   pre_tool_callback=pre_tool_callback, qa_callback=qa_callback, stream_callback=stream_callback,
+   patch_callback=patch_callback, base_dir=base_dir, vendor_name="minimax",
+   history_lock=history.lock, history=history,
+   trim_func=lambda h: _trim_minimax_history(_build_minimax_request(0).messages, h),
+   reasoning_extractor=_extract_minimax_reasoning if caps.reasoning else None,
+   wrap_reasoning_in_text=bool(caps.reasoning),
+  ))
+ except Exception as exc:
+  return Result(data="", errors=[_classify_minimax_error(exc, source="ai_client.minimax")])
+
+#endregion: MiniMax Provider
+
+#region: Qwen Provider
+
+def _ensure_qwen_client() -> None:
+ global _qwen_client, _qwen_region
+ if _qwen_client is None:
+  import dashscope
+  creds = _load_credentials()
+  api_key = creds.get("qwen", {}).get("api_key")
+  if not api_key:
+   raise ValueError("Qwen API key not found in credentials.toml")
+  _qwen_region = creds.get("qwen", {}).get("region", "china")
+  if _qwen_region == "international":
+   dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"
+  else:
+   dashscope.base_http_api_url = "https://dashscope.aliyuncs.com/api/v1"
+  dashscope.api_key = api_key
+  _qwen_client = dashscope.Generation
+
+def _dashscope_call(
+ model: str,
+ messages: list[Metadata],
+ tools: list[Metadata] | None,
+ *,
+ max_tokens: int,
+ temperature: float,
+ top_p: float,
+) -> Metadata:
+ import dashscope
+ from src.qwen_adapter import build_dashscope_tools
+ kwargs: Metadata = {
+  "model": model,
+  "messages": messages,
+  "max_tokens": max_tokens,
+  "temperature": temperature,
+  "top_p": top_p,
+  "result_format": "message",
+ }
+ if tools:
+  kwargs["tools"] = build_dashscope_tools(tools)
+ resp = dashscope.Generation.call(**kwargs)
+ if getattr(resp, "status_code", 200) != 200:
+  from src.qwen_adapter import classify_dashscope_error
+  raise classify_dashscope_error(_dashscope_exception_from_response(resp)) from None
+ return {
+  "text": resp.output.text if hasattr(resp, "output") and resp.output else "",
+  "tool_calls": _extract_dashscope_tool_calls(resp),
+  "usage": {
+   "input_tokens": getattr(resp.usage, "input_tokens", 0) if hasattr(resp, "usage") and resp.usage else 0,
+   "output_tokens": getattr(resp.usage, "output_tokens", 0) if hasattr(resp, "usage") and resp.usage else 0,
+  },
+ }
+
+def _dashscope_exception_from_response(resp: Any) -> Exception:
+ msg = getattr(resp, "message", "unknown dashscope error")
+ return RuntimeError(msg)
+
+def _extract_dashscope_tool_calls(resp: Any) -> list[Metadata]:
+ out: list[Metadata] = []
+ if not (hasattr(resp, "output") and resp.output and getattr(resp.output, "tool_calls", None)):
+  return out
+ for tc in resp.output.tool_calls:
+  out.append({
+   "id": getattr(tc, "id", ""),
+   "type": "function",
+   "function": {
+    "name": getattr(tc.function, "name", "") if hasattr(tc, "function") else "",
+    "arguments": getattr(tc.function, "arguments", "{}") if hasattr(tc, "function") else "{}",
+   },
+  })
+ return out
+
+def _list_qwen_models() -> list[str]:
+ return list_models_for_vendor("qwen")
+
+def _send_qwen(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  Dispatches queries to Alibaba's Qwen model via DashScope SDK.
+
+  Functional Purpose:
+   Initializes/ensures DashScope setup, builds the conversation history,
+   and delegates the invocation to _dashscope_call which triggers dashscope.Generation.call.
+
+  Parameters & Inputs:
+   md_content (str): Markdown formatted context content.
+   user_message (str): User prompt text.
+   base_dir (str): Workspace root directory.
+   file_items (Optional[FileItems]): Media or file items for multimodal queries.
+   discussion_history (str): Contextual discussion text.
+   stream (bool): Whether to stream output.
+   pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation.
+   qa_callback (Optional[Callable]): Verification callback for QA checks.
+   stream_callback (Optional[Callable]): Callback function for streaming chunks.
+   patch_callback (Optional[Callable]): Validation callback for code edits.
+
+  Returns:
+   Result[str]: Wrap of string response and potential errors.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send
+   Calls: _ensure_qwen_client, _dashscope_call
+
+  SSDL:
+   `[I:_ensure_qwen_client] -> [I:dashscope.Generation.call] -> [T:Result]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread; synchronizes history using _qwen_history_lock.
+ """
+ from src.qwen_adapter import classify_dashscope_error
+ try:
+  _ensure_qwen_client()
+  history = provider_state.get_history("qwen")
+  with history.lock:
+   user_content = user_message
+   if file_items:
+    for fi in file_items:
+     if fi.get("is_image") and fi.get("base64_data"):
+      from src.project_files import FileItem
+      fi_item = fi if isinstance(fi, FileItem) else FileItem.from_dict(fi)
+      user_content = f"[IMAGE: {fi_item.path or 'attachment'}]\n{user_content}"
+   if discussion_history and not history:
+    history.append({"role": "user", "content": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"})
+   else:
+    history.append({"role": "user", "content": user_content})
+   messages = [{"role": "system", "content": f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>"}]
+   messages.extend(history)
+  resp = _dashscope_call(
+   model=_model,
+   messages=messages,
+   tools=None,
+   max_tokens=_max_tokens,
+   temperature=_temperature,
+   top_p=_top_p,
+  )
+  return Result(data=resp.get("text", ""))
+ except Exception as exc:
+  return Result(data="", errors=[classify_dashscope_error(exc, source="ai_client.qwen")])
+
+#endregion: Qwen Provider
+
+#region: Llama Provider
+
+def _ensure_llama_client() -> Any:
+ global _llama_client, _llama_base_url, _llama_api_key
+ if _llama_client is None:
+  openai = _require_warmed("openai")
+  creds = _load_credentials()
+  configured_url = creds.get("llama", {}).get("base_url")
+  configured_key = creds.get("llama", {}).get("api_key")
+  if configured_url:
+   _llama_base_url = configured_url
+  if configured_key is not None:
+   _llama_api_key = configured_key or "ollama"
+  _llama_client = openai.OpenAI(api_key=_llama_api_key, base_url=_llama_base_url)
+ return _llama_client
+
+def _send_llama(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  Dispatches queries to Llama-based models using OpenAI compatible client or native Ollama backend.
+
+  Functional Purpose:
+   Routes execution either to _send_llama_native (if using a local/Ollama base URL) or
+   to the OpenAI compatible client setup with history management and tool loop execution.
+
+  Parameters & Inputs:
+   md_content (str): Markdown formatted context content.
+   user_message (str): User prompt text.
+   base_dir (str): Workspace root directory.
+   file_items (Optional[FileItems]): Media or file items for multimodal queries.
+   discussion_history (str): Contextual discussion text.
+   stream (bool): Whether to stream output.
+   pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation.
+   qa_callback (Optional[Callable]): Verification callback for QA checks.
+   stream_callback (Optional[Callable]): Callback function for streaming chunks.
+   patch_callback (Optional[Callable]): Validation callback for code edits.
+
+  Returns:
+   Result[str]: Wrap of string response and potential errors.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send
+   Calls: _send_llama_native, _ensure_llama_client, _get_deepseek_tools,
+          get_capabilities, run_with_tool_loop
+
+  SSDL:
+   `[I:_ensure_llama_client] -> [I:run_with_tool_loop] -> [T:Result]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread; synchronizes history using _llama_history_lock.
+ """
+ from src.openai_compatible import OpenAICompatibleRequest, _classify_openai_compatible_error
+ from src.openai_schemas import ChatMessage
+ try:
+  if "localhost" in _llama_base_url or "127.0.0.1" in _llama_base_url:
+   return _send_llama_native(md_content, user_message, base_dir, file_items, discussion_history, stream, pre_tool_callback, qa_callback, stream_callback, patch_callback)
+  client = _ensure_llama_client()
+  tools: list[Metadata] | None = _get_deepseek_tools() or None
+  history = provider_state.get_history("llama")
+  with history.lock:
+   user_content = user_message
+   if file_items:
+    for fi in file_items:
+     if fi.get("is_image") and fi.get("base64_data"):
+      from src.project_files import FileItem
+      fi_item = fi if isinstance(fi, FileItem) else FileItem.from_dict(fi)
+      user_content = f"[IMAGE: {fi_item.path or 'attachment'}]\n{user_content}"
+   if discussion_history and not history:
+    history.append({"role": "user", "content": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"})
+   else:
+    history.append({"role": "user", "content": user_content})
+  def _build_llama_request(_round_idx: int) -> OpenAICompatibleRequest:
+   with history.lock:
+    history_msgs: list[ChatMessage] = [ChatMessage(role=m["role"], content=m["content"]) for m in history]
+    messages: list[ChatMessage] = [ChatMessage(role="system", content=f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>")]
+    messages.extend(history_msgs)
+   return OpenAICompatibleRequest(
+    messages=messages, model=_model, temperature=_temperature, top_p=_top_p,
+    max_tokens=_max_tokens, stream=stream, stream_callback=stream_callback,
+    tools=tools, tool_choice="auto" if tools else "auto",
+   )
+  caps = get_capabilities("llama", _model)
+  return Result(data=run_with_tool_loop(
+   client, _build_llama_request, capabilities=caps,
+   pre_tool_callback=pre_tool_callback, qa_callback=qa_callback, stream_callback=stream_callback,
+   patch_callback=patch_callback, base_dir=base_dir, vendor_name="llama",
+   history_lock=history.lock, history=history,
+  ))
+ except Exception as exc:
+  return Result(data="", errors=[_classify_openai_compatible_error(exc, source="ai_client.llama")])
+
+OLLAMA_DEFAULT_BASE_URL: str = "http://localhost:11434"
+
+def ollama_chat(
+ model: str,
+ messages: list[Metadata],
+ *,
+ think: str = "low",
+ images: list[str] | None = None,
+ tools: list[Metadata] | None = None,
+ base_url: str = OLLAMA_DEFAULT_BASE_URL,
+ ) -> Metadata:
+ requests = _require_warmed("requests")
+ payload: Metadata = {"model": model, "messages": messages, "stream": False}
+ if think:
+  payload["think"] = think
+ if images:
+  payload["images"] = images
+ if tools:
+  payload["tools"] = tools
+ resp = requests.post(f"{base_url}/api/chat", json=payload, timeout=120)
+ return resp.json()
+
+def _send_llama_native(md_content: str, user_message: str, base_dir: str,
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None) -> Result[str]:
+ """
+  Dispatches queries natively to local Ollama endpoints using direct HTTP requests.
+
+  Functional Purpose:
+   Bypasses the OpenAI compatible wrapper to interact directly with the Ollama REST API.
+   Supports image attachments and extracts deep thinking logs (if present) to format the response.
+
+  Parameters & Inputs:
+   md_content (str): Markdown formatted context content.
+   user_message (str): User prompt text.
+   base_dir (str): Workspace root directory.
+   file_items (Optional[FileItems]): Media or file items for multimodal queries.
+   discussion_history (str): Contextual discussion text.
+   stream (bool): Whether to stream output.
+   pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation.
+   qa_callback (Optional[Callable]): Verification callback for QA checks.
+   stream_callback (Optional[Callable]): Callback function for streaming chunks.
+   patch_callback (Optional[Callable]): Validation callback for code edits.
+
+  Returns:
+   Result[str]: Wrap of string response (possibly including thinking blocks) and potential errors.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: _send_llama
+   Calls: ollama_chat
+
+  SSDL:
+   `[I:_ensure_llama_client] -> [I:run_with_tool_loop] -> [T:Result]`
+
+  Thread Boundaries:
+   Runs synchronously in the caller thread; synchronizes history using _llama_history_lock.
+ """
+ try:
+  base_url = _llama_base_url.replace("/v1", "")
+  history = provider_state.get_history("llama")
+  with history.lock:
+   if discussion_history and not history:
+    history.append({"role": "user", "content": f"[DISCUSSION HISTORY]\n\n{discussion_history}\n\n---\n\n{user_message}"})
+   else:
+    history.append({"role": "user", "content": user_message})
+   messages: list[Metadata] = [{"role": "system", "content": f"{_get_combined_system_prompt()}\n\n<context>\n{md_content}\n</context>"}]
+   messages.extend(history)
+   images: list[str] = []
+   if file_items:
+    for fi in file_items:
+     if fi.get("is_image") and fi.get("base64_data"):
+      images.append(fi["base64_data"])
+  response = ollama_chat(_model, messages, images=images, base_url=base_url)
+  text = response.get("message", {}).get("content", "")
+  thinking = response.get("message", {}).get("thinking", "")
+  with history.lock:
+   msg: Metadata = {"role": "assistant", "content": text or None}
+   if thinking:
+    msg["thinking"] = thinking
+   history.append(msg)
+  return Result(data=(f"<thinking>\n{thinking}\n</thinking>\n" if thinking else "") + text)
+ except Exception as exc:
+  return Result(data="", errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=str(exc), source="ai_client.llama_native", original=exc)])
+
+def _list_llama_models() -> list[str]:
+ return list_models_for_vendor("llama")
+
+def _get_llama_cost_tracking() -> bool:
+ if "localhost" in _llama_base_url or "127.0.0.1" in _llama_base_url:
+  return False
+ try:
+  caps = get_capabilities("llama", _model)
+  return caps.cost_tracking
+ except KeyError:
+  return True
+
+#endregion: Llama Provider
+
+#region: Tier 4 Analysis
+
+def _run_tier4_analysis_result(stderr: str) -> Result[str]:
+ """Tier 4 QA agent: analyze stderr and propose a fix in ~20 words.
+
+ Returns Result(data=analysis) on success, Result(data="", errors=[ErrorInfo])
+ on SDK failure. The legacy caller (run_tier4_analysis) returns result.data
+ (preserving the original str signature; failures surface as empty string
+ to keep the qa_callback contract).
+ """
+ if not stderr or not stderr.strip():
+  return Result(data="")
+ try:
+  _ensure_gemini_client()
+  if not _gemini_client:
+   return Result(data="")
+  genai = _require_warmed("google.genai")
+  types = genai.types
+  prompt = (
+   f"You are a Tier 4 QA Agent specializing in error analysis.\n"
+   f"Analyze the following stderr output from a PowerShell command:\n\n"
+   f"```\n{stderr}\n```\n\n"
+   f"Provide a concise summary of the failure and suggest a fix in approximately 20 words."
+  )
+  model_name = "gemini-2.5-flash-lite"
+  resp = _gemini_client.models.generate_content(
+   model=model_name,
+   contents=prompt,
+   config=types.GenerateContentConfig(
+    temperature=0.0,
+    max_output_tokens=150,
+   )
+  )
+  analysis = resp.text.strip() if resp.text else ""
+  return Result(data=analysis)
+ except Exception as e:
+  return Result(
+   data="",
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"[QA ANALYSIS FAILED] {e}", source="ai_client._run_tier4_analysis_result", original=e)],
+  )
+
+
+def run_tier4_analysis(stderr: str) -> str:
+ return _run_tier4_analysis_result(stderr).data
+
+#endregion: Tier 4 Analysis
+
+#region: Session & Public API
+
+def _run_tier4_patch_callback_result(stderr: str, base_dir: str) -> Result[str]:
+ """Tier 4 QA agent: propose a unified-diff patch for the stderr.
+
+ Returns Result(data=patch) when a valid diff is produced, Result(data="")
+ when no valid diff, Result(data="", errors=[ErrorInfo]) on SDK failure.
+ The legacy caller (run_tier4_patch_callback) returns result.data
+ (preserving the original Optional[str] signature; empty string is treated
+ as "no patch" by callers).
+ """
+ try:
+  file_items = project_manager.get_current_file_items()
+  file_context = ""
+  for item in file_items[:5]:
+   path = item.get("path", "")
+   content = item.get("content", "")[:2000]
+   file_context += f"\n\nFile: {path}\n```\n{content}\n```\n"
+  patch = run_tier4_patch_generation(stderr, file_context)
+  if patch and "---" in patch and "+++" in patch:
+   return Result(data=patch)
+  return Result(data="")
+ except Exception as e:
+  return Result(
+   data="",
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"tier4 patch callback failed: {e}", source="ai_client._run_tier4_patch_callback_result", original=e)],
+  )
+
+
+def _run_tier4_patch_generation_result(error: str, file_context: str) -> Result[str]:
+ """Tier 4 QA agent: generate a unified-diff patch for the given error.
+
+ Returns Result(data=patch) on success, Result(data="", errors=[ErrorInfo])
+ on SDK failure. The legacy caller (run_tier4_patch_generation) returns
+ result.data (preserving the original str signature; failures surface as
+ empty string to keep callers' downstream code working).
+ """
+ if not error or not error.strip():
+  return Result(data="")
+ try:
+  _ensure_gemini_client()
+  if not _gemini_client:
+   return Result(data="")
+  genai = _require_warmed("google.genai")
+  types = genai.types
+  prompt = (
+   f"{mma_prompts.TIER4_PATCH_PROMPT}\n\n"
+   f"Error:\n```\n{error}\n```\n\n"
+   f"File Context:\n```\n{file_context}\n```\n"
+  )
+  model_name = "gemini-2.5-flash-lite"
+  resp = _gemini_client.models.generate_content(
+   model=model_name,
+   contents=prompt,
+   config=types.GenerateContentConfig(
+    temperature=0.0,
+    max_output_tokens=2048,
+   )
+  )
+  patch = resp.text.strip() if resp.text else ""
+  return Result(data=patch)
+ except Exception as e:
+  return Result(
+   data="",
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"[PATCH GENERATION FAILED] {e}", source="ai_client._run_tier4_patch_generation_result", original=e)],
+  )
+
+
+def run_tier4_patch_generation(error: str, file_context: str) -> str:
+ """
+  [C: src/gui_2.py:App.request_patch_from_tier4, tests/test_tier4_patch_generation.py:test_run_tier4_patch_generation_calls_ai, tests/test_tier4_patch_generation.py:test_run_tier4_patch_generation_empty_error, tests/test_tier4_patch_generation.py:test_run_tier4_patch_generation_returns_diff]
+ """
+ return _run_tier4_patch_generation_result(error, file_context).data
+
+def _count_gemini_tokens_for_stats_result(md_content: str) -> Result[int]:
+ """Count tokens via Gemini SDK for the token-stats panel.
+
+ Returns Result(data=token_count) on success, Result(data=0, errors=[ErrorInfo])
+ on SDK or warmup failure. The legacy caller (get_token_stats) treats
+ errors as "token count unavailable" and falls back to character-based
+ estimation (preserving original behavior).
+ """
+ if _gemini_client is None:
+  _ensure_gemini_client()
+ if _gemini_client is None:
+  return Result(data=0)
+ try:
+  resp = _gemini_client.models.count_tokens(model=_model, contents=md_content)
+  return Result(data=cast(int, resp.total_tokens))
+ except Exception as e:
+  return Result(
+   data=0,
+   errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=f"failed to count gemini tokens for stats: {e}", source="ai_client._count_gemini_tokens_for_stats_result", original=e)],
+  )
+
+
+def get_token_stats(md_content: str) -> Metadata:
+ """
+  [C: src/app_controller.py:AppController._refresh_api_metrics]
+ """
+ global _provider, _gemini_client, _model, _CHARS_PER_TOKEN
+ total_tokens = 0
+ p = str(_provider).lower().strip()
+ if p in ("gemini", "gemini_cli"):
+  total_tokens = _count_gemini_tokens_for_stats_result(md_content).data
+ if total_tokens == 0:
+  total_tokens = max(1, int(len(md_content) / _CHARS_PER_TOKEN))
+ limit = _GEMINI_MAX_INPUT_TOKENS if p in ["gemini", "gemini_cli"] else _ANTHROPIC_MAX_PROMPT_TOKENS
+ if p == "deepseek":
+  limit = 64000
+ pct = (total_tokens / limit * 100) if limit > 0 else 0
+ stats = {
+  "total_tokens": total_tokens,
+  "current": total_tokens,
+  "limit": limit,
+  "percentage": pct
+ }
+ return _add_bleed_derived(stats, sys_tok=total_tokens)
+
+def send(
+ md_content: str,
+ user_message: str,
+ base_dir: str = ".",
+ file_items: list[Metadata] | None = None,
+ discussion_history: str = "",
+ stream: bool = False,
+ pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None,
+ qa_callback: Optional[Callable[[str], str]] = None,
+ enable_tools: bool = True,
+ stream_callback: Optional[Callable[[str], None]] = None,
+ patch_callback: Optional[Callable[[str, str], Result[str]]] = None,
+ rag_engine: Optional[Any] = None,
+) -> Result[str]:
+ """
+  Sends a prompt to the currently configured AI provider, returning a comprehensive Result object.
+
+  Functional Purpose:
+   This is the primary public entry point for AI communication. It integrates retrieval-augmented
+   generation (RAG) by searching the vector index and injecting relevant context chunks into the user
+   message. It logs the outgoing request to the communications logger, acquires a global thread-safety
+   lock (_send_lock), and routes the request to the appropriate vendor-specific handler based on the
+   active provider configuration. All exceptions are caught and returned gracefully as ErrorInfo objects.
+
+  Parameters & Inputs:
+   md_content (str): System prompt template or markdown prompt structure.
+   user_message (str): The primary user instruction.
+   base_dir (str): Base workspace directory path (defaults to ".").
+   file_items (list[Metadata] | None): Optional list of active context files.
+   discussion_history (str): Contextual discussion history lines.
+   stream (bool): Whether to stream the response chunks.
+   pre_tool_callback (Optional[Callable]): Hook called before executing tool calls.
+   qa_callback (Optional[Callable]): Hook for Tier 4 quality/validation checks.
+   enable_tools (bool): Controls whether LLM tool usage is enabled.
+   stream_callback (Optional[Callable]): Hook to stream response chunks to.
+   patch_callback (Optional[Callable]): Custom callback for interactive patch validation.
+   rag_engine (Optional[Any]): RAG search engine instance to fetch vector context.
+
+  Returns:
+   Result[str]: Container holding the successful response string or error details.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send() and direct public callers verifying error structures.
+   Calls: performance_monitor, rag_engine.search, _append_comms, _send_gemini,
+          _send_gemini_cli, _send_anthropic, _send_deepseek, _send_minimax,
+          _send_qwen, _send_llama, _send_grok, _send_llama_native
+
+  SSDL:
+   `[Q:active_provider] -> [I:SetupTierTag] -> [I:DispatchProvider] -> [T:Result]`
+
+  Thread Boundaries:
+   Acquires the global _send_lock to synchronize provider calls. Safely called from any worker
+   thread executing background tasks, preventing concurrent thread collisions on shared provider SDK states.
+
+  [C: tests/test_ai_client_result.py:test_send_public_api_returns_result, tests/test_ai_client_result.py:test_send_preserves_errors, tests/test_deprecation_warnings.py:test_send_does_not_emit_deprecation]
+ """
+ monitor = performance_monitor.get_monitor()
+ if monitor.enabled: monitor.start_component("ai_client.send")
+
+ if rag_engine and getattr(rag_engine.config, "enabled", False) and "## Retrieved Context" not in user_message:
+  chunks = rag_engine.search(user_message)
+  if chunks:
+   context_block = "## Retrieved Context\n\n"
+   for i, chunk in enumerate(chunks):
+    path = chunk.path if chunk.path else "unknown"
+    doc = chunk.document
+    context_block += f"### Chunk {i+1} (Source: {path})\n{doc}\n\n"
+   user_message = context_block + user_message
+
+ _append_comms("OUT", "request", {"message": user_message, "system": _get_combined_system_prompt(_active_tool_preset, _active_bias_profile)})
+ with _send_lock:
+  p = str(_provider).lower().strip()
+  try:
+   if p == "gemini":
+    res = _send_gemini(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     pre_tool_callback, qa_callback, enable_tools, stream_callback, patch_callback
+    )
+   elif p == "gemini_cli":
+    res = _send_gemini_cli(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "anthropic":
+    res = _send_anthropic(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     pre_tool_callback, qa_callback, stream_callback=stream_callback, patch_callback=patch_callback
+    )
+   elif p == "deepseek":
+    res = _send_deepseek(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "minimax":
+    res = _send_minimax(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "qwen":
+    res = _send_qwen(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "llama":
+    res = _send_llama(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "grok":
+    res = _send_grok(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   elif p == "llama_native":
+    res = _send_llama_native(
+     md_content, user_message, base_dir, file_items, discussion_history,
+     stream, pre_tool_callback, qa_callback, stream_callback, patch_callback
+    )
+   else:
+    res = Result(data="", errors=[ErrorInfo(kind=ErrorKind.CONFIG, message=f"unknown provider: {_provider}", source="ai_client.send")])
+  except Exception as exc:
+   res = Result(data="", errors=[ErrorInfo(kind=ErrorKind.INTERNAL, message=str(exc), source="ai_client.send", original=exc)])
+ if monitor.enabled: monitor.end_component("ai_client.send")
+ return res
+
+def _add_bleed_derived(d: Metadata, sys_tok: int = 0, tool_tok: int = 0) -> Metadata:
+ """
+  [C: tests/test_token_viz.py:test_add_bleed_derived_aliases, tests/test_token_viz.py:test_add_bleed_derived_breakdown, tests/test_token_viz.py:test_add_bleed_derived_headroom, tests/test_token_viz.py:test_add_bleed_derived_headroom_clamped_to_zero, tests/test_token_viz.py:test_add_bleed_derived_history_clamped_to_zero, tests/test_token_viz.py:test_add_bleed_derived_would_trim_false, tests/test_token_viz.py:test_add_bleed_derived_would_trim_true, tests/test_token_viz.py:test_would_trim_boundary_exact, tests/test_token_viz.py:test_would_trim_just_above_threshold, tests/test_token_viz.py:test_would_trim_just_below_threshold]
+ """
+ cur = d.get("current", 0)
+ lim = d.get("limit", 0)
+ d["estimated_prompt_tokens"] = cur
+ d["max_prompt_tokens"] = lim
+ d["utilization_pct"] = d.get("percentage", 0.0)
+ d["headroom"] = max(0, lim - cur)
+ d["would_trim"] = cur >= lim
+ d["sys_tokens"] = sys_tok
+ d["tool_tokens"] = tool_tok
+ d["history_tokens"] = max(0, cur - sys_tok - tool_tok)
+ return d
+
+# Check for tool preset in environment variable (headless mode)
+if os.environ.get("SLOP_TOOL_PRESET"):
+ _set_tool_preset_result(os.environ["SLOP_TOOL_PRESET"])
+
+#endregion: Session & Public API
+
+#region: Subagent Summarization
+
+def run_subagent_summarization(file_path: str, content: str, is_code: bool, outline: str) -> str:
+ """
+  [C: src/summarize.py:summarise_file, tests/test_subagent_summarization.py:test_run_subagent_summarization_anthropic, tests/test_subagent_summarization.py:test_run_subagent_summarization_gemini]
+ """
+ requests = _require_warmed("requests")
+ genai = _require_warmed("google.genai")
+ types = genai.types
+ prompt_tmpl = mma_prompts.TIER4_SUMMARIZE_CODE_PROMPT if is_code else mma_prompts.TIER4_SUMMARIZE_TEXT_PROMPT
+ prompt = prompt_tmpl.format(file_path=file_path, outline=outline, content=content)
+ if _provider == "gemini":
+  _ensure_gemini_client()
+  if _gemini_client:
+   resp = _gemini_client.models.generate_content(
+    model=_model,
+    contents=prompt,
+    config=types.GenerateContentConfig(
+     temperature=0.0,
+     max_output_tokens=1024,
+    )
+   )
+   return resp.text or ""
+ elif _provider == "anthropic":
+  _ensure_anthropic_client()
+  if _anthropic_client:
+   resp = _anthropic_client.messages.create(
+    model=_model,
+    max_tokens=1024,
+    messages=[{"role": "user", "content": prompt}]
+   )
+   return "".join([b.text for b in resp.content if hasattr(b, "text") and b.text])
+ elif _provider == "deepseek":
+  creds = _load_credentials()
+  api_key = creds.get("deepseek", {}).get("api_key")
+  if not api_key: return "ERROR: DeepSeek API key missing"
+  headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+  payload = {
+   "model": _model,
+   "messages": [{"role": "user", "content": prompt}],
+   "temperature": 0.0,
+  }
+  try:
+   r = requests.post("https://api.deepseek.com/chat/completions", headers=headers, json=payload, timeout=60)
+   r.raise_for_status()
+   return r.json()["choices"][0]["message"]["content"]
+  except Exception as e:
+   return f"ERROR: DeepSeek summarization failed: {e}"
+ elif _provider == "gemini_cli":
+  # Using the adapter for a one-off call
+  adapter = GeminiCliAdapter(binary_path="gemini")
+  resp_data = adapter.send(prompt, model=_model)
+  return resp_data.get("text", "")
+ return "ERROR: Unsupported provider for sub-agent summarization"
+
+def run_discussion_compression(discussion_text: str) -> str:
+ genai = _require_warmed("google.genai")
+ types = genai.types
+ requests = _require_warmed("requests")
+ # Robustly identify the provider string (handles case and whitespace)
+ p = str(get_provider()).lower().strip()
+ prompt = f"The following is a long conversation history.\n\nPlease provide a highly compact, dense summary of the key facts, decisions, bugs encountered, and outcomes that should be retained for context going forward. Categorize into User intent, Tool outputs, and AI reasoning. Omit pleasantries and redundant thoughts.\n\n[HISTORY]\n{discussion_text}"
+ if p == "gemini":
+  _ensure_gemini_client()
+  if _gemini_client:
+   resp = _gemini_client.models.generate_content(
+    model=_model,
+    contents=prompt,
+    config=types.GenerateContentConfig(temperature=0.0, max_output_tokens=2048)
+   )
+   return resp.text or ""
+ elif p == "anthropic":
+  _ensure_anthropic_client()
+  if _anthropic_client:
+   resp = _anthropic_client.messages.create(
+    model=_model, max_tokens=2048,
+    messages=[{"role": "user", "content": prompt}]
+   )
+   return "".join([b.text for b in resp.content if hasattr(b, "text") and b.text])
+ elif p == "deepseek":
+  creds = _load_credentials()
+  api_key = creds.get("deepseek", {}).get("api_key")
+  if not api_key: return "ERROR: DeepSeek API key missing"
+  try:
+   r = requests.post("https://api.deepseek.com/chat/completions", headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}, json={"model": _model, "messages": [{"role": "user", "content": prompt}], "temperature": 0.0}, timeout=60)
+   r.raise_for_status()
+   return r.json()["choices"][0]["message"]["content"]
+  except Exception as e:
+   return f"ERROR: DeepSeek compression failed: {e}"
+ elif p == "minimax":
+  _ensure_minimax_client()
+  if _minimax_client:
+   resp = _minimax_client.chat.completions.create(
+    model=_model,
+    messages=[{"role": "user", "content": prompt}],
+    temperature=0.0,
+    max_tokens=2048
+   )
+   return resp.choices[0].message.content or ""
+ elif p == "gemini_cli":
+  adapter = GeminiCliAdapter(binary_path="gemini")
+  resp_data = adapter.send(prompt, model=_model)
+  return resp_data.get("text", "")
+ return f"ERROR: Unsupported provider for discussion compression: '{p}'"
+
+#endregion: Subagent Summarization
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_personas.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_personas.py
new file mode 100644
index 00000000..c50da68c
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_personas.py
@@ -0,0 +1,171 @@
+"""Personas module: Persona dataclass + PersonaManager CRUD.
+
+Per module_taxonomy_refactor_20260627 Phase 3.4, the Persona dataclass
+moved from src/models.py into this module. PersonaManager (the ops layer
+that loads/saves Persona instances to TOML) was already here.
+"""
+from __future__ import annotations
+
+import tomllib
+import tomli_w
+
+from dataclasses import dataclass, field
+from pathlib    import Path
+from typing     import Dict, Any, Optional
+
+from src        import paths
+from src.type_aliases import Metadata
+
+
+@dataclass
+class Persona:
+ name: str
+ preferred_models: list[Metadata] = field(default_factory=list)
+ system_prompt: str = ''
+ tool_preset: Optional[str] = None
+ bias_profile: Optional[str] = None
+ context_preset: Optional[str] = None
+ aggregation_strategy: Optional[str] = None
+
+ @property
+ def provider(self) -> str:
+  if not self.preferred_models: return ""
+  return self.preferred_models[0].get("provider") or ""
+
+ @property
+ def model(self) -> str:
+  if not self.preferred_models: return ""
+  return self.preferred_models[0].get("model") or ""
+
+ @property
+ def temperature(self) -> float:
+  if not self.preferred_models: return 0.0
+  return float(self.preferred_models[0].get("temperature") or 0.0)
+
+ @property
+ def top_p(self) -> float:
+  if not self.preferred_models: return 1.0
+  return float(self.preferred_models[0].get("top_p") or 1.0)
+
+ @property
+ def max_output_tokens(self) -> int:
+  if not self.preferred_models: return 0
+  return int(self.preferred_models[0].get("max_output_tokens") or 0)
+
+ def to_dict(self) -> Metadata:
+  res = {"system_prompt": self.system_prompt}
+  if self.preferred_models:
+   processed = []
+   for m in self.preferred_models:
+    if isinstance(m, str):
+     processed.append({"model": m})
+    else:
+     processed.append(m)
+   res["preferred_models"] = processed
+  if self.tool_preset          is not None: res["tool_preset"] = self.tool_preset
+  if self.bias_profile         is not None: res["bias_profile"] = self.bias_profile
+  if self.context_preset       is not None: res["context_preset"] = self.context_preset
+  if self.aggregation_strategy is not None: res["aggregation_strategy"] = self.aggregation_strategy
+  return res
+
+ @classmethod
+ def from_dict(cls, name: str, data: Metadata) -> "Persona":
+  raw_models = data.get("preferred_models", [])
+  parsed_models = []
+  for m in raw_models:
+   if isinstance(m, str):
+    parsed_models.append({"model": m})
+   else:
+    parsed_models.append(m)
+  legacy = {}
+  for k in ["provider", "model", "temperature", "top_p", "max_output_tokens"]:
+   if data.get(k) is not None:
+    legacy[k] = data[k]
+  if legacy:
+   if not parsed_models:
+    parsed_models.append(legacy)
+   else:
+    for k, v in legacy.items():
+     if k not in parsed_models[0] or parsed_models[0][k] is None:
+      parsed_models[0][k] = v
+  return cls(
+   name                 = name,
+   preferred_models     = parsed_models,
+   system_prompt        = data.get("system_prompt", ""),
+   tool_preset          = data.get("tool_preset"),
+   bias_profile         = data.get("bias_profile"),
+   context_preset       = data.get("context_preset"),
+   aggregation_strategy = data.get("aggregation_strategy"),
+  )
+
+
+class PersonaManager:
+ """Manages Persona profiles across global and project-specific files."""
+
+ def __init__(self, project_root: Optional[Path] = None):
+  self.project_root = project_root
+
+ def _get_path(self, scope: str) -> Path:
+  if scope == "global":
+   return paths.get_global_personas_path()
+  elif scope == "project":
+   if not self.project_root:
+    raise ValueError("Project root is not set, cannot resolve project scope.")
+   return paths.get_project_personas_path(self.project_root)
+  else:
+   raise ValueError("Invalid scope, must be 'global' or 'project'")
+
+ def load_all(self) -> Dict[str, Persona]:
+  personas = {}
+  global_path = paths.get_global_personas_path()
+  global_data = self._load_file(global_path)
+  for name, data in global_data.get("personas", {}).items():
+   personas[name] = Persona.from_dict(name, data)
+  if self.project_root:
+   project_path = paths.get_project_personas_path(self.project_root)
+   project_data = self._load_file(project_path)
+   for name, data in project_data.get("personas", {}).items():
+    personas[name] = Persona.from_dict(name, data)
+  return personas
+
+ def save_persona(self, persona: Persona, scope: str = "project") -> None:
+  path = self._get_path(scope)
+  data = self._load_file(path)
+  if "personas" not in data:
+   data["personas"] = {}
+  data["personas"][persona.name] = persona.to_dict()
+  self._save_file(path, data)
+
+ def get_persona_scope(self, name: str) -> str:
+  """Returns the scope ('global' or 'project') of a persona by name."""
+  if self.project_root:
+   project_path = paths.get_project_personas_path(self.project_root)
+   project_data = self._load_file(project_path)
+   if name in project_data.get("personas", {}):
+    return "project"
+  global_path = paths.get_global_personas_path()
+  global_data = self._load_file(global_path)
+  if name in global_data.get("personas", {}):
+   return "global"
+  return "project"
+
+ def delete_persona(self, name: str, scope: str = "project") -> None:
+  path = self._get_path(scope)
+  data = self._load_file(path)
+  if "personas" in data and name in data["personas"]:
+   del data["personas"][name]
+   self._save_file(path, data)
+
+ def _load_file(self, path: Path) -> Dict[str, Any]:
+  if not path.exists():
+   return {}
+  try:
+   with open(path, "rb") as f:
+    return tomllib.load(f)
+  except Exception:
+   return {}
+
+ def _save_file(self, path: Path, data: Dict[str, Any]) -> None:
+  path.parent.mkdir(parents=True, exist_ok=True)
+  with open(path, "wb") as f:
+   tomli_w.dump(data, f)
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_spec.md b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_spec.md
new file mode 100644
index 00000000..de4a344f
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_spec.md
@@ -0,0 +1,224 @@
+# Track Specification: module_taxonomy_refactor_20260627
+
+## Overview
+
+The user-reported `models.py` is a "dumping ground" (1044 lines, 36 classes, 5+ unrelated domains). This track cleans it up PLUS addresses 5 ImGui LEAKS that violate the "ImGui belongs in `gui_2.py`" boundary PLUS unifies 2 vendor files with `ai_client.py`.
+
+Per the user's principle: **unify unless there's a good reason (import load times, definition pollution)**. No sub-directories. Prefix naming convention.
+
+## Current State Audit (master `5380b715`, measured 2026-06-27)
+
+| Metric | Value |
+|---|---:|
+| `src/` file count | 65 |
+| `src/models.py` line count | 1044 |
+| `src/models.py` class/function count | 36 |
+| `src/models.py` regions | 13 (Constants, Config Utilities, History Utilities, Pydantic Models, MMA Core, State & Config, Tool Models, UI/Editor, Persona, Workspace, MCP Config, Project Context, ...more) |
+| ImGui-using files outside `gui_2.py` | 5 (`bg_shader.py`, `shaders.py`, `command_palette.py`, `diff_viewer.py`, `patch_modal.py`) |
+| Vendor files separate from `ai_client.py` | 2 (`vendor_capabilities.py`, `vendor_state.py`) |
+| `AGENT_TOOL_NAMES` consumers | 8 (3 in `app_controller.py`, 5 in `tests/test_arch_boundary_phase2.py`) |
+| `mcp_tool_specs.tool_names()` test | EXISTS (asserts `tool_names() Γèå AGENT_TOOL_NAMES` ΓÇö proves it's redundant) |
+
+## Goals
+
+| ID | Goal | Acceptance |
+|---|---|---|
+| G1 | **MERGE 5 ImGui LEAKS into `gui_2.py`** | `git grep -l "imgui_bundle\|from imgui\\." -- 'src/*.py'` returns ONLY `gui_2.py` + `imgui_scopes.py` |
+| G2 | **MERGE 2 vendor files into `ai_client.py`** | `ls src/{vendor_capabilities,vendor_state}.py` returns not-found; `python -c "from src.ai_client import ..."` imports the merged symbols |
+| G3 | **SPLIT `models.py`** into `mma.py` + `project.py` + `project_files.py` | `ls src/mma.py src/project.py src/project_files.py` all exist; `python -c "from src.mma import ThinkingSegment, Ticket, Track, WorkerContext, TrackState"` works |
+| G4 | **MERGE** 6+ other `models.py` classes into existing sub-system files | `Persona` in `personas.py`; `Tool`/`ToolPreset` in `tool_presets.py`; `BiasProfile` in `tool_bias.py`; `TextEditorConfig`/`ExternalEditorConfig` in `external_editor.py`; `MCPServerConfig`+etc in `mcp_client.py`; `WorkspaceProfile` in `workspace_manager.py` |
+| G5 | **DELETE `AGENT_TOOL_NAMES`** (redundant with `mcp_tool_specs.tool_names()`) | `git grep "AGENT_TOOL_NAMES" -- 'src/*.py'` returns 0 hits; 8 consumer sites updated to use `list(mcp_tool_specs.tool_names())` |
+| G6 | **`src/models.py` reduced to Γëñ30 lines** (or eliminated) | `wc -l src/models.py` returns Γëñ30 |
+| G7 | All 7 audit gates pass `--strict` | unchanged from baseline |
+| G8 | All batched test tiers pass (10/11 baseline + RAG flake) | unchanged from baseline |
+
+## Non-Goals
+
+- Renaming existing files for prefix consistency (`multi_agent_conductor.py` → `mma_conductor.py`, etc.) — deferred to follow-up; current names are clear enough
+- Refactoring `aggregate.py` (513 lines), `app_controller.py` (4869 lines), `gui_2.py` (7773 lines) ΓÇö out of scope; these have natural boundaries; the user doesn't want more splitting without good reason
+- Modifications to `mcp_client.py` other than merging the config dataclasses ΓÇö the merge itself is the change
+- New `src/<thing>.py` files (per AGENTS.md hard rule) ΓÇö the 3 new files (`mma.py`, `project.py`, `project_files.py`) are justified by the `models.py` split (definition pollution)
+
+## Functional Requirements
+
+### FR1: MERGE ImGui LEAKS into `gui_2.py`
+
+For each of these 5 files, move the content into `gui_2.py` in a clearly-marked section, then `git rm` the original:
+
+```python
+# In gui_2.py, add at the appropriate location:
+
+#region: Bg Shader (moved from src/bg_shader.py)
+# ... (content of src/bg_shader.py)
+#endregion
+
+#region: Shaders (moved from src/shaders.py)
+# ... (content of src/shaders.py)
+#endregion
+
+#region: Command Palette (moved from src/command_palette.py)
+# ... (content of src/command_palette.py)
+#endregion
+
+#region: Diff Viewer (moved from src/diff_viewer.py)
+# ... (content of src/diff_viewer.py)
+#endregion
+
+#region: Patch Modal (moved from src/patch_modal.py)
+# ... (content of src/patch_modal.py)
+#endregion
+```
+
+**Imports to update across the codebase:**
+- `from src.bg_shader import X` → `from src.gui_2 import X`
+- `from src.shaders import X` → `from src.gui_2 import X`
+- (etc. for all 5 files)
+
+### FR2: MERGE vendor files into `ai_client.py`
+
+```python
+# In ai_client.py, add at the appropriate location:
+
+#region: Vendor Capabilities (moved from src/vendor_capabilities.py)
+# ... (content of src/vendor_capabilities.py)
+#endregion
+
+#region: Vendor State (moved from src/vendor_state.py)
+# ... (content of src/vendor_state.py)
+#endregion
+```
+
+**Imports to update:**
+- `from src.vendor_capabilities import X` → `from src.ai_client import X`
+- `from src.vendor_state import X` → `from src.ai_client import X`
+
+### FR3: SPLIT `models.py`
+
+**Phase 1: Create `src/mma.py`** with the MMA Core + TrackState:
+- ThinkingSegment
+- Ticket
+- Track
+- WorkerContext
+- TrackState
+- Top-level docstring explaining MMA scope
+
+**Phase 2: Create `src/project.py`** with the project config:
+- ProjectContext + 5 sub-dataclasses (ProjectMeta, ProjectOutput, ProjectFiles, ProjectScreenshots, ProjectDiscussion)
+- Config I/O helpers: `_clean_nones`, `load_config_from_disk`, `save_config_to_disk`, `parse_history_entries`
+- Top-level docstring explaining project config scope
+
+**Phase 3: Create `src/project_files.py`** with the file-related dataclasses:
+- FileItem
+- ContextPreset
+- ContextFileEntry
+- NamedViewPreset
+- Preset
+- Top-level docstring explaining file-related project state scope
+
+### FR4: MERGE other `models.py` classes into existing sub-system files
+
+| Class from `models.py` | Destination (existing file) | New section name |
+|---|---|---|
+| `Persona` | `src/personas.py` | "Persona Dataclass" |
+| `Tool`, `ToolPreset` | `src/tool_presets.py` | "Tool + ToolPreset Dataclasses" |
+| `BiasProfile` | `src/tool_bias.py` | "BiasProfile Dataclass" |
+| `TextEditorConfig`, `ExternalEditorConfig` | `src/external_editor.py` | "Editor Config Dataclasses" |
+| `MCPServerConfig`, `MCPConfiguration`, `VectorStoreConfig`, `RAGConfig`, `load_mcp_config` | `src/mcp_client.py` | "MCP Config Dataclasses" |
+| `WorkspaceProfile` | `src/workspace_manager.py` | "WorkspaceProfile Dataclass" |
+
+### FR5: DELETE `AGENT_TOOL_NAMES` (redundant)
+
+```python
+# 8 consumer site updates:
+# Before:
+from src.models import AGENT_TOOL_NAMES
+for tool in AGENT_TOOL_NAMES:
+    ...
+
+# After:
+from src import mcp_tool_specs
+for tool in mcp_tool_specs.tool_names():
+    ...
+```
+
+**Consumer sites (8):**
+- `src/app_controller.py:2110, 2972, 3273` (3 sites)
+- `tests/test_arch_boundary_phase2.py:23, 29, 31, 32, 33` (5 sites)
+
+**Test simplification:** `test_tool_names_subset_of_models_agent_tool_names` becomes either:
+- DELETE (it's a tautology once `AGENT_TOOL_NAMES` is derived from `tool_names()`)
+- OR convert to a positive assertion: `assert mcp_tool_specs.tool_names() == {expected canonical tools}`
+
+### FR6: REDUCE `src/models.py` to ~30 lines (or eliminate)
+
+After all moves, `src/models.py` contains:
+- `_create_generate_request`, `_create_confirm_request`, `__getattr__` (Pydantic lazy proxies for the API)
+- OR these move to `src/api_hooks.py` (if API-specific)
+- Top-level docstring
+
+If `models.py` becomes essentially empty after these moves, **delete the file entirely** (it's not a "system" file; `models.py` is just a temporary holder).
+
+## Non-Functional Requirements
+
+- NFR1: 1-space indentation (per `conductor/workflow.md`)
+- NFR2: CRLF line endings on Windows
+- NFR3: No comments in source code (per AGENTS.md "No comments in source code")
+- NFR4: Per-task atomic commits with git notes
+- NFR5: No new pip dependencies
+- NFR6: `Result[T]` returns for fallible fns (per `error_handling.md`)
+- NFR7: No new `src/<thing>.py` files UNLESS justified by definition pollution (per AGENTS.md hard rule)
+
+## Architecture Reference
+
+- `AGENTS.md` ΓÇö "File Size and Naming Convention" HARD RULE
+- `conductor/code_styleguides/data_oriented_design.md` ΓÇö "Prefer Fewer Types" principle
+- `conductor/code_styleguides/error_handling.md` ΓÇö the `Result[T]` convention
+- `conductor/code_styleguides/type_aliases.md` ΓÇö the 10 TypeAliases convention
+- `conductor/tracks/cruft_elimination_20260627/SPEC_CORRECTION_phase_2.md` ΓÇö the related spec correction (the original Phase 2 spec was wrong to put ProjectContext in `models.py`; this track fixes that)
+- `docs/reports/FOLLOWUP_module_taxonomy_20260627.md` ΓÇö the previous followup report (this track supersedes it with concrete execution)
+
+## Out of Scope
+
+- Renaming existing files for prefix consistency (`multi_agent_conductor.py` → `mma_conductor.py`, etc.) — deferred to follow-up
+- Refactoring `aggregate.py` (513 lines), `app_controller.py` (4869 lines), `gui_2.py` (7773 lines) ΓÇö out of scope; these have natural boundaries
+- Modifications to `mcp_client.py` other than merging the config dataclasses
+- New `src/<thing>.py` files beyond the 3 justified ones (`mma.py`, `project.py`, `project_files.py`)
+- The RAG test pre-existing flake (per `docs/reports/SSDL_CAMPAIGN_ABORTED_20260624.md` "Out of Scope")
+- Any Tier 2 spec rewrites (per the user's earlier "don't fuck with commits" directive)
+
+## Verification Criteria (Definition of Done)
+
+| # | Criterion | Verification |
+|---|---|---|
+| VC1 | ImGui imports limited to `gui_2.py` + `imgui_scopes.py` | `git grep -l "imgui_bundle\|from imgui\\." -- 'src/*.py'` returns 2 files |
+| VC2 | `src/bg_shader.py`, `src/shaders.py`, `src/command_palette.py`, `src/diff_viewer.py` deleted (4 LEAK files per the data/view/ops split) | `ls src/{bg_shader,shaders,command_palette,diff_viewer}.py` returns not-found. `src/patch_modal.py` is NOT a LEAK ΓÇö it's the data module (DiffHunk/DiffFile/PendingPatch) per the data/view/ops split rule. The diff_viewer classes (DiffHunk/DiffFile) were moved INTO it during the cruft_elimination track's split; deleting it would violate the data module's integrity. See `conductor/tracks/post_module_taxonomy_de_cruft_20260627/spec.md` Phase 1 for the formal correction. |
+| VC3 | `src/vendor_capabilities.py`, `src/vendor_state.py` deleted | `ls src/{vendor_capabilities,vendor_state}.py` returns not-found |
+| VC4 | Vendor symbols importable from `src.ai_client` | `python -c "from src.ai_client import PROVIDER_CAPABILITIES, get_vendor_state"` works |
+| VC5 | `src/mma.py` exists with MMA Core + TrackState | `python -c "from src.mma import ThinkingSegment, Ticket, Track, WorkerContext, TrackState"` works |
+| VC6 | `src/project.py` exists with ProjectContext + sub + config I/O | `python -c "from src.project import ProjectContext, ProjectMeta, ProjectOutput, ProjectFiles, ProjectScreenshots, ProjectDiscussion, _clean_nones, load_config_from_disk, save_config_to_disk, parse_history_entries"` works |
+| VC7 | `src/project_files.py` exists with file-related dataclasses | `python -c "from src.project_files import FileItem, ContextPreset, ContextFileEntry, NamedViewPreset, Preset"` works |
+| VC8 | Persona/Tool/Editor/MCP/Workspace dataclasses in their proper sub-system files | `python -c "from src.personas import Persona; from src.tool_presets import Tool, ToolPreset; from src.tool_bias import BiasProfile; from src.external_editor import TextEditorConfig, ExternalEditorConfig; from src.mcp_client import MCPServerConfig, MCPConfiguration, VectorStoreConfig, RAGConfig, load_mcp_config; from src.workspace_manager import WorkspaceProfile"` works |
+| VC9 | `AGENT_TOOL_NAMES` deleted; all 8 consumer sites use `mcp_tool_specs.tool_names()` | `git grep "AGENT_TOOL_NAMES" -- 'src/*.py' 'tests/*.py'` returns 0 hits |
+| VC10 | `src/models.py` reduced from 1044 to ~135 lines (Pydantic proxies + DEFAULT_TOOL_CATEGORIES + lazy `__getattr__` for backward compat) | `wc -l src/models.py` returns Γëñ200; the 30-line target was aspirational. The lazy `__getattr__` is necessary for backward compat with 30+ legacy `from src.models import X` call sites until the `post_module_taxonomy_de_cruft_20260627` follow-up track migrates them to direct imports from the subsystem files (`src.mma`, `src.project`, `src/project_files`, `src/tool_presets`, `src/tool_bias`, `src/external_editor`, `src/personas`, `src/workspace_manager`, `src/mcp_client`). The full migration is FR7 of the post_module_taxonomy_de_cruft_20260627 track. The legacy `Metadata = TrackMetadata` alias is preserved for `from src.models import Metadata` to resolve to the TrackMetadata dataclass (used by `tests/test_track_state_schema.py`). |
+| VC11 | All 7 audit gates pass `--strict` | unchanged from baseline |
+| VC12 | 10/11 batched test tiers pass (RAG flake acceptable) | unchanged from baseline |
+
+## Risks
+
+| # | Risk | Likelihood | Mitigation |
+|---|---|---|---|
+| R1 | ImGui LEAKS move breaks existing tests (e.g., `command_palette` is referenced in commands.py) | low | Run full affected test set after each move; revert + fix on regression |
+| R2 | Vendor merge into `ai_client.py` creates circular imports (PROVIDERS lazy proxy is the workaround) | medium | The lazy import pattern (`__getattr__`) handles this; verify by running the full test suite after merge |
+| R3 | `models.py` split breaks 136 import sites | high | Per-file move with regression-guard tests after each; update imports systematically |
+| R4 | The 6+ "merge into existing sub-system files" moves break those files' existing tests | medium | Run the affected test file after each merge |
+| R5 | `AGENT_TOOL_NAMES` deletion breaks `test_arch_boundary_phase2.py` | low | Update the test to use `mcp_tool_specs.tool_names()`; cross-check that the test's expected tool names are in the registry |
+| R6 | The `ProjectContext` Phase 2 commit (in `cruft_elimination_20260627`) put `ProjectContext` in `models.py`; the new track moves it to `project.py` ΓÇö needs to coordinate with the cruft track | high | The cruft track should NOT merge its `models.py` `ProjectContext` commit; this refactor track handles the move |
+| R7 | The `_create_generate_request` etc. Pydantic proxies in `models.py` are used by `api_hooks.py`; if we move them to `api_hooks.py` we create a different topology | low | Audit the consumers; if they're all in `api_hooks.py`, move them; if not, keep in `models.py` or move to a new `api_models.py` |
+
+## See also
+
+- `docs/reports/FOLLOWUP_module_taxonomy_20260627.md` ΓÇö the previous followup report (this spec supersedes it)
+- `conductor/tracks/cruft_elimination_20260627/SPEC_CORRECTION_phase_2.md` ΓÇö the related spec correction
+- `conductor/tracks/cruft_elimination_20260627/spec.md` ΓÇö the parent spec (which is currently in flux)
+- `AGENTS.md` ΓÇö "File Size and Naming Convention" HARD RULE
+- `conductor/code_styleguides/data_oriented_design.md` ΓÇö "Prefer Fewer Types" principle
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_bias.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_bias.py
new file mode 100644
index 00000000..f23ae77c
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_bias.py
@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing      import Any, Dict, List, Optional
+
+from src.tool_presets   import Tool, ToolPreset
+from src.type_aliases   import Metadata
+
+
+@dataclass
+class BiasProfile:
+ name:                 str
+ tool_weights:         Dict[str, int]   = field(default_factory=dict)
+ category_multipliers: Dict[str, float] = field(default_factory=dict)
+
+ def to_dict(self) -> Metadata:
+  return {
+   "name":                 self.name,
+   "tool_weights":         self.tool_weights,
+   "category_multipliers": self.category_multipliers,
+  }
+
+ @classmethod
+ def from_dict(cls, data: Metadata) -> "BiasProfile":
+  return cls(
+   name                 = data["name"],
+   tool_weights         = data.get("tool_weights", {}),
+   category_multipliers = data.get("category_multipliers", {}),
+  )
+
+
+class ToolBiasEngine:
+ def apply_semantic_nudges(self, tool_definitions: List[Dict[str, Any]], preset: ToolPreset) -> List[Dict[str, Any]]:
+  """
+  [C: tests/test_tool_bias.py:test_apply_semantic_nudges, tests/test_tool_bias.py:test_parameter_bias_nudging]
+  """
+  weight_map = {
+   5: "[HIGH PRIORITY] ",
+   4: "[PREFERRED] ",
+   2: "[NOT RECOMMENDED] ",
+   1: "[LOW PRIORITY] "
+  }
+  
+  preset_tools: Dict[str, Tool] = {}
+  for cat_tools in preset.categories.values():
+   for t in cat_tools:
+    if isinstance(t, Tool):
+     preset_tools[t.name] = t
+  
+  for defn in tool_definitions:
+   name = defn.get("name")
+   if name in preset_tools:
+    tool = preset_tools[name]
+    prefix = weight_map.get(tool.weight, "")
+    if prefix:
+     defn["description"] = prefix + defn.get("description", "")
+    
+    if tool.parameter_bias:
+     params = defn.get("parameters") or defn.get("input_schema")
+     if params and "properties" in params:
+      props = params["properties"]
+      for p_name, bias in tool.parameter_bias.items():
+       if p_name in props:
+        p_desc = props[p_name].get("description", "")
+        props[p_name]["description"] = f"[{bias}] {p_desc}".strip()
+  
+  return tool_definitions
+
+ def generate_tooling_strategy(self, preset: ToolPreset, global_bias: BiasProfile) -> str:
+  """
+  [C: tests/test_tool_bias.py:test_generate_tooling_strategy]
+  """
+  lines = ["### Tooling Strategy"]
+  
+  preferred = []
+  low_priority = []
+  for cat_tools in preset.categories.values():
+   for t in cat_tools:
+    if not isinstance(t, Tool): continue
+    if   t.weight >= 5: preferred.append(f"{t.name} [HIGH PRIORITY]")
+    elif t.weight == 4: preferred.append(f"{t.name} [PREFERRED]")
+    elif t.weight == 2: low_priority.append(f"{t.name} [NOT RECOMMENDED]")
+    elif t.weight <= 1: low_priority.append(f"{t.name} [LOW PRIORITY]")
+  
+  if preferred:    lines.append(f"Preferred tools: {', '.join(preferred)}.")
+  if low_priority: lines.append(f"Low-priority tools: {', '.join(low_priority)}.")
+  
+  if global_bias.category_multipliers:
+   lines.append("Category focus multipliers:")
+   for cat, mult in global_bias.category_multipliers.items():
+    lines.append(f"- {cat}: {mult}x")
+    
+  return "\n\n".join(lines)
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_presets.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_presets.py
new file mode 100644
index 00000000..168b0f26
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_tool_presets.py
@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import tomllib
+import tomli_w
+
+from dataclasses import dataclass, field
+from pathlib     import Path
+from typing      import Dict, List, Optional, Union, Any
+
+from src               import paths
+from src.type_aliases  import Metadata
+
+
+@dataclass
+class Tool:
+ name:           str
+ approval:       str = 'auto'
+ weight:         int = 3
+ parameter_bias: Dict[str, str] = field(default_factory=dict)
+
+ def to_dict(self) -> Metadata:
+  return {
+   "name":           self.name,
+   "approval":       self.approval,
+   "weight":         self.weight,
+   "parameter_bias": self.parameter_bias,
+  }
+
+ @classmethod
+ def from_dict(cls, data: Metadata) -> "Tool":
+  return cls(
+   name=data["name"],
+   approval=data.get("approval", "auto"),
+   weight=data.get("weight", 3),
+   parameter_bias=data.get("parameter_bias", {}),
+  )
+
+
+@dataclass
+class ToolPreset:
+ name:       str
+ categories: Dict[str, List[Union[Tool, Any]]] = field(default_factory=dict)
+
+ def to_dict(self) -> Metadata:
+  serialized_categories = {}
+  for cat, tools in self.categories.items():
+   serialized_categories[cat] = [t.to_dict() if isinstance(t, Tool) else t for t in tools]
+  return {"categories": serialized_categories}
+
+ @classmethod
+ def from_dict(cls, name: str, data: Metadata) -> "ToolPreset":
+  raw_categories    = data.get("categories", {})
+  parsed_categories = {}
+  for cat, tools in raw_categories.items():
+   parsed_categories[cat] = [Tool.from_dict(t) if isinstance(t, dict) else t for t in tools]
+  return cls(name=name, categories=parsed_categories)
+
+
+class ToolPresetManager:
+ def __init__(self, project_root: Optional[Union[str, Path]] = None):
+  self.project_root = Path(project_root) if project_root else None
+
+ def _get_path(self, scope: str) -> Path:
+  """
+  [C: src/workspace_manager.py:WorkspaceManager.delete_profile, src/workspace_manager.py:WorkspaceManager.save_profile]
+  """
+  if scope == "global":
+   return paths.get_global_tool_presets_path()
+  elif scope == "project":
+   if not self.project_root:
+    raise ValueError("Project root not set for project scope operation.")
+   return paths.get_project_tool_presets_path(self.project_root)
+  else:
+   raise ValueError(f"Invalid scope: {scope}")
+
+ def _read_raw(self, path: Path) -> Dict[str, Any]:
+  if not path.exists():
+   return {}
+  try:
+   with open(path, "rb") as f:
+    return tomllib.load(f)
+  except Exception:
+   return {}
+
+ def _write_raw(self, path: Path, data: Dict[str, Any]) -> None:
+  path.parent.mkdir(parents=True, exist_ok=True)
+  with open(path, "wb") as f:
+   tomli_w.dump(data, f)
+
+ def load_all_presets(self) -> Dict[str, ToolPreset]:
+  """
+  [C: tests/test_tool_preset_manager.py:test_load_all_presets_merged]
+  """
+  global_path = paths.get_global_tool_presets_path()
+  global_data = self._read_raw(global_path).get("presets", {})
+  
+  presets = {}
+  for name, config in global_data.items():
+   if isinstance(config, dict):
+    presets[name] = ToolPreset.from_dict(name, config)
+  
+  if self.project_root:
+   project_path = paths.get_project_tool_presets_path(self.project_root)
+   project_data = self._read_raw(project_path).get("presets", {})
+   for name, config in project_data.items():
+    if isinstance(config, dict):
+     presets[name] = ToolPreset.from_dict(name, config)
+  
+  return presets
+
+ def load_all(self) -> Dict[str, ToolPreset]:
+  """
+  Backward compatibility for load_all().
+  [C: tests/test_persona_manager.py:test_delete_persona, tests/test_persona_manager.py:test_load_all_merged, tests/test_persona_manager.py:test_save_persona, tests/test_preset_manager.py:test_delete_preset, tests/test_preset_manager.py:test_load_all_merged, tests/test_preset_manager.py:test_save_preset_global, tests/test_preset_manager.py:test_save_preset_project, tests/test_presets.py:TestPresetManager.test_delete_preset, tests/test_presets.py:TestPresetManager.test_project_overwrites_global, tests/test_presets.py:TestPresetManager.test_save_and_load_global, tests/test_presets.py:TestPresetManager.test_save_and_load_project]
+  """
+  return self.load_all_presets()
+
+ def save_preset(self, preset: ToolPreset, scope: str = "project") -> None:
+  """
+  [C: tests/test_preset_manager.py:test_save_preset_global, tests/test_preset_manager.py:test_save_preset_project, tests/test_preset_manager.py:test_save_preset_project_no_root, tests/test_presets.py:TestPresetManager.test_delete_preset, tests/test_presets.py:TestPresetManager.test_project_overwrites_global, tests/test_presets.py:TestPresetManager.test_save_and_load_global, tests/test_presets.py:TestPresetManager.test_save_and_load_project]
+  """
+  path = self._get_path(scope)
+  data = self._read_raw(path)
+  if "presets" not in data:
+   data["presets"] = {}
+  data["presets"][preset.name] = preset.to_dict()
+  self._write_raw(path, data)
+
+ def delete_preset(self, name: str, scope: str = "project") -> None:
+  """
+  [C: tests/test_preset_manager.py:test_delete_preset, tests/test_presets.py:TestPresetManager.test_delete_preset]
+  """
+  path = self._get_path(scope)
+  data = self._read_raw(path)
+  if "presets" in data and name in data["presets"]:
+   del data["presets"][name]
+   self._write_raw(path, data)
+
+ def load_all_bias_profiles(self) -> Dict[str, "BiasProfile"]:
+  """
+  [C: tests/test_tool_preset_manager.py:test_bias_profiles_merged, tests/test_tool_preset_manager.py:test_delete_bias_profile, tests/test_tool_preset_manager.py:test_save_bias_profile]
+  """
+  from src.tool_bias import BiasProfile
+  global_path = paths.get_global_tool_presets_path()
+  global_data = self._read_raw(global_path).get("bias_profiles", {})
+  
+  profiles = {}
+  for name, config in global_data.items():
+   if isinstance(config, dict):
+    cfg = dict(config)
+    if "name" not in cfg:
+     cfg["name"] = name
+    profiles[name] = BiasProfile.from_dict(cfg)
+  
+  if self.project_root:
+   project_path = paths.get_project_tool_presets_path(self.project_root)
+   project_data = self._read_raw(project_path).get("bias_profiles", {})
+   for name, config in project_data.items():
+    if isinstance(config, dict):
+     cfg = dict(config)
+     if "name" not in cfg: 
+      cfg["name"] = name
+     profiles[name] = BiasProfile.from_dict(cfg)
+  
+  return profiles
+
+ def save_bias_profile(self, profile: BiasProfile, scope: str = "project") -> None:
+  """
+  [C: tests/test_tool_preset_manager.py:test_save_bias_profile]
+  """
+  path = self._get_path(scope)
+  data = self._read_raw(path)
+  if "bias_profiles" not in data:
+   data["bias_profiles"] = {}
+  data["bias_profiles"][profile.name] = profile.to_dict()
+  self._write_raw(path, data)
+
+ def delete_bias_profile(self, name: str, scope: str = "project") -> None:
+  """
+  [C: tests/test_tool_preset_manager.py:test_delete_bias_profile]
+  """
+  path = self._get_path(scope)
+  data = self._read_raw(path)
+  if "bias_profiles" in data and name in data["bias_profiles"]:
+   del data["bias_profiles"][name]
+   self._write_raw(path, data)
diff --git a/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_workspace_manager.py b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_workspace_manager.py
new file mode 100644
index 00000000..e3ab5890
--- /dev/null
+++ b/scripts/tier2/artifacts/post_module_taxonomy_de_cruft_20260627/resolved_workspace_manager.py
@@ -0,0 +1,109 @@
+import tomllib
+import tomli_w
+
+from dataclasses import dataclass, field
+from pathlib     import Path
+from typing      import Dict, Any, Optional, Union
+
+from src               import paths
+from src.type_aliases import Metadata
+
+
+@dataclass
+class WorkspaceProfile:
+ name:         str
+ ini_content:  str
+ show_windows: Dict[str, bool]
+ panel_states: Metadata
+
+ def to_dict(self) -> Metadata:
+  return {
+   "ini_content":  self.ini_content,
+   "show_windows": self.show_windows,
+   "panel_states": self.panel_states,
+  }
+
+ @classmethod
+ def from_dict(cls, name: str, data: Metadata) -> "WorkspaceProfile":
+  return cls(
+   name         = name,
+   ini_content  = data.get("ini_content", ""),
+   show_windows = data.get("show_windows", {}),
+   panel_states = data.get("panel_states", {}),
+  )
+
+
+class WorkspaceManager:
+ """Manages Workspace profiles across global and project-specific files."""
+
+ def __init__(self, project_root: Optional[Union[str, Path]] = None):
+  if project_root:
+   self.project_root = Path(project_root).resolve()
+  else:
+   self.project_root = None
+
+ def _get_path(self, scope: str) -> Path:
+  if scope == "global":
+   return paths.get_global_workspace_profiles_path()
+  elif scope == "project":
+   if not self.project_root:
+    raise ValueError("Project root is not set, cannot resolve project scope.")
+   return paths.get_project_workspace_profiles_path(self.project_root)
+  else:
+   raise ValueError("Invalid scope, must be 'global' or 'project'")
+
+ def load_all_profiles(self) -> Dict[str, WorkspaceProfile]:
+  """
+  Merges global and project profiles into a single dictionary.
+  [C: tests/test_workspace_manager.py:test_delete_profile, tests/test_workspace_manager.py:test_load_all_profiles_merged, tests/test_workspace_manager.py:test_save_profile_global_and_project]
+  """
+  profiles = {}
+  
+  global_path = paths.get_global_workspace_profiles_path()
+  global_data = self._load_file(global_path)
+  for name, data in global_data.get("profiles", {}).items():
+   profiles[name] = WorkspaceProfile.from_dict(name, data)
+  
+  if self.project_root:
+   project_path = paths.get_project_workspace_profiles_path(self.project_root)
+   project_data = self._load_file(project_path)
+   for name, data in project_data.get("profiles", {}).items():
+    profiles[name] = WorkspaceProfile.from_dict(name, data)
+    
+  return profiles
+
+ def save_profile(self, profile: WorkspaceProfile, scope: str = "project") -> None:
+  """
+  [C: tests/test_workspace_manager.py:test_delete_profile, tests/test_workspace_manager.py:test_save_profile_global_and_project]
+  """
+  path = self._get_path(scope)
+  data = self._load_file(path)
+  if "profiles" not in data:
+   data["profiles"] = {}
+  
+  data["profiles"][profile.name] = profile.to_dict()
+  self._save_file(path, data)
+
+ def delete_profile(self, name: str, scope: str = "project") -> None:
+  """
+  [C: tests/test_workspace_manager.py:test_delete_profile]
+  """
+  path = self._get_path(scope)
+  data = self._load_file(path)
+  if "profiles" in data and name in data["profiles"]:
+   del data["profiles"][name]
+   self._save_file(path, data)
+
+ def _load_file(self, path: Path) -> Dict[str, Any]:
+  if not path.exists():
+   return {}
+  try:
+   with open(path, "rb") as f:
+    return tomllib.load(f)
+  except Exception:
+   return {}
+
+ def _save_file(self, path: Path, data: Dict[str, Any]) -> None:
+  path.parent.mkdir(parents=True, exist_ok=True)
+  with open(path, "wb") as f:
+   tomli_w.dump(data, f)
diff --git a/src/app_controller.py b/src/app_controller.py
index a0c05b6c..701de4b9 100644
--- a/src/app_controller.py
+++ b/src/app_controller.py
@@ -1,4 +1,10 @@
 from __future__ import annotations
+from src.tool_presets import ToolPreset
+from src.mma import Ticket, Track, TrackState
+from src.personas import Persona
+from src.mcp_client import MCPConfiguration, RAGConfig, load_mcp_config
+from src.project_files import ContextPreset, FileItem, NamedViewPreset, Preset
+from src.tool_bias import BiasProfile
 
 import copy
 import inspect
@@ -505,13 +511,13 @@ def _handle_mma_state_update(controller: 'AppController', task: dict):
   if track_data:
    tickets = []
    for t_data in controller.active_tickets:
-    if isinstance(t_data, models.Ticket):
+    if isinstance(t_data, Ticket):
      tickets.append(t_data)
     else:
      if "goal" in t_data and "description" not in t_data:
       t_data["description"] = t_data["goal"]
-     tickets.append(models.Ticket.from_dict(t_data))
-   controller.active_track = models.Track(
+     tickets.append(Ticket.from_dict(t_data))
+   controller.active_track = Track(
     id=track_data.get("id"),
     description=track_data.get("title", ""),
     tickets=tickets
@@ -998,7 +1004,7 @@ class AppController:
   self.discussion_sent_system_prompt: str = ""
   self.disc_roles:                    List[str] = []
   self.tracks:                        list[Metadata] = []
-  self.active_track:                  Optional[models.Track] = None
+  self.active_track:                  Optional[Track] = None
   self.engines:                       Dict[str, multi_agent_conductor.ConductorEngine] = {}
   self.mma_streams:                   Dict[str, str] = {}
   self.MAX_STREAM_SIZE:               int = 10 * 1024
@@ -1017,9 +1023,9 @@ class AppController:
    "Tier 3": {"input": 0, "output": 0, "provider": "gemini", "model": "gemini-2.5-flash-lite",  "tool_preset": None},
    "Tier 4": {"input": 0, "output": 0, "provider": "gemini", "model": "gemini-2.5-flash-lite",  "tool_preset": None},
   }
-  self.mcp_config:                      models.MCPConfiguration = models.MCPConfiguration()
-  self.view_presets:                    list[models.NamedViewPreset] = []
-  self.rag_config:                      Optional[models.RAGConfig] = None
+  self.mcp_config:                      MCPConfiguration = MCPConfiguration()
+  self.view_presets:                    list[NamedViewPreset] = []
+  self.rag_config:                      Optional[RAGConfig] = None
   self.rag_status:                      str = 'idle'
   self.temperature:                     float = 0.0
   self.top_p:                           float = 1.0
@@ -1099,8 +1105,8 @@ class AppController:
   #endregion: UI State
 
   # --- Media/Context ---
-  self.files:         List[models.FileItem] = []
-  self.context_files: List[models.FileItem] = []
+  self.files:         List[FileItem] = []
+  self.context_files: List[FileItem] = []
   self.screenshots:   List[str] = []
 
   # --- Services ---
@@ -1110,7 +1116,7 @@ class AppController:
   # --- Defaults set here so tests that construct AppController without
   # calling init_state() still see the attributes ---
   self.ui_global_preset_name:  Optional[str] = None
-  self.active_tickets:          list[models.Ticket] = []
+  self.active_tickets:          list[Ticket] = []
   self.ui_selected_tickets:     Set[str] = set()
 
   #region: --- Configuration Maps ---
@@ -1753,7 +1759,7 @@ class AppController:
   on `self._mcp_config_parse_error` for sub-track 4 GUI."""
   try:
    data = json.loads(value)
-   self.mcp_config = models.MCPConfiguration.from_dict(data)
+   self.mcp_config = MCPConfiguration.from_dict(data)
    return OK
   except (json.JSONDecodeError, ValueError, TypeError, KeyError, AttributeError) as e:
    return Result(data=None, errors=[ErrorInfo(
@@ -1778,7 +1784,7 @@ class AppController:
     new_files.append(old_files[p])
    else:
     from src import models
-    new_files.append(models.FileItem(path=p, injected_at=now))
+    new_files.append(FileItem(path=p, injected_at=now))
   self.files = new_files
 
  @property
@@ -1998,12 +2004,12 @@ class AppController:
   raw_paths = self.project.get("files", {}).get("paths", [])
   self.files = []
   for p in raw_paths:
-   if isinstance(p, models.FileItem):
+   if isinstance(p, FileItem):
     self.files.append(p)
    elif isinstance(p, dict):
-    self.files.append(models.FileItem.from_dict(p))
+    self.files.append(FileItem.from_dict(p))
    else:
-    self.files.append(models.FileItem(path=str(p)))
+    self.files.append(FileItem(path=str(p)))
   self.screenshots = list(self.project.get("screenshots", {}).get("paths", []))
   disc_sec = self.project.get("discussion", {})
   self.disc_roles = list(disc_sec.get("roles", ["User", "AI", "Vendor API", "System", "Reasoning", "Context"]))
@@ -2040,14 +2046,14 @@ class AppController:
    mcp_p = Path(mcp_path)
    if not mcp_p.is_absolute() and self.active_project_path:
     mcp_p = Path(self.active_project_path).parent / mcp_path
-   if mcp_p.exists(): self.mcp_config = models.load_mcp_config(str(mcp_p))
-   else:              self.mcp_config = models.MCPConfiguration()
+   if mcp_p.exists(): self.mcp_config = load_mcp_config(str(mcp_p))
+   else:              self.mcp_config = MCPConfiguration()
   else:
-   self.mcp_config = models.MCPConfiguration()
+   self.mcp_config = MCPConfiguration()
   
   rag_data = self.config.get('rag')
-  if rag_data: self.rag_config = models.RAGConfig.from_dict(rag_data)
-  else:        self.rag_config = models.RAGConfig()
+  if rag_data: self.rag_config = RAGConfig.from_dict(rag_data)
+  else:        self.rag_config = RAGConfig()
   
   self.rag_engine = None
   if self.rag_config.enabled: self._sync_rag_engine()
@@ -2145,8 +2151,8 @@ class AppController:
   try:
    tickets = []
    for t_data in at_data.get("tickets", []):
-    tickets.append(models.Ticket(**t_data))
-   track = models.Track(
+    tickets.append(Ticket(**t_data))
+   track = Track(
     id=at_data.get("id"),
     description=at_data.get("description"),
     tickets=tickets
@@ -2543,7 +2549,7 @@ class AppController:
     file_path = os.path.relpath(file_path, self.active_project_root)
    existing = next((f for f in self.files if f.path == file_path), None)
    if not existing:
-    item = models.FileItem(path=file_path)
+    item = FileItem(path=file_path)
     self.files.append(item)
     self._refresh_from_project()
 
@@ -3232,19 +3238,19 @@ class AppController:
   raw_paths = self.project.get("files", {}).get("paths", [])
   self.files = []
   for p in raw_paths:
-   if isinstance(p, models.FileItem):
+   if isinstance(p, FileItem):
     self.files.append(p)
    elif isinstance(p, dict):
-    self.files.append(models.FileItem.from_dict(p))
+    self.files.append(FileItem.from_dict(p))
    else:
-    self.files.append(models.FileItem(path=str(p)))
+    self.files.append(FileItem(path=str(p)))
   import copy
   self.context_files = []
   for f in self.files:
-   if isinstance(f, models.FileItem):
+   if isinstance(f, FileItem):
     fi = copy.deepcopy(f)
    else:
-    fi = models.FileItem(path=str(f))
+    fi = FileItem(path=str(f))
    self.context_files.append(fi)
   if hasattr(self, "_app") and self._app is not None:
    self._app.ui_selected_context_files = {f.path for f in self.context_files if f.auto_aggregate}
@@ -3287,7 +3293,7 @@ class AppController:
    if result.ok:
     self.active_track = result.data
     raw_tickets = at_data.get("tickets", [])
-    self.active_tickets = [models.Ticket.from_dict(t) if isinstance(t, dict) else t for t in raw_tickets]
+    self.active_tickets = [Ticket.from_dict(t) if isinstance(t, dict) else t for t in raw_tickets]
    else:
     err = result.errors[0]
     self._last_request_errors.append(("active_track_deserialize", err))
@@ -3320,9 +3326,9 @@ class AppController:
   ai_client.set_bias_profile(self.ui_active_bias_profile)
   raw_presets = proj.get("view_presets", [])
   if isinstance(raw_presets, dict):
-   self.view_presets = [models.NamedViewPreset.from_dict({"name": name, **data}) for name, data in raw_presets.items()]
+   self.view_presets = [NamedViewPreset.from_dict({"name": name, **data}) for name, data in raw_presets.items()]
   else:
-   self.view_presets = [models.NamedViewPreset.from_dict(p) for p in raw_presets if isinstance(p, dict)]
+   self.view_presets = [NamedViewPreset.from_dict(p) for p in raw_presets if isinstance(p, dict)]
   if self.rag_config and self.rag_config.enabled:
    self._rebuild_rag_index()
 
@@ -3396,11 +3402,11 @@ class AppController:
   summarize._summary_cache.clear()
   self._push_mma_state_update()
 
- def save_context_preset(self, preset: models.ContextPreset) -> None:
+ def save_context_preset(self, preset: ContextPreset) -> None:
   self.context_preset_manager.save_preset(self.project, preset)
   self._save_active_project()
 
- def load_context_preset(self, name: str) -> models.ContextPreset:
+ def load_context_preset(self, name: str) -> ContextPreset:
   presets_result = self.context_preset_manager.load_all(self.project)
   if not presets_result.ok:
    raise RuntimeError(f"Failed to load context presets: {presets_result.errors}")
@@ -3413,7 +3419,7 @@ class AppController:
   import copy
   self.context_files = []
   for f in preset.files:
-   fi = models.FileItem(path=f.path, view_mode=f.view_mode)
+   fi = FileItem(path=f.path, view_mode=f.view_mode)
    fi.custom_slices = copy.deepcopy(f.custom_slices)
    fi.ast_mask = copy.deepcopy(f.ast_mask)
    fi.ast_signatures = getattr(f, 'ast_signatures', False)
@@ -3648,7 +3654,7 @@ class AppController:
   """
   if not name or not name.strip():
    raise ValueError("Preset name cannot be empty or whitespace.")
-  preset = models.Preset(
+  preset = Preset(
    name=name,
    system_prompt=content
   )
@@ -3666,7 +3672,7 @@ class AppController:
   """
     [C: src/gui_2.py:App._render_tool_preset_manager_content]
   """
-  preset = models.ToolPreset(name=name, categories=categories)
+  preset = ToolPreset(name=name, categories=categories)
   self.tool_preset_manager.save_preset(preset, scope)
   self.tool_presets = self.tool_preset_manager.load_all_presets()
 
@@ -3677,7 +3683,7 @@ class AppController:
   self.tool_preset_manager.delete_preset(name, scope)
   self.tool_presets = self.tool_preset_manager.load_all_presets()
 
- def _cb_save_bias_profile(self, profile: models.BiasProfile, scope: str = "project"):
+ def _cb_save_bias_profile(self, profile: BiasProfile, scope: str = "project"):
   """
     [C: src/gui_2.py:App._render_tool_preset_manager_content]
   """
@@ -3688,7 +3694,7 @@ class AppController:
   self.tool_preset_manager.delete_bias_profile(name, scope)
   self.bias_profiles = self.tool_preset_manager.load_all_bias_profiles()
 
- def _cb_save_persona(self, persona: models.Persona, scope: str = "project") -> None:
+ def _cb_save_persona(self, persona: Persona, scope: str = "project") -> None:
   """
     [C: src/gui_2.py:App._render_persona_editor_window]
   """
@@ -3702,11 +3708,11 @@ class AppController:
   self.persona_manager.delete_persona(name, scope)
   self.personas = self.persona_manager.load_all()
 
- def _cb_save_view_preset(self, name: str, f_item: models.FileItem) -> None:
+ def _cb_save_view_preset(self, name: str, f_item: FileItem) -> None:
   """
     [C: src/gui_2.py:App._render_context_files_table, tests/test_view_presets.py:test_save_view_preset]
   """
-  preset = models.NamedViewPreset(
+  preset = NamedViewPreset(
    name=name,
    view_mode=f_item.view_mode,
    ast_mask=copy.deepcopy(f_item.ast_mask) if hasattr(f_item, "ast_mask") else {},
@@ -3720,7 +3726,7 @@ class AppController:
    self.view_presets.append(preset)
   self._flush_to_project()
 
- def _cb_apply_view_preset(self, name: str, f_item: models.FileItem) -> None:
+ def _cb_apply_view_preset(self, name: str, f_item: FileItem) -> None:
   """
     [C: src/gui_2.py:App._render_context_files_table, tests/test_view_presets.py:test_apply_view_preset]
   """
@@ -3776,7 +3782,7 @@ class AppController:
   self.discussion_sent_system_prompt = disc_data.get("sent_system_prompt", "")
   if "context_snapshot" in disc_data:
    snapshot_data = disc_data["context_snapshot"]
-   self.context_files = [models.FileItem.from_dict(f) if isinstance(f, dict) else models.FileItem(path=str(f)) for f in snapshot_data]
+   self.context_files = [FileItem.from_dict(f) if isinstance(f, dict) else FileItem(path=str(f)) for f in snapshot_data]
    if self._app:
     self._app.ui_selected_context_files = {f.path for f in self.context_files if f.auto_aggregate}
   self.ai_status = f"discussion: {name}"
@@ -3913,8 +3919,8 @@ class AppController:
   # unsynced forever (test_rag_phase4_final_verify regression on
   # 2026-06-10).
   self.rag_engine = None
-  from src import models as _rag_models
-  self.rag_config = _rag_models.RAGConfig()
+  from src.mcp_client import RAGConfig
+  self.rag_config = RAGConfig()
   self.rag_status = 'idle'
   self._rag_sync_token = 0
   self._rag_sync_dirty = False
@@ -4720,7 +4726,7 @@ class AppController:
   """Phase 6 Group 6.7: topological sort with Result propagation.
   On ValueError: fall back to raw_tickets (preserves existing behavior)."""
   try:
-   normalized = [models.Ticket.from_dict(t) if isinstance(t, dict) else t for t in raw_tickets]
+   normalized = [Ticket.from_dict(t) if isinstance(t, dict) else t for t in raw_tickets]
    sorted_tickets_data = conductor_tech_lead.topological_sort(normalized)
    return Result(data=sorted_tickets_data)
   except ValueError as e:
@@ -4773,7 +4779,7 @@ class AppController:
    # 3. Create Track and Ticket objects
    tickets = []
    for t_data in sorted_tickets_data:
-    ticket = models.Ticket(
+    ticket = Ticket(
      id=t_data["id"],
      description=t_data.get("description") or t_data.get("goal", "No description"),
      status=t_data.get("status", "todo"),
@@ -4783,10 +4789,10 @@ class AppController:
     )
     tickets.append(ticket)
    track_id = f"track_{uuid.uuid5(uuid.NAMESPACE_DNS, f'{self.active_project_path}_{title}').hex[:12]}"
-   track = models.Track(id=track_id, description=title, tickets=tickets)
+   track = Track(id=track_id, description=title, tickets=tickets)
    # Initialize track state in the filesystem
    meta = models.Metadata(id=track_id, name=title, status="todo", created_at=datetime.now(), updated_at=datetime.now())
-   state = models.TrackState(metadata=meta, discussion=[], tasks=tickets)
+   state = TrackState(metadata=meta, discussion=[], tasks=tickets)
    project_manager.save_track_state(track_id, state, self.active_project_root)
    # Add to memory and notify UI
    self.tracks.append({"id": track_id, "title": title, "status": "todo"})
@@ -5031,10 +5037,10 @@ class AppController:
    tickets = []
    for t in state.tasks:
     if isinstance(t, dict):
-     tickets.append(models.Ticket(**t))
+     tickets.append(Ticket(**t))
     else:
      tickets.append(t)
-   self.active_track = models.Track(
+   self.active_track = Track(
     id=state.metadata.id,
     description=state.metadata.name,
     tickets=tickets
@@ -5084,7 +5090,7 @@ class AppController:
    track = self.active_track
    if track is None: return OK
    new_tickets = [
-    models.Ticket(
+    Ticket(
      id=t.id,
      description=t.description,
      status=t.status,
@@ -5094,7 +5100,7 @@ class AppController:
     for t in self.active_tickets
    ]
    track.tickets = new_tickets
-   state = models.TrackState(metadata=track, tasks=list(new_tickets))
+   state = TrackState(metadata=track, tasks=list(new_tickets))
    project_manager.save_track_state(track.id, state, self.active_project_root)
    return OK
   except (OSError, IOError, ValueError, TypeError, KeyError, AttributeError) as e:
@@ -5121,7 +5127,7 @@ class AppController:
     beads_result = self._load_beads_from_path_result(Path(base))
     if beads_result.ok:
      for bead in beads_result.data:
-      self.active_tickets.append(models.Ticket(
+      self.active_tickets.append(Ticket(
        id=bead.id,
        description=bead.description or "",
        status=bead.status,
diff --git a/src/gui_2.py b/src/gui_2.py
index 14448360..5cb97ff2 100644
--- a/src/gui_2.py
+++ b/src/gui_2.py
@@ -357,7 +357,7 @@ class App:
   self.controller._predefined_callbacks['delete_context_preset']      = self.delete_context_preset
   self.controller._predefined_callbacks['set_ui_file_paths']          = lambda p: setattr(self, 'ui_file_paths', p)
   self.controller._predefined_callbacks['set_ui_screenshot_paths']    = lambda p: setattr(self, 'ui_screenshot_paths', p)
-  self.controller._predefined_callbacks['set_context_files_for_test'] = lambda files: setattr(self, 'context_files', [models.FileItem(path=f) for f in files])
+  self.controller._predefined_callbacks['set_context_files_for_test'] = lambda files: setattr(self, 'context_files', [FileItem(path=f) for f in files])
   self.controller._predefined_callbacks['set_screenshots_for_test']   = lambda ss: setattr(self, 'screenshots', ss)
   self.controller._predefined_callbacks['_toggle_command_palette']    = self._toggle_command_palette
   self.controller._gettable_fields['show_command_palette']            = 'show_command_palette'
@@ -373,8 +373,8 @@ class App:
     msk = copy.deepcopy(f.ast_mask)
     sig = f.ast_signatures
     dfn = f.ast_definitions
-    preset_files.append(models.ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
-   preset = models.ContextPreset(name=name, files=preset_files, screenshots=list(self.screenshots))
+    preset_files.append(ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
+   preset = ContextPreset(name=name, files=preset_files, screenshots=list(self.screenshots))
    self.controller.save_context_preset(preset)
    self.ui_new_context_preset_name = ""
    self.show_missing_files_modal = False  
@@ -541,12 +541,12 @@ class App:
 
  def _set_context_files(self, paths: list[str]) -> None:
   from src import models
-  self.context_files            = [models.FileItem(path=p) for p in paths]
+  self.context_files            = [FileItem(path=p) for p in paths]
   self.controller.context_files = self.context_files
 
  def _simulate_save_preset(self, name: str) -> None:
   from src import models
-  item               = models.FileItem(path='test.py')
+  item               = FileItem(path='test.py')
   self.files         = [item]
   self.context_files = [item]
   self.screenshots   = ['test.png']
@@ -865,20 +865,20 @@ class App:
    from src import models
    self.files = []
    for f in snapshot.files:
-    if isinstance(f, dict): self.files.append(models.FileItem.from_dict(f))
-    else:                   self.files.append(models.FileItem(path=str(f)))
+    if isinstance(f, dict): self.files.append(FileItem.from_dict(f))
+    else:                   self.files.append(FileItem(path=str(f)))
    
    self.context_files = []
    for f in snapshot.context_files:
-    if isinstance(f, dict): self.context_files.append(models.FileItem.from_dict(f))
-    else:                   self.context_files.append(models.FileItem(path=str(f)))
+    if isinstance(f, dict): self.context_files.append(FileItem.from_dict(f))
+    else:                   self.context_files.append(FileItem(path=str(f)))
    
    self.screenshots       = list(snapshot.screenshots)
    self._last_ui_snapshot = snapshot # Update last snapshot to avoid immediate re-push
   finally:
    self._is_applying_snapshot = False # ?? TODO(Ed): Whats the point of this??
 
- def _capture_workspace_profile(self, name: str) -> models.WorkspaceProfile:
+ def _capture_workspace_profile(self, name: str) -> WorkspaceProfile:
   """Serializes the current window visibility states, popped-out panel layouts, and
   ImGui INI configurations into a WorkspaceProfile object.
   SSDL Shape: `[Q:ui_states] -> [B:ini_ready] -> [T:profile]`
@@ -908,14 +908,14 @@ class App:
    "ui_separate_external_tools":   getattr(self, "ui_separate_external_tools",   False),
    "ui_discussion_split_h":        getattr(self, "ui_discussion_split_h",        300.0),
   }
-  return models.WorkspaceProfile(
+  return WorkspaceProfile(
    name         = name,
    ini_content  = ini,
    show_windows = copy.deepcopy(self.show_windows),
    panel_states = panel_states
   )
 
- def _apply_workspace_profile(self, profile: models.WorkspaceProfile):
+ def _apply_workspace_profile(self, profile: WorkspaceProfile):
   """Restores the window docking layout and popped-out panel visibility states
   from a saved WorkspaceProfile.
   SSDL Shape: `[I:load_ini] -> [S:ui_states]`
@@ -975,7 +975,7 @@ class App:
   import copy
   self.context_files = []
   for f in preset.files:
-   fi = models.FileItem(path=f.path, view_mode=f.view_mode)
+   fi = FileItem(path=f.path, view_mode=f.view_mode)
    fi.custom_slices   = copy.deepcopy(f.custom_slices)
    fi.ast_mask        = copy.deepcopy(f.ast_mask)
    fi.ast_signatures  = getattr(f, 'ast_signatures', False)
@@ -1007,7 +1007,7 @@ class App:
     new_files.append(old_files[p])
    else:
     from src import models
-    new_files.append(models.FileItem(path=p, injected_at=now))
+    new_files.append(FileItem(path=p, injected_at=now))
   self.files = new_files
 
  @property
@@ -1259,7 +1259,7 @@ class App:
   self.init_state()
   self.ai_status = 'paths applied and session reset'
 
- def _populate_auto_slices(self, f_item: models.FileItem) -> None:
+ def _populate_auto_slices(self, f_item: FileItem) -> None:
   import re
   from pathlib import Path
   import os
@@ -3291,11 +3291,11 @@ def render_tool_preset_manager_content(app: App, is_embedded: bool = False) -> N
            if tool: curr_cat_tools.remove(tool)
           imgui.same_line(); 
           if imgui.radio_button(f"Auto##{cat_name}_{tool_name}", mode == "auto"):
-           if not tool: tool = models.Tool(name=tool_name, approval="auto"); curr_cat_tools.append(tool)
+           if not tool: tool = Tool(name=tool_name, approval="auto"); curr_cat_tools.append(tool)
            else: tool.approval = "auto"
           imgui.same_line(); 
           if imgui.radio_button(f"Ask##{cat_name}_{tool_name}", mode == "ask"):
-           if not tool: tool = models.Tool(name=tool_name, approval="ask"); curr_cat_tools.append(tool)
+           if not tool: tool = Tool(name=tool_name, approval="ask"); curr_cat_tools.append(tool)
            else: tool.approval = "ask"
        imgui.tree_pop()
     if app._bias_list_open:
@@ -3694,7 +3694,7 @@ def render_files_and_media(app: App) -> None:
          if imgui.button(f"+##add_f_{i}"):
           if not in_context:
            from src import models
-           new_item = models.FileItem(path=fpath)
+           new_item = FileItem(path=fpath)
            app.context_files.append(new_item)
            app._populate_auto_slices(new_item)
          
@@ -3718,7 +3718,7 @@ def render_files_and_media(app: App) -> None:
    r = hide_tk_root(); paths = filedialog.askopenfilenames(); r.destroy()
    from src import models
    for p in paths:
-    if p not in [f.path for f in app.files]: app.files.append(models.FileItem(path=p))
+    if p not in [f.path for f in app.files]: app.files.append(FileItem(path=p))
   imgui.same_line()
   if imgui.button("Add Directory"):
    r = hide_tk_root(); dirpath = filedialog.askdirectory(); r.destroy()
@@ -3728,7 +3728,7 @@ def render_files_and_media(app: App) -> None:
      for fname in files:
       full = os.path.join(root, fname)
       if full not in existing:
-       app.files.append(models.FileItem(path=full))
+       app.files.append(FileItem(path=full))
        existing.add(full)
  
  imgui.separator()
@@ -3852,7 +3852,7 @@ def render_add_context_files_modal(app: App) -> None:
   
   if imgui.button("Add Selected", imgui.ImVec2(120, 0)):
    for fpath in app._ui_picker_selected:
-    f_item = models.FileItem(path=fpath)
+    f_item = FileItem(path=fpath)
     app.context_files.append(f_item)
     app._populate_auto_slices(f_item)
    app._ui_picker_selected.clear()
@@ -4369,8 +4369,8 @@ def render_context_presets(app: App) -> None:
      msk = copy.deepcopy(f.ast_mask)
      sig = f.ast_signatures
      dfn = f.ast_definitions
-     preset_files.append(models.ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
-    preset = models.ContextPreset(name=active, files=preset_files, screenshots=list(app.screenshots))
+     preset_files.append(ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
+    preset = ContextPreset(name=active, files=preset_files, screenshots=list(app.screenshots))
     app.controller.save_context_preset(preset)
   else:
    imgui.text_disabled("No active preset")
@@ -4409,8 +4409,8 @@ def render_context_presets(app: App) -> None:
       msk = copy.deepcopy(f.ast_mask)
       sig = f.ast_signatures
       dfn = f.ast_definitions
-      preset_files.append(models.ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
-     preset = models.ContextPreset(name=name, files=preset_files, screenshots=list(app.screenshots))
+      preset_files.append(ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
+     preset = ContextPreset(name=name, files=preset_files, screenshots=list(app.screenshots))
      app.controller.save_context_preset(preset)
      app.ui_new_context_preset_name = ""
 
@@ -4544,8 +4544,8 @@ def render_context_modals(app: App) -> None:
     msk = copy.deepcopy(f.ast_mask)
     sig = f.ast_signatures
     dfn = f.ast_definitions
-    preset_files.append(models.ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
-   preset = models.ContextPreset(name=name, files=preset_files, screenshots=list(app.screenshots))
+    preset_files.append(ContextFileEntry(path=p, view_mode=vm, custom_slices=slc, ast_mask=msk, ast_signatures=sig, ast_definitions=dfn))
+   preset = ContextPreset(name=name, files=preset_files, screenshots=list(app.screenshots))
    app.controller.save_context_preset(preset)
    app.ui_new_context_preset_name = ""
    imgui.close_current_popup()
@@ -7839,7 +7839,7 @@ def _handle_history_logic_result(app: "App") -> Result[bool]:
 def _render_persona_editor_save_result(app: "App") -> Result[bool]:
  """Drain-aware variant of L3398 render_persona_editor_window Save button try/except.
 
- Extracts the models.Persona(...) construction + app.controller._cb_save_persona
+ Extracts the Persona(...) construction + app.controller._cb_save_persona
  try/except from the Save button handler in render_persona_editor_window into a
  Result-returning helper. On success, sets app.ai_status to "Saved: <name>"
  and returns Result(data=True). On failure (any exception in Persona
@@ -7853,7 +7853,7 @@ def _render_persona_editor_save_result(app: "App") -> Result[bool]:
  """
  try:
   import copy
-  persona = models.Persona(
+  persona = Persona(
    name=app._editing_persona_name.strip(),
    system_prompt=app._editing_persona_system_prompt,
    tool_preset=app._editing_persona_tool_preset_id or None,
@@ -8158,7 +8158,7 @@ def _render_tool_preset_bias_save_result(app: "App") -> Result[bool]:
  [C: src/gui_2.py:render_tool_preset_manager_content (L3163 legacy wrapper)]
  """
  try:
-  p = models.BiasProfile(
+  p = BiasProfile(
    name=app._editing_bias_profile_name,
    tool_weights=app._editing_bias_profile_tool_weights,
    category_multipliers=app._editing_bias_profile_category_multipliers,
diff --git a/src/project_manager.py b/src/project_manager.py
index ba4c842c..0e381f69 100644
--- a/src/project_manager.py
+++ b/src/project_manager.py
@@ -194,7 +194,7 @@ def load_project(path: Union[str, Path]) -> Metadata:
  # Deserialise FileItems in files.paths
  if "files" in proj and "paths" in proj["files"]:
   from src import models
-  proj["files"]["paths"] = [models.FileItem.from_dict(p) if isinstance(p, dict) else p for p in proj["files"]["paths"]]
+  proj["files"]["paths"] = [FileItem.from_dict(p) if isinstance(p, dict) else p for p in proj["files"]["paths"]]
  hist_path = get_history_path(path)
  if "discussion" in proj:
   disc = proj.pop("discussion")
diff --git a/src/rag_engine.py b/src/rag_engine.py
index a9880edd..e87b2096 100644
--- a/src/rag_engine.py
+++ b/src/rag_engine.py
@@ -8,10 +8,11 @@ from dataclasses import dataclass, field, fields as dc_fields
 from typing import List, Dict, Any, Optional
 
 from src import ai_client
-from src import models
 from src import mcp_client
-from src.result_types import ErrorInfo, ErrorKind, NilRAGState, Result
-from src.type_aliases import Metadata
+from src import models
+from src.mcp_client          import RAGConfig
+from src.result_types       import ErrorInfo, ErrorKind, NilRAGState, Result
+from src.type_aliases       import Metadata
 
 from src.file_cache import ASTParser
 
@@ -121,7 +122,7 @@ def _parse_search_response_result(res_str: str) -> Result[List[Dict[str, Any]]]:
 
 
 class RAGEngine:
- def __init__(self, config: models.RAGConfig, base_dir: str = "."):
+ def __init__(self, config: RAGConfig, base_dir: str = "."):
   self.config             = copy.deepcopy(config)
   self.base_dir           = base_dir
   self.client             = None
diff --git a/src/type_aliases.py b/src/type_aliases.py
index 5cde7725..dd37b9fa 100644
--- a/src/type_aliases.py
+++ b/src/type_aliases.py
@@ -146,7 +146,7 @@ class HistoryMessage:
 History: TypeAlias = list[HistoryMessage]
 
 
-FileItem: TypeAlias = "models.FileItem"
+FileItem: TypeAlias = "FileItem"
 FileItems: TypeAlias = list[FileItem]
 
 
diff --git a/tests/test_ast_inspector_extended.py b/tests/test_ast_inspector_extended.py
index 205eaf59..616fb2be 100644
--- a/tests/test_ast_inspector_extended.py
+++ b/tests/test_ast_inspector_extended.py
@@ -8,7 +8,7 @@ def test_ast_inspector_line_range_parsing():
  app = MagicMock(spec=App)
  app._show_ast_inspector = True
  app.show_structural_editor_modal = True
- app.ui_inspecting_ast_file = models.FileItem(path="test.py")
+ app.ui_inspecting_ast_file = FileItem(path="test.py")
  app.ui_editing_slices_file = app.ui_inspecting_ast_file
  app._cached_ast_file_path = ""
  app._cached_ast_nodes = []
diff --git a/tests/test_auto_slices.py b/tests/test_auto_slices.py
index e0d2632a..6d0bc95a 100644
--- a/tests/test_auto_slices.py
+++ b/tests/test_auto_slices.py
@@ -27,7 +27,7 @@ def mock_app():
   return app
 
 def test_populate_auto_slices_basic(mock_app: App) -> None:
- f_item = models.FileItem(path="test.py")
+ f_item = FileItem(path="test.py")
  mock_outline = "[Class] MyClass (Lines 1-10)\n[Method] my_method (Lines 2-5)\n[Func] top_func (Lines 12-15)"
  
  with (
diff --git a/tests/test_external_mcp.py b/tests/test_external_mcp.py
index 579d5dd5..fee8981f 100644
--- a/tests/test_external_mcp.py
+++ b/tests/test_external_mcp.py
@@ -11,7 +11,7 @@ async def test_external_mcp_real_process():
     
     # Use our mock script
     mock_script = "scripts/mock_mcp_server.py"
-    config = models.MCPServerConfig(
+    config = MCPServerConfig(
         name="real-mock", 
         command="python", 
         args=[mock_script]
@@ -36,7 +36,7 @@ async def test_get_tool_schemas_includes_external():
     await manager.stop_all()
     
     mock_script = "scripts/mock_mcp_server.py"
-    config = models.MCPServerConfig(
+    config = MCPServerConfig(
         name="test-server", 
         command="python", 
         args=[mock_script]
diff --git a/tests/test_files_and_media_tree.py b/tests/test_files_and_media_tree.py
index efa23ea2..53460d91 100644
--- a/tests/test_files_and_media_tree.py
+++ b/tests/test_files_and_media_tree.py
@@ -9,7 +9,7 @@ def test_files_rendered_under_directory_grouping(app_instance):
   os.makedirs(sub, exist_ok=True)
   for p in [os.path.join(tmp, "a.py"), os.path.join(tmp, "b.py"), os.path.join(sub, "c.py")]:
    open(p, "w").close()
-  app_instance.files = [models.FileItem(path=os.path.join(tmp, "a.py")), models.FileItem(path=os.path.join(tmp, "b.py")), models.FileItem(path=os.path.join(sub, "c.py"))]
+  app_instance.files = [FileItem(path=os.path.join(tmp, "a.py")), FileItem(path=os.path.join(tmp, "b.py")), FileItem(path=os.path.join(sub, "c.py"))]
   with patch("src.gui_2.imgui") as mock_imgui, patch("src.gui_2.imscope") as mock_imscope, patch("src.gui_2.filedialog") as mock_filedialog, patch("src.gui_2.hide_tk_root", return_value=MagicMock()):
    mock_imgui.collapsing_header.return_value = True
    mock_imgui.TableFlags_ = type("T", (), {"resizable": 1, "borders": 2, "row_bg": 4})()
diff --git a/tests/test_gui_2_result.py b/tests/test_gui_2_result.py
index 90ccbf13..860c1159 100644
--- a/tests/test_gui_2_result.py
+++ b/tests/test_gui_2_result.py
@@ -715,7 +715,7 @@ def test_phase_4_l3398_render_persona_editor_save_result_success():
  L3398 _render_persona_editor_save_result returns Result.ok=True on success.
 
  The helper wraps the Save button try/except in render_persona_editor_window
- (Persona creation: models.Persona(...) + _cb_save_persona). On success,
+ (Persona creation: Persona(...) + _cb_save_persona). On success,
  sets app.ai_status to "Saved: <name>" and returns Result(data=True).
  """
  from src import gui_2
diff --git a/tests/test_gui_kill_button.py b/tests/test_gui_kill_button.py
index b6c72964..5416a5d8 100644
--- a/tests/test_gui_kill_button.py
+++ b/tests/test_gui_kill_button.py
@@ -37,7 +37,7 @@ def test_render_ticket_queue_table_columns():
   from src.gui_2 import App, render_ticket_queue
   app = App.__new__(App)
   app.active_track = MagicMock()
-  app.active_tickets = [models.Ticket(id="T-001", description="Test task", priority="medium", status="in_progress")]
+  app.active_tickets = [Ticket(id="T-001", description="Test task", priority="medium", status="in_progress")]
   app.ui_selected_tickets = set()
   app.ui_selected_ticket_id = None
   app.controller = MagicMock()
diff --git a/tests/test_gui_progress.py b/tests/test_gui_progress.py
index e7623de7..95c5c229 100644
--- a/tests/test_gui_progress.py
+++ b/tests/test_gui_progress.py
@@ -34,7 +34,7 @@ def test_render_mma_dashboard_progress():
   app.active_track = MagicMock()
   app.active_track.description = "Test Track"
   
-  # Mock self.active_track.tickets as a list of src.models.Ticket objects
+  # Mock self.active_track.tickets as a list of src.Ticket objects
   app.active_track.tickets = [
    Ticket(id='T1', description='desc', status='completed'),
    Ticket(id='T2', description='desc', status='in_progress'),
diff --git a/tests/test_mcp_config.py b/tests/test_mcp_config.py
index 0574321c..29e8b7f4 100644
--- a/tests/test_mcp_config.py
+++ b/tests/test_mcp_config.py
@@ -9,7 +9,7 @@ def test_mcp_server_config_to_from_dict():
         "args": ["server.js"],
         "auto_start": True
     }
-    cfg = models.MCPServerConfig.from_dict("test-server", data)
+    cfg = MCPServerConfig.from_dict("test-server", data)
     assert cfg.name == "test-server"
     assert cfg.command == "node"
     assert cfg.args == ["server.js"]
@@ -31,7 +31,7 @@ def test_mcp_configuration_to_from_dict():
             }
         }
     }
-    cfg = models.MCPConfiguration.from_dict(data)
+    cfg = MCPConfiguration.from_dict(data)
     assert len(cfg.mcpServers) == 2
     assert cfg.mcpServers["server1"].command == "python"
     assert cfg.mcpServers["server2"].url == "http://localhost:8080/sse"
@@ -47,7 +47,7 @@ def test_load_mcp_config(tmp_path):
     config_file.write_text(json.dumps(data))
     
     # We'll need a way to load from a specific path
-    # Maybe models.load_mcp_config(path)
-    cfg = models.load_mcp_config(str(config_file))
+    # Maybe load_mcp_config(path)
+    cfg = load_mcp_config(str(config_file))
     assert "test" in cfg.mcpServers
     assert cfg.mcpServers["test"].command == "echo"
diff --git a/tests/test_metadata_promotion_phase1.py b/tests/test_metadata_promotion_phase1.py
index 92fa3e89..f798244c 100644
--- a/tests/test_metadata_promotion_phase1.py
+++ b/tests/test_metadata_promotion_phase1.py
@@ -2,8 +2,8 @@
 Phase 1 of metadata_promotion_20260624.
 
 Verifies:
- 1. self.active_tickets load boundaries convert dicts to models.Ticket
- 2. conductor_tech_lead.topological_sort returns list[models.Ticket]
+ 1. self.active_tickets load boundaries convert dicts to Ticket
+ 2. conductor_tech_lead.topological_sort returns list[Ticket]
  3. gui_2.py consumer sites use direct field access (not .get())
  4. app_controller.py consumer sites use direct field access (not .get())
 """
@@ -15,11 +15,11 @@ from src.mma import Ticket
 
 class TestActiveTicketsType:
  def test_active_tickets_annotation_is_list_of_ticket(self) -> None:
-  """self.active_tickets type hint must be list[models.Ticket], not list[Metadata]."""
+  """self.active_tickets type hint must be list[Ticket], not list[Metadata]."""
   from src.app_controller import AppController
   src_text = inspect.getsource(AppController.__init__)
-  assert "list[models.Ticket]" in src_text, (
-   "AppController.__init__ must declare self.active_tickets: list[models.Ticket]"
+  assert "list[Ticket]" in src_text, (
+   "AppController.__init__ must declare self.active_tickets: list[Ticket]"
   )
   assert "list[Metadata]" not in src_text.split("self.active_tickets")[1].split("\n")[0], (
    "AppController.__init__ must NOT declare self.active_tickets: list[Metadata]"
@@ -28,7 +28,7 @@ class TestActiveTicketsType:
 
 class TestActiveTicketsLoadBoundaries:
  def test_load_at_data_converts_dicts_to_tickets(self) -> None:
-  """_deserialize_active_track_result boundary must wrap dicts as models.Ticket."""
+  """_deserialize_active_track_result boundary must wrap dicts as Ticket."""
   from src.app_controller import AppController
   with patch.object(AppController, "load_config", return_value={
    'ai': {'provider': 'gemini', 'model': 'gemini-2.5-flash-lite'},
@@ -56,7 +56,7 @@ class TestActiveTicketsLoadBoundaries:
     )
 
  def test_load_active_tickets_beads_branch_converts_dicts_to_tickets(self) -> None:
-  """_load_active_tickets (beads branch) must wrap bead dicts as models.Ticket."""
+  """_load_active_tickets (beads branch) must wrap bead dicts as Ticket."""
   from src.app_controller import AppController
   from src.mma import Ticket
   ctrl = AppController.__new__(AppController)
@@ -79,7 +79,7 @@ class TestActiveTicketsLoadBoundaries:
 
 class TestTopologicalSortReturnsTicketList:
  def test_topological_sort_returns_ticket_instances(self) -> None:
-  """conductor_tech_lead.topological_sort must return list[models.Ticket]."""
+  """conductor_tech_lead.topological_sort must return list[Ticket]."""
   from src import conductor_tech_lead
   sig = inspect.signature(conductor_tech_lead.topological_sort)
   assert sig.return_annotation is not inspect.Signature.empty
diff --git a/tests/test_project_context_20260627.py b/tests/test_project_context_20260627.py
index 2a1e4bfc..c004c13b 100644
--- a/tests/test_project_context_20260627.py
+++ b/tests/test_project_context_20260627.py
@@ -11,7 +11,7 @@ from __future__ import annotations
 import pytest
 
 from src.project_manager import flat_config
-from src.models import (
+from src.project import (
     ProjectContext, ProjectMeta, ProjectOutput, ProjectFiles,
     ProjectScreenshots, ProjectDiscussion, EMPTY_PROJECT_CONTEXT,
 )
diff --git a/tests/test_project_serialization.py b/tests/test_project_serialization.py
index b1a7834a..dacb9d99 100644
--- a/tests/test_project_serialization.py
+++ b/tests/test_project_serialization.py
@@ -17,8 +17,8 @@ class TestProjectSerialization(unittest.TestCase):
  def test_fileitem_roundtrip(self):
   """Verify that FileItem objects survive a save/load cycle."""
   proj = project_manager.default_project("test")
-  file1 = models.FileItem(path="src/main.py", auto_aggregate=True, force_full=False)
-  file2 = models.FileItem(path="docs/readme.md", auto_aggregate=False, force_full=True)
+  file1 = FileItem(path="src/main.py", auto_aggregate=True, force_full=False)
+  file2 = FileItem(path="docs/readme.md", auto_aggregate=False, force_full=True)
   proj["files"]["paths"] = [file1, file2]
   
   # Save
@@ -29,12 +29,12 @@ class TestProjectSerialization(unittest.TestCase):
   
   paths = loaded_proj["files"]["paths"]
   self.assertEqual(len(paths), 2)
-  self.assertIsInstance(paths[0], models.FileItem)
+  self.assertIsInstance(paths[0], FileItem)
   self.assertEqual(paths[0].path, "src/main.py")
   self.assertTrue(paths[0].auto_aggregate)
   self.assertFalse(paths[0].force_full)
   
-  self.assertIsInstance(paths[1], models.FileItem)
+  self.assertIsInstance(paths[1], FileItem)
   self.assertEqual(paths[1].path, "docs/readme.md")
   self.assertFalse(paths[1].auto_aggregate)
   self.assertTrue(paths[1].force_full)
@@ -68,17 +68,17 @@ roles = ["User", "AI"]
   raw_paths = controller.project.get("files", {}).get("paths", [])
   controller.files = []
   for p in raw_paths:
-   if isinstance(p, models.FileItem):
+   if isinstance(p, FileItem):
     controller.files.append(p)
    elif isinstance(p, dict):
-    controller.files.append(models.FileItem.from_dict(p))
+    controller.files.append(FileItem.from_dict(p))
    else:
-    controller.files.append(models.FileItem(path=str(p)))
+    controller.files.append(FileItem(path=str(p)))
     
   self.assertEqual(len(controller.files), 2)
-  self.assertIsInstance(controller.files[0], models.FileItem)
+  self.assertIsInstance(controller.files[0], FileItem)
   self.assertEqual(controller.files[0].path, "file1.py")
-  self.assertIsInstance(controller.files[1], models.FileItem)
+  self.assertIsInstance(controller.files[1], FileItem)
   self.assertEqual(controller.files[1].path, "file2.md")
 
  def test_default_roles_include_context(self):
diff --git a/tests/test_rag_engine.py b/tests/test_rag_engine.py
index d3c883c1..e307ddc5 100644
--- a/tests/test_rag_engine.py
+++ b/tests/test_rag_engine.py
@@ -11,8 +11,8 @@ class MockEmbeddingProvider(BaseEmbeddingProvider):
 
 @pytest.fixture
 def mock_rag_config():
- vs_config = models.VectorStoreConfig(provider='mock', collection_name='test')
- return models.RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='gemini')
+ vs_config = VectorStoreConfig(provider='mock', collection_name='test')
+ return RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='gemini')
 
 def test_rag_engine_init_mock(mock_rag_config):
  engine = RAGEngine(mock_rag_config)
@@ -38,8 +38,8 @@ def test_rag_engine_chroma(mock_get_chroma, mock_embed):
  mock_client.get_or_create_collection.return_value = mock_collection
  mock_chroma.PersistentClient.return_value = mock_client
 
- vs_config = models.VectorStoreConfig(provider='chroma', collection_name='test')
- config = models.RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
+ vs_config = VectorStoreConfig(provider='chroma', collection_name='test')
+ config = RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
 
  with patch('src.rag_engine._get_sentence_transformers') as mock_st:
   mock_st.return_value = MagicMock()
@@ -97,8 +97,8 @@ def test_rag_collection_dim_mismatch_recreates_collection(mock_get_chroma, mock_
  mock_client.get_or_create_collection.return_value = mock_collection
  mock_chroma.PersistentClient.return_value = mock_client
 
- vs_config = models.VectorStoreConfig(provider='chroma', collection_name='test')
- config = models.RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
+ vs_config = VectorStoreConfig(provider='chroma', collection_name='test')
+ config = RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
 
  with patch('src.rag_engine._get_sentence_transformers') as mock_st:
   mock_st.return_value = MagicMock()
@@ -136,8 +136,8 @@ def test_rag_collection_dim_match_preserves_collection(mock_get_chroma, mock_emb
  mock_client.get_or_create_collection.return_value = mock_collection
  mock_chroma.PersistentClient.return_value = mock_client
 
- vs_config = models.VectorStoreConfig(provider='chroma', collection_name='test')
- config = models.RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
+ vs_config = VectorStoreConfig(provider='chroma', collection_name='test')
+ config = RAGConfig(enabled=True, vector_store=vs_config, embedding_provider='local')
 
  with patch('src.rag_engine._get_sentence_transformers') as mock_st:
   mock_st.return_value = MagicMock()
diff --git a/tests/test_rag_engine_ready_status_bug.py b/tests/test_rag_engine_ready_status_bug.py
index b6086750..2a9889ab 100644
--- a/tests/test_rag_engine_ready_status_bug.py
+++ b/tests/test_rag_engine_ready_status_bug.py
@@ -37,10 +37,10 @@ def test_rag_engine_init_with_local_provider_raises_when_sentence_transformers_m
  when sentence-transformers is not installed.
  """
  from src import models
- config = models.RAGConfig(
+ config = RAGConfig(
    enabled=True,
    embedding_provider="local",
-   vector_store=models.VectorStoreConfig(provider="chroma", collection_name="test"),
+   vector_store=VectorStoreConfig(provider="chroma", collection_name="test"),
  )
  # Force the import to fail
  with patch.dict(sys.modules, {"sentence_transformers": None}):
@@ -125,10 +125,10 @@ def test_rag_engine_init_with_failing_local_embedding_leaves_engine_broken() ->
  """
  from src import models
  from src import rag_engine
- config = models.RAGConfig(
+ config = RAGConfig(
    enabled=True,
    embedding_provider="local",
-   vector_store=models.VectorStoreConfig(provider="chroma", collection_name="t"),
+   vector_store=VectorStoreConfig(provider="chroma", collection_name="t"),
  )
  with patch("src.rag_engine._get_sentence_transformers",
     side_effect=ImportError("Local RAG embeddings require sentence-transformers.")):
diff --git a/tests/test_rag_integration.py b/tests/test_rag_integration.py
index 8dd6ae36..fdc97bd3 100644
--- a/tests/test_rag_integration.py
+++ b/tests/test_rag_integration.py
@@ -55,9 +55,9 @@ def test_rag_integration(mock_project):
   ai_client.set_provider("gemini", "gemini-1.5-flash")
 
  # 2. Configures a mock RAG setup (enabled=True, provider='mock').
- rag_config = models.RAGConfig(
+ rag_config = RAGConfig(
   enabled=True,
-  vector_store=models.VectorStoreConfig(provider='mock')
+  vector_store=VectorStoreConfig(provider='mock')
  )
  app.rag_config = rag_config
  
diff --git a/tests/test_ui_summary_only_removal.py b/tests/test_ui_summary_only_removal.py
index 3abf3f66..3855b0e2 100644
--- a/tests/test_ui_summary_only_removal.py
+++ b/tests/test_ui_summary_only_removal.py
@@ -25,7 +25,7 @@ def test_ui_summary_only_not_in_app_controller_projects():
 
 
 def test_file_item_has_per_file_flags():
- item = models.FileItem(path="test.py")
+ item = FileItem(path="test.py")
  assert hasattr(item, "auto_aggregate")
  assert hasattr(item, "force_full")
  assert item.auto_aggregate is True
@@ -33,13 +33,13 @@ def test_file_item_has_per_file_flags():
 
 
 def test_file_item_serialization_with_flags():
- item = models.FileItem(path="test.py", auto_aggregate=False, force_full=True)
+ item = FileItem(path="test.py", auto_aggregate=False, force_full=True)
  data = item.to_dict()
 
  assert data["auto_aggregate"] is False
  assert data["force_full"] is True
 
- restored = models.FileItem.from_dict(data)
+ restored = FileItem.from_dict(data)
  assert restored.auto_aggregate is False
  assert restored.force_full is True
 
diff --git a/tests/test_view_presets.py b/tests/test_view_presets.py
index 85f890ac..26628563 100644
--- a/tests/test_view_presets.py
+++ b/tests/test_view_presets.py
@@ -38,7 +38,7 @@ def controller(tmp_path):
  return ctrl
 
 def test_save_view_preset(controller):
- f_item = models.FileItem(path="test.py", view_mode="skeleton")
+ f_item = FileItem(path="test.py", view_mode="skeleton")
  f_item.ast_mask = {"test::func": "sig"}
  f_item.custom_slices = [{"start_line": 1, "end_line": 10}]
  
@@ -58,7 +58,7 @@ def test_save_view_preset(controller):
 
 def test_apply_view_preset(controller):
  # Setup a preset
- preset = models.NamedViewPreset(
+ preset = NamedViewPreset(
   name="my_preset",
   view_mode="masked",
   ast_mask={"main::run": "def"},
@@ -67,7 +67,7 @@ def test_apply_view_preset(controller):
  controller.view_presets.append(preset)
  
  # Create a file item to apply to
- f_item = models.FileItem(path="main.py", view_mode="summary")
+ f_item = FileItem(path="main.py", view_mode="summary")
  
  controller._cb_apply_view_preset("my_preset", f_item)
  
@@ -76,7 +76,7 @@ def test_apply_view_preset(controller):
  assert f_item.custom_slices == [{"start_line": 5, "end_line": 15}]
 
 def test_delete_view_preset(controller):
- preset = models.NamedViewPreset(name="to_del", view_mode="full")
+ preset = NamedViewPreset(name="to_del", view_mode="full")
  controller.view_presets.append(preset)
  
  controller._cb_delete_view_preset("to_del")