stravinsky 0.1.2__py3-none-any.whl → 0.2.38__py3-none-any.whl

mcp_bridge/server.py

@@ -1,17 +1,17 @@
 """
-Claude Superagent MCP Bridge Server
+Stravinsky MCP Bridge Server - Zero-Import-Weight Architecture
 
-Main entry point for the MCP server that provides tools for:
-- OAuth-authenticated Gemini model invocation
-- OAuth-authenticated OpenAI model invocation
-- LSP tool proxies
-- Session management
-
-Run with: python -m mcp_bridge.server
+Optimized for extremely fast startup and protocol compliance:
+- Lazy-loads all tool implementations and dependencies.
+- Minimal top-level imports.
+- Robust crash logging to stderr and /tmp.
 """
 
+import sys
+import os
 import asyncio
 import logging
+import time
 from typing import Any
 
 from mcp.server import Server
@@ -25,799 +25,408 @@ from mcp.types import (
     GetPromptResult,
 )
 
-from .auth.token_store import TokenStore
-from .tools.model_invoke import invoke_gemini, invoke_openai
-from .tools.code_search import lsp_diagnostics, ast_grep_search, ast_grep_replace, grep_search, glob_files
-from .tools.session_manager import list_sessions, read_session, search_sessions, get_session_info
-from .tools.skill_loader import list_skills, get_skill, create_skill
-from .tools.background_tasks import task_spawn, task_status, task_list
-from .tools.agent_manager import agent_spawn, agent_output, agent_cancel, agent_list, agent_progress
-from .tools.project_context import get_project_context, get_system_health
-from .tools.lsp import (
-    lsp_hover,
-    lsp_goto_definition,
-    lsp_find_references,
-    lsp_document_symbols,
-    lsp_workspace_symbols,
-    lsp_prepare_rename,
-    lsp_rename,
-    lsp_code_actions,
-    lsp_servers,
-)
-from .prompts import stravinsky, delphi, dewey, explore, frontend, document_writer, multimodal
+from . import __version__
+
+# --- CRITICAL: PROTOCOL HYGIENE ---
 
-# Configure logging
-logging.basicConfig(level=logging.INFO)
+# Configure logging to stderr explicitly to avoid protocol corruption
+logging.basicConfig(
+    level=logging.INFO, format="%(levelname)s:%(name)s:%(message)s", stream=sys.stderr
+)
 logger = logging.getLogger(__name__)
 
-# Initialize the MCP server
-server = Server("stravinsky")
 
-# Token store for OAuth tokens
-token_store = TokenStore()
+# Pre-async crash logger
+def install_emergency_logger():
+    def handle_exception(exc_type, exc_value, exc_traceback):
+        if issubclass(exc_type, KeyboardInterrupt):
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+        logger.critical("FATAL PRE-STARTUP ERROR", exc_info=(exc_type, exc_value, exc_traceback))
+        try:
+            with open("/tmp/stravinsky_crash.log", "a") as f:
+                import traceback
+
+                f.write(f"\n--- CRASH AT {time.ctime()} ---\n")
+                traceback.print_exception(exc_type, exc_value, exc_traceback, file=f)
+        except:
+            pass
+
+    sys.excepthook = handle_exception
+
+
+install_emergency_logger()
+
+# --- SERVER INITIALIZATION ---
+
+server = Server("stravinsky", version=__version__)
+
+# Lazy-loaded systems
+_token_store = None
+_hook_manager = None
+
+
+def get_token_store():
+    global _token_store
+    if _token_store is None:
+        from .auth.token_store import TokenStore
+
+        _token_store = TokenStore()
+    return _token_store
+
+
+def get_hook_manager_lazy():
+    global _hook_manager
+    if _hook_manager is None:
+        from .hooks.manager import get_hook_manager
+
+        _hook_manager = get_hook_manager()
+    return _hook_manager
+
+
+# --- MCP INTERFACE ---
 
 
 @server.list_tools()
 async def list_tools() -> list[Tool]:
-    """List all available tools."""
-    tools = [
-        Tool(
-            name="invoke_gemini",
-            description=(
-                "Invoke a Gemini model with the given prompt. "
-                "Requires OAuth authentication with Google. "
-                "Use this for tasks requiring Gemini's capabilities like "
-                "frontend UI generation, documentation writing, or multimodal analysis."
-            ),
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "prompt": {
-                        "type": "string",
-                        "description": "The prompt to send to Gemini",
-                    },
-                    "model": {
-                        "type": "string",
-                        "description": "Gemini model to use (default: gemini-3-flash)",
-                        "default": "gemini-3-flash",
-                    },
-                    "temperature": {
-                        "type": "number",
-                        "description": "Sampling temperature (0.0-2.0)",
-                        "default": 0.7,
-                    },
-                    "max_tokens": {
-                        "type": "integer",
-                        "description": "Maximum tokens in response",
-                        "default": 4096,
-                    },
-                    "thinking_budget": {
-                        "type": "integer",
-                        "description": "Tokens reserved for internal reasoning (if model supports it)",
-                        "default": 0,
-                    },
-                },
-                "required": ["prompt"],
-            },
-        ),
-        Tool(
-            name="invoke_openai",
-            description=(
-                "Invoke an OpenAI model with the given prompt. "
-                "Requires OAuth authentication with OpenAI. "
-                "Use this for tasks requiring GPT capabilities like "
-                "strategic advice, code review, or complex reasoning."
-            ),
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "prompt": {
-                        "type": "string",
-                        "description": "The prompt to send to OpenAI",
-                    },
-                    "model": {
-                        "type": "string",
-                        "description": "OpenAI model to use (default: gpt-5.2)",
-                        "default": "gpt-5.2",
-                    },
-                    "temperature": {
-                        "type": "number",
-                        "description": "Sampling temperature (0.0-2.0)",
-                        "default": 0.7,
-                    },
-                    "max_tokens": {
-                        "type": "integer",
-                        "description": "Maximum tokens in response",
-                        "default": 4096,
-                    },
-                    "thinking_budget": {
-                        "type": "integer",
-                        "description": "Tokens reserved for internal reasoning (e.g. gpt-5.2 / o1 / o3)",
-                        "default": 0,
-                    },
-                },
-                "required": ["prompt"],
-            },
-        ),
-        Tool(
-            name="get_project_context",
-            description="Summarize project environment including Git status, local rules (.claude/rules/), and pending todos.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "project_path": {"type": "string", "description": "Path to the project root"},
-                },
-            },
-        ),
-        Tool(
-            name="get_system_health",
-            description="Comprehensive check of system dependencies (rg, fd, sg, etc.) and authentication status.",
-            inputSchema={
-                "type": "object",
-                "properties": {},
-            },
-        ),
-        Tool(
-            name="lsp_diagnostics",
-            description="Get diagnostics (errors, warnings) for a file using language tools (tsc, ruff).",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Path to file to analyze"},
-                    "severity": {"type": "string", "description": "Filter: error, warning, all", "default": "all"},
-                },
-                "required": ["file_path"],
-            },
-        ),
-        Tool(
-            name="ast_grep_search",
-            description="Search codebase using ast-grep for structural AST patterns.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "pattern": {"type": "string", "description": "ast-grep pattern"},
-                    "directory": {"type": "string", "description": "Directory to search", "default": "."},
-                    "language": {"type": "string", "description": "Filter by language"},
-                },
-                "required": ["pattern"],
-            },
-        ),
-        Tool(
-            name="grep_search",
-            description="Fast text search using ripgrep.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "pattern": {"type": "string", "description": "Search pattern (regex)"},
-                    "directory": {"type": "string", "description": "Directory to search", "default": "."},
-                    "file_pattern": {"type": "string", "description": "Glob filter (e.g. *.py)"},
-                },
-                "required": ["pattern"],
-            },
-        ),
-        Tool(
-            name="glob_files",
-            description="Find files matching a glob pattern.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "pattern": {"type": "string", "description": "Glob pattern (e.g. **/*.py)"},
-                    "directory": {"type": "string", "description": "Base directory", "default": "."},
-                },
-                "required": ["pattern"],
-            },
-        ),
-        Tool(
-            name="session_list",
-            description="List Claude Code sessions with optional filtering.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "project_path": {"type": "string", "description": "Filter by project path"},
-                    "limit": {"type": "integer", "description": "Max sessions", "default": 20},
-                },
-            },
-        ),
-        Tool(
-            name="session_read",
-            description="Read messages from a Claude Code session.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "session_id": {"type": "string", "description": "Session ID"},
-                    "limit": {"type": "integer", "description": "Max messages"},
-                },
-                "required": ["session_id"],
-            },
-        ),
-        Tool(
-            name="session_search",
-            description="Search across Claude Code session messages.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                    "session_id": {"type": "string", "description": "Search in specific session"},
-                    "limit": {"type": "integer", "description": "Max results", "default": 20},
-                },
-                "required": ["query"],
-            },
-        ),
-        Tool(
-            name="skill_list",
-            description="List available Claude Code skills/commands from .claude/commands/.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "project_path": {"type": "string", "description": "Project directory"},
-                },
-            },
-        ),
-        Tool(
-            name="skill_get",
-            description="Get the content of a specific skill/command.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "name": {"type": "string", "description": "Skill name"},
-                    "project_path": {"type": "string", "description": "Project directory"},
-                },
-                "required": ["name"],
-            },
-        ),
-        Tool(
-            name="task_spawn",
-            description=(
-                "Spawn a background task to execute a prompt asynchronously. "
-                "Returns a Task ID. Best for deep research or parallel processing."
-            ),
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "prompt": {"type": "string", "description": "The prompt for the background agent"},
-                    "model": {
-                        "type": "string", 
-                        "description": "Model to use (gemini-3-flash or gpt-5.2)",
-                        "default": "gemini-3-flash"
-                    },
-                },
-                "required": ["prompt"],
-            },
-        ),
-        Tool(
-            name="task_status",
-            description="Check the status and retrieve results of a background task.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "task_id": {"type": "string", "description": "The ID of the task to check"},
-                },
-                "required": ["task_id"],
-            },
-        ),
-        Tool(
-            name="task_list",
-            description="List all active and recent background tasks.",
-            inputSchema={
-                "type": "object",
-                "properties": {},
-            },
-        ),
-        # New Agent Tools with Full Tool Access
-        Tool(
-            name="agent_spawn",
-            description=(
-                "Spawn a background agent. Uses Gemini by default for fast execution. "
-                "Set model='claude' to use Claude Code CLI with full tool access."
-            ),
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "prompt": {"type": "string", "description": "The task for the agent to perform"},
-                    "agent_type": {
-                        "type": "string",
-                        "description": "Agent type: explore, dewey, frontend, delphi",
-                        "default": "explore",
-                    },
-                    "description": {"type": "string", "description": "Short description for status display"},
-                    "model": {
-                        "type": "string",
-                        "description": "Model: gemini-3-flash (default) or claude",
-                        "default": "gemini-3-flash",
-                    },
-                    "thinking_budget": {
-                        "type": "integer",
-                        "description": "Tokens reserved for internal reasoning (if model supports it)",
-                        "default": 0,
-                    },
-                },
-                "required": ["prompt"],
-            },
-        ),
-        Tool(
-            name="agent_output",
-            description="Get output from a background agent. Use block=true to wait for completion.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "task_id": {"type": "string", "description": "The agent task ID"},
-                    "block": {"type": "boolean", "description": "Wait for completion", "default": False},
-                },
-                "required": ["task_id"],
-            },
-        ),
-        Tool(
-            name="agent_cancel",
-            description="Cancel a running background agent.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "task_id": {"type": "string", "description": "The agent task ID to cancel"},
-                },
-                "required": ["task_id"],
-            },
-        ),
-        Tool(
-            name="agent_list",
-            description="List all background agent tasks with their status.",
-            inputSchema={
-                "type": "object",
-                "properties": {},
-            },
-        ),
-        Tool(
-            name="agent_progress",
-            description="Get real-time progress from a running background agent. Shows recent output lines to monitor what the agent is doing.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "task_id": {"type": "string", "description": "The agent task ID"},
-                    "lines": {"type": "integer", "description": "Number of recent lines to show", "default": 20},
-                },
-                "required": ["task_id"],
-            },
-        ),
-        # LSP Tools
-        Tool(
-            name="lsp_hover",
-            description="Get type info, documentation, and signature at a position in a file.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                },
-                "required": ["file_path", "line", "character"],
-            },
-        ),
-        Tool(
-            name="lsp_goto_definition",
-            description="Find where a symbol is defined. Jump to symbol definition.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                },
-                "required": ["file_path", "line", "character"],
-            },
-        ),
-        Tool(
-            name="lsp_find_references",
-            description="Find all references to a symbol across the workspace.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                    "include_declaration": {"type": "boolean", "description": "Include the declaration itself", "default": True},
-                },
-                "required": ["file_path", "line", "character"],
-            },
-        ),
-        Tool(
-            name="lsp_document_symbols",
-            description="Get hierarchical outline of all symbols (functions, classes, methods) in a file.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                },
-                "required": ["file_path"],
-            },
-        ),
-        Tool(
-            name="lsp_workspace_symbols",
-            description="Search for symbols by name across the entire workspace.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Symbol name to search for (fuzzy match)"},
-                    "directory": {"type": "string", "description": "Workspace directory", "default": "."},
-                },
-                "required": ["query"],
-            },
-        ),
-        Tool(
-            name="lsp_prepare_rename",
-            description="Check if a symbol at position can be renamed. Use before lsp_rename.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                },
-                "required": ["file_path", "line", "character"],
-            },
-        ),
-        Tool(
-            name="lsp_rename",
-            description="Rename a symbol across the workspace. Use lsp_prepare_rename first to validate.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                    "new_name": {"type": "string", "description": "New name for the symbol"},
-                    "dry_run": {"type": "boolean", "description": "Preview changes without applying", "default": True},
-                },
-                "required": ["file_path", "line", "character", "new_name"],
-            },
-        ),
-        Tool(
-            name="lsp_code_actions",
-            description="Get available quick fixes and refactorings at a position.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "file_path": {"type": "string", "description": "Absolute path to the file"},
-                    "line": {"type": "integer", "description": "Line number (1-indexed)"},
-                    "character": {"type": "integer", "description": "Character position (0-indexed)"},
-                },
-                "required": ["file_path", "line", "character"],
-            },
-        ),
-        Tool(
-            name="lsp_servers",
-            description="List available LSP servers and their installation status.",
-            inputSchema={
-                "type": "object",
-                "properties": {},
-            },
-        ),
-        Tool(
-            name="ast_grep_replace",
-            description="Replace code patterns using ast-grep's AST-aware replacement. More reliable than text-based replace for refactoring.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "pattern": {"type": "string", "description": "ast-grep pattern to search (e.g., 'console.log($A)')"},
-                    "replacement": {"type": "string", "description": "Replacement pattern (e.g., 'logger.debug($A)')"},
-                    "directory": {"type": "string", "description": "Directory to search in", "default": "."},
-                    "language": {"type": "string", "description": "Filter by language (typescript, python, etc.)"},
-                    "dry_run": {"type": "boolean", "description": "Preview changes without applying", "default": True},
-                },
-                "required": ["pattern", "replacement"],
-            },
-        ),
-    ]
-    return tools
+    """List available tools (metadata only)."""
+    from .server_tools import get_tool_definitions
+
+    return get_tool_definitions()
 
 
 @server.call_tool()
 async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
-    """Handle tool invocations."""
-    logger.info(f"Tool called: {name} with args: {arguments}")
+    """Handle tool calls with deep lazy loading of implementations."""
+    logger.info(f"Tool call: {name}")
+    hook_manager = get_hook_manager_lazy()
+    token_store = get_token_store()
 
     try:
+        # Pre-tool call hooks orchestration
+        arguments = await hook_manager.execute_pre_tool_call(name, arguments)
+
+        result_content = None
+
+        # --- MODEL DISPATCH ---
         if name == "invoke_gemini":
-            result = await invoke_gemini(
+            from .tools.model_invoke import invoke_gemini
+
+            result_content = await invoke_gemini(
                 token_store=token_store,
                 prompt=arguments["prompt"],
-                model=arguments.get("model", "gemini-3-flash"),
+                model=arguments.get("model", "gemini-2.0-flash-exp"),
                 temperature=arguments.get("temperature", 0.7),
-                max_tokens=arguments.get("max_tokens", 4096),
+                max_tokens=arguments.get("max_tokens", 8192),
                 thinking_budget=arguments.get("thinking_budget", 0),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "invoke_openai":
-            result = await invoke_openai(
+            from .tools.model_invoke import invoke_openai
+
+            result_content = await invoke_openai(
                 token_store=token_store,
                 prompt=arguments["prompt"],
-                model=arguments.get("model", "gpt-5.2"),
+                model=arguments.get("model", "gpt-4o"),
                 temperature=arguments.get("temperature", 0.7),
                 max_tokens=arguments.get("max_tokens", 4096),
                 thinking_budget=arguments.get("thinking_budget", 0),
             )
-            return [TextContent(type="text", text=result)]
 
+        # --- CONTEXT DISPATCH ---
         elif name == "get_project_context":
-            result = await get_project_context(
-                project_path=arguments.get("project_path"),
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.project_context import get_project_context
+
+            result_content = await get_project_context(project_path=arguments.get("project_path"))
 
         elif name == "get_system_health":
-            result = await get_system_health()
-            return [TextContent(type="text", text=result)]
+            from .tools.project_context import get_system_health
 
-        elif name == "lsp_diagnostics":
-            result = await lsp_diagnostics(
-                file_path=arguments["file_path"],
-                severity=arguments.get("severity", "all"),
+            result_content = await get_system_health()
+
+        # --- SEARCH DISPATCH ---
+        elif name == "grep_search":
+            from .tools.code_search import grep_search
+
+            result_content = await grep_search(
+                pattern=arguments["pattern"],
+                directory=arguments.get("directory", "."),
+                file_pattern=arguments.get("file_pattern", ""),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "ast_grep_search":
-            result = await ast_grep_search(
+            from .tools.code_search import ast_grep_search
+
+            result_content = await ast_grep_search(
                 pattern=arguments["pattern"],
                 directory=arguments.get("directory", "."),
                 language=arguments.get("language", ""),
             )
-            return [TextContent(type="text", text=result)]
 
-        elif name == "grep_search":
-            result = await grep_search(
+        elif name == "ast_grep_replace":
+            from .tools.code_search import ast_grep_replace
+
+            result_content = await ast_grep_replace(
                 pattern=arguments["pattern"],
+                replacement=arguments["replacement"],
                 directory=arguments.get("directory", "."),
-                file_pattern=arguments.get("file_pattern", ""),
+                language=arguments.get("language", ""),
+                dry_run=arguments.get("dry_run", True),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "glob_files":
-            result = await glob_files(
+            from .tools.code_search import glob_files
+
+            result_content = await glob_files(
                 pattern=arguments["pattern"],
                 directory=arguments.get("directory", "."),
             )
-            return [TextContent(type="text", text=result)]
 
+        # --- SESSION DISPATCH ---
         elif name == "session_list":
-            result = list_sessions(
+            from .tools.session_manager import list_sessions
+
+            result_content = list_sessions(
                 project_path=arguments.get("project_path"),
                 limit=arguments.get("limit", 20),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "session_read":
-            result = read_session(
+            from .tools.session_manager import read_session
+
+            result_content = read_session(
                 session_id=arguments["session_id"],
                 limit=arguments.get("limit"),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "session_search":
-            result = search_sessions(
+            from .tools.session_manager import search_sessions
+
+            result_content = search_sessions(
                 query=arguments["query"],
                 session_id=arguments.get("session_id"),
                 limit=arguments.get("limit", 20),
             )
-            return [TextContent(type="text", text=result)]
 
+        # --- SKILL DISPATCH ---
         elif name == "skill_list":
-            result = list_skills(
-                project_path=arguments.get("project_path"),
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.skill_loader import list_skills
+
+            result_content = list_skills(project_path=arguments.get("project_path"))
 
         elif name == "skill_get":
-            result = get_skill(
+            from .tools.skill_loader import get_skill
+
+            result_content = get_skill(
                 name=arguments["name"],
                 project_path=arguments.get("project_path"),
             )
-            return [TextContent(type="text", text=result)]
 
-        elif name == "task_spawn":
-            result = await task_spawn(
-                prompt=arguments["prompt"],
-                model=arguments.get("model", "gemini-3-flash"),
-            )
-            return [TextContent(type="text", text=result)]
-
-        elif name == "task_status":
-            result = await task_status(
-                task_id=arguments["task_id"],
-            )
-            return [TextContent(type="text", text=result)]
-
-        elif name == "task_list":
-            result = await task_list()
-            return [TextContent(type="text", text=result)]
-
-        # Agent tools with full tool access
+        elif name == "stravinsky_version":
+            from . import __version__
+            import sys
+            import os
+
+            result_content = [
+                TextContent(
+                    type="text",
+                    text=f"Stravinsky Bridge v{__version__}\n"
+                    f"Python: {sys.version.split()[0]}\n"
+                    f"Platform: {sys.platform}\n"
+                    f"CWD: {os.getcwd()}\n"
+                    f"CLI: {os.environ.get('CLAUDE_CLI', '/opt/homebrew/bin/claude')}",
+                )
+            ]
+
+        elif name == "system_restart":
+            # Schedule a restart. We can't exit immediately or MCP will error on the reply.
+            # We'll use a small delay.
+            async def restart_soon():
+                await asyncio.sleep(1)
+                os._exit(0)  # Immediate exit
+
+            asyncio.create_task(restart_soon())
+            result_content = [
+                TextContent(
+                    type="text",
+                    text="🚀 Restarting Stravinsky Bridge... This process will exit and Claude Code will automatically respawn it. Please wait a few seconds before calling tools again.",
+                )
+            ]
+
+        # --- AGENT DISPATCH ---
         elif name == "agent_spawn":
-            result = await agent_spawn(
-                prompt=arguments["prompt"],
-                agent_type=arguments.get("agent_type", "explore"),
-                description=arguments.get("description", ""),
-                model=arguments.get("model", "gemini-3-flash"),
-                thinking_budget=arguments.get("thinking_budget", 0),
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.agent_manager import agent_spawn
+
+            result_content = await agent_spawn(**arguments)
 
         elif name == "agent_output":
-            result = await agent_output(
+            from .tools.agent_manager import agent_output
+
+            result_content = await agent_output(
                 task_id=arguments["task_id"],
                 block=arguments.get("block", False),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "agent_cancel":
-            result = await agent_cancel(
-                task_id=arguments["task_id"],
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.agent_manager import agent_cancel
+
+            result_content = await agent_cancel(task_id=arguments["task_id"])
 
         elif name == "agent_list":
-            result = await agent_list()
-            return [TextContent(type="text", text=result)]
+            from .tools.agent_manager import agent_list
+
+            result_content = await agent_list()
 
         elif name == "agent_progress":
-            result = await agent_progress(
+            from .tools.agent_manager import agent_progress
+
+            result_content = await agent_progress(
                 task_id=arguments["task_id"],
                 lines=arguments.get("lines", 20),
             )
-            return [TextContent(type="text", text=result)]
 
-        # LSP Tools
+        elif name == "agent_retry":
+            from .tools.agent_manager import agent_retry
+
+            result_content = await agent_retry(
+                task_id=arguments["task_id"],
+                new_prompt=arguments.get("new_prompt"),
+                new_timeout=arguments.get("new_timeout"),
+            )
+
+        # --- BACKGROUND TASK DISPATCH ---
+        elif name == "task_spawn":
+            from .tools.background_tasks import task_spawn
+
+            result_content = await task_spawn(
+                prompt=arguments["prompt"],
+                model=arguments.get("model", "gemini-3-flash"),
+            )
+
+        elif name == "task_status":
+            from .tools.background_tasks import task_status
+
+            result_content = await task_status(task_id=arguments["task_id"])
+
+        elif name == "task_list":
+            from .tools.background_tasks import task_list
+
+            result_content = await task_list()
+
+        # --- LSP DISPATCH ---
         elif name == "lsp_hover":
-            result = await lsp_hover(
+            from .tools.lsp import lsp_hover
+
+            result_content = await lsp_hover(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_goto_definition":
-            result = await lsp_goto_definition(
+            from .tools.lsp import lsp_goto_definition
+
+            result_content = await lsp_goto_definition(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_find_references":
-            result = await lsp_find_references(
+            from .tools.lsp import lsp_find_references
+
+            result_content = await lsp_find_references(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
                 include_declaration=arguments.get("include_declaration", True),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_document_symbols":
-            result = await lsp_document_symbols(
-                file_path=arguments["file_path"],
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.lsp import lsp_document_symbols
+
+            result_content = await lsp_document_symbols(file_path=arguments["file_path"])
 
         elif name == "lsp_workspace_symbols":
-            result = await lsp_workspace_symbols(
-                query=arguments["query"],
-                directory=arguments.get("directory", "."),
-            )
-            return [TextContent(type="text", text=result)]
+            from .tools.lsp import lsp_workspace_symbols
+
+            result_content = await lsp_workspace_symbols(query=arguments["query"])
 
         elif name == "lsp_prepare_rename":
-            result = await lsp_prepare_rename(
+            from .tools.lsp import lsp_prepare_rename
+
+            result_content = await lsp_prepare_rename(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_rename":
-            result = await lsp_rename(
+            from .tools.lsp import lsp_rename
+
+            result_content = await lsp_rename(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
                 new_name=arguments["new_name"],
-                dry_run=arguments.get("dry_run", True),
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_code_actions":
-            result = await lsp_code_actions(
+            from .tools.lsp import lsp_code_actions
+
+            result_content = await lsp_code_actions(
                 file_path=arguments["file_path"],
                 line=arguments["line"],
                 character=arguments["character"],
             )
-            return [TextContent(type="text", text=result)]
 
         elif name == "lsp_servers":
-            result = await lsp_servers()
-            return [TextContent(type="text", text=result)]
+            from .tools.lsp import lsp_servers
 
-        elif name == "ast_grep_replace":
-            result = await ast_grep_replace(
-                pattern=arguments["pattern"],
-                replacement=arguments["replacement"],
-                directory=arguments.get("directory", "."),
-                language=arguments.get("language", ""),
-                dry_run=arguments.get("dry_run", True),
-            )
-            return [TextContent(type="text", text=result)]
+            result_content = await lsp_servers()
 
         else:
-            return [TextContent(type="text", text=f"Unknown tool: {name}")]
+            result_content = f"Unknown tool: {name}"
+
+        # Post-tool call hooks orchestration
+        if result_content is not None:
+            if (
+                isinstance(result_content, list)
+                and len(result_content) > 0
+                and hasattr(result_content[0], "text")
+            ):
+                processed_text = await hook_manager.execute_post_tool_call(
+                    name, arguments, result_content[0].text
+                )
+                result_content[0].text = processed_text
+            elif isinstance(result_content, str):
+                result_content = await hook_manager.execute_post_tool_call(
+                    name, arguments, result_content
+                )
+
+        # Format final return as List[TextContent]
+        if isinstance(result_content, list):
+            return result_content
+        return [TextContent(type="text", text=str(result_content))]
 
     except Exception as e:
-        logger.error(f"Error in tool {name}: {e}")
+        logger.error(f"Error calling tool {name}: {e}")
         return [TextContent(type="text", text=f"Error: {str(e)}")]
 
 
 @server.list_prompts()
 async def list_prompts() -> list[Prompt]:
-    """List available agent prompts."""
-    return [
-        Prompt(
-            name="stravinsky",
-            description=(
-                "Stravinsky - Powerful AI orchestrator. "
-                "Plans obsessively with todos, assesses search complexity before "
-                "exploration, delegates strategically to specialized agents."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="delphi",
-            description=(
-                "Delphi - Strategic advisor using GPT for debugging, "
-                "architecture review, and complex problem solving."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="dewey",
-            description=(
-                "Dewey - Documentation and GitHub research specialist. "
-                "Finds implementation examples, official docs, and code patterns."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="explore",
-            description=(
-                "Explore - Fast codebase search specialist. "
-                "Answers 'Where is X?', finds files and code patterns."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="frontend",
-            description=(
-                "Frontend UI/UX Engineer - Designer-turned-developer for stunning visuals. "
-                "Excels at styling, layout, animation, typography."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="document_writer",
-            description=(
-                "Document Writer - Technical documentation specialist. "
-                "README files, API docs, architecture docs, user guides."
-            ),
-            arguments=[],
-        ),
-        Prompt(
-            name="multimodal",
-            description=(
-                "Multimodal Looker - Visual content analysis. "
-                "PDFs, images, diagrams - extracts and interprets visual data."
-            ),
-            arguments=[],
-        ),
-    ]
+    """List available prompts (metadata only)."""
+    from .server_tools import get_prompt_definitions
+
+    return get_prompt_definitions()
 
 
 @server.get_prompt()
 async def get_prompt(name: str, arguments: dict[str, str] | None) -> GetPromptResult:
-    """Get a specific agent prompt."""
+    """Get a specific prompt content (lazy loaded)."""
+    from .prompts import stravinsky, delphi, dewey, explore, frontend, document_writer, multimodal
+
     prompts_map = {
         "stravinsky": ("Stravinsky orchestrator system prompt", stravinsky.get_stravinsky_prompt),
         "delphi": ("Delphi advisor system prompt", delphi.get_delphi_prompt),
@@ -827,13 +436,13 @@ async def get_prompt(name: str, arguments: dict[str, str] | None) -> GetPromptRe
         "document_writer": ("Document Writer prompt", document_writer.get_document_writer_prompt),
         "multimodal": ("Multimodal Looker prompt", multimodal.get_multimodal_prompt),
     }
-    
+
     if name not in prompts_map:
         raise ValueError(f"Unknown prompt: {name}")
-    
+
     description, get_prompt_fn = prompts_map[name]
     prompt_text = get_prompt_fn()
-    
+
     return GetPromptResult(
         description=description,
         messages=[
@@ -846,20 +455,234 @@ async def get_prompt(name: str, arguments: dict[str, str] | None) -> GetPromptRe
 
 
 async def async_main():
-    """Async entry point for the MCP server."""
-    logger.info("Starting Stravinsky MCP Bridge Server...")
+    """Server execution entry point."""
+    # Initialize hooks at runtime, not import time
+    try:
+        from .hooks import initialize_hooks
+
+        initialize_hooks()
+    except Exception as e:
+        logger.error(f"Failed to initialize hooks: {e}")
 
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(
-            read_stream,
-            write_stream,
-            server.create_initialization_options(),
-        )
+    try:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+    except Exception as e:
+        logger.critical("Server process crashed in async_main", exc_info=True)
+        sys.exit(1)
 
 
 def main():
-    """Synchronous main entry point for uvx/CLI."""
-    asyncio.run(async_main())
+    """Synchronous entry point with CLI arg handling."""
+    import argparse
+    import sys
+    from .tools.agent_manager import get_manager
+    from .auth.token_store import TokenStore
+
+    parser = argparse.ArgumentParser(
+        description="Stravinsky MCP Bridge - Multi-model AI orchestration for Claude Code. "
+        "Spawns background agents with full tool access via Claude CLI.",
+        prog="stravinsky",
+        epilog="Examples:\n"
+        "  stravinsky              # Start MCP server (default)\n"
+        "  stravinsky list         # Show all background agents\n"
+        "  stravinsky status       # Check auth status\n"
+        "  stravinsky stop --clear # Stop agents and clear history\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"stravinsky {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands", metavar="COMMAND")
+
+    # list command
+    subparsers.add_parser(
+        "list",
+        help="List all background agent tasks",
+        description="Shows status, ID, type, and description of all spawned agents.",
+    )
+
+    # status command
+    subparsers.add_parser(
+        "status",
+        help="Show authentication status for all providers",
+        description="Displays OAuth authentication status and token expiration for Gemini and OpenAI.",
+    )
+
+    # start command (explicit server start)
+    subparsers.add_parser(
+        "start",
+        help="Explicitly start the MCP server (STDIO transport)",
+        description="Starts the MCP server for communication with Claude Code. Usually started automatically.",
+    )
+
+    # stop command (stop all agents)
+    stop_parser = subparsers.add_parser(
+        "stop",
+        help="Stop all running background agents",
+        description="Terminates all active agent processes. Use --clear to also remove history.",
+    )
+    stop_parser.add_argument(
+        "--clear",
+        action="store_true",
+        help="Also clear agent history from .stravinsky/agents.json",
+    )
+
+    # auth command (authentication)
+    auth_parser = subparsers.add_parser(
+        "auth",
+        help="Authentication commands (login/logout/refresh/status)",
+        description="Manage OAuth authentication for Gemini and OpenAI providers.",
+    )
+    auth_subparsers = auth_parser.add_subparsers(
+        dest="auth_command", help="Auth subcommands", metavar="SUBCOMMAND"
+    )
+
+    # auth login
+    login_parser = auth_subparsers.add_parser(
+        "login",
+        help="Login to a provider via browser OAuth",
+        description="Opens browser for OAuth authentication with the specified provider.",
+    )
+    login_parser.add_argument(
+        "provider",
+        choices=["gemini", "openai"],
+        metavar="PROVIDER",
+        help="Provider to authenticate with: gemini (Google) or openai (ChatGPT Plus/Pro)",
+    )
+
+    # auth logout
+    logout_parser = auth_subparsers.add_parser(
+        "logout",
+        help="Remove stored OAuth credentials",
+        description="Deletes stored access and refresh tokens for the specified provider.",
+    )
+    logout_parser.add_argument(
+        "provider",
+        choices=["gemini", "openai"],
+        metavar="PROVIDER",
+        help="Provider to logout from: gemini or openai",
+    )
+
+    # auth status
+    auth_subparsers.add_parser(
+        "status",
+        help="Show authentication status for all providers",
+        description="Displays authentication status and token expiration for Gemini and OpenAI.",
+    )
+
+    # auth refresh
+    refresh_parser = auth_subparsers.add_parser(
+        "refresh",
+        help="Manually refresh access token",
+        description="Force-refresh the access token using the stored refresh token.",
+    )
+    refresh_parser.add_argument(
+        "provider",
+        choices=["gemini", "openai"],
+        metavar="PROVIDER",
+        help="Provider to refresh token for: gemini or openai",
+    )
+
+    # auth init
+    auth_subparsers.add_parser(
+        "init",
+        help="Bootstrap current repository for Stravinsky",
+        description="Creates .stravinsky/ directory structure and copies default configuration files.",
+    )
+
+    # Check for CLI flags
+    args, unknown = parser.parse_known_args()
+
+    if args.command == "list":
+        # Run agent_list logic
+        manager = get_manager()
+        tasks = manager.list_tasks()
+        if not tasks:
+            print("No background agent tasks found.")
+            return 0
+
+        print("\nStravinsky Background Agents:")
+        print("-" * 100)
+        print(f"{'STATUS':10} | {'ID':15} | {'TYPE':10} | {'STARTED':20} | DESCRIPTION")
+        print("-" * 100)
+        for t in sorted(tasks, key=lambda x: x.get("created_at", ""), reverse=True):
+            status = t["status"]
+            task_id = t["id"]
+            agent = t["agent_type"]
+            created = t.get("created_at", "")[:19].replace("T", " ")  # Format datetime
+            desc = t.get("description", t.get("prompt", "")[:40])[:40]
+            print(f"{status.upper():10} | {task_id:15} | {agent:10} | {created:20} | {desc}")
+
+            # Show error for failed agents
+            if status == "failed" and t.get("error"):
+                error_msg = t["error"][:100].replace("\n", " ")
+                print(f"           └─ ERROR: {error_msg}")
+        print("-" * 100)
+        return 0
+
+    elif args.command == "status":
+        from .auth.cli import cmd_status
+
+        return cmd_status(TokenStore())
+
+    elif args.command == "start":
+        asyncio.run(async_main())
+        return 0
+
+    elif args.command == "stop":
+        manager = get_manager()
+        count = manager.stop_all(clear_history=getattr(args, "clear", False))
+        if getattr(args, "clear", False):
+            print(f"Cleared {count} agent task(s) from history.")
+        else:
+            print(f"Stopped {count} running agent(s).")
+        return 0
+
+    elif args.command == "auth":
+        auth_cmd = getattr(args, "auth_command", None)
+        token_store = get_token_store()
+
+        if auth_cmd == "login":
+            from .auth.cli import cmd_login
+
+            return cmd_login(args.provider, token_store)
+
+        elif auth_cmd == "logout":
+            from .auth.cli import cmd_logout
+
+            return cmd_logout(args.provider, token_store)
+
+        elif auth_cmd == "status":
+            from .auth.cli import cmd_status
+
+            return cmd_status(token_store)
+
+        elif auth_cmd == "refresh":
+            from .auth.cli import cmd_refresh
+
+            return cmd_refresh(args.provider, token_store)
+
+        elif auth_cmd == "init":
+            from .tools.init import bootstrap_repo
+
+            print(bootstrap_repo())
+            return 0
+
+        else:
+            auth_parser.print_help()
+            return 0
+
+    else:
+        # Default behavior: start server (fallback for MCP runners and unknown args)
+        # This ensures that flags like --transport stdio don't cause an exit
+        if unknown:
+            logger.info(f"Starting MCP server with unknown arguments: {unknown}")
+        asyncio.run(async_main())
+        return 0
 
 
 if __name__ == "__main__":