gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/llm/resolver.py

@@ -18,7 +18,8 @@ from typing import TYPE_CHECKING, Literal
 from gobby.llm.executor import AgentExecutor
 
 if TYPE_CHECKING:
-    from gobby.config.app import DaemonConfig, LLMProvidersConfig
+    from gobby.config.app import DaemonConfig
+    from gobby.config.llm_providers import LLMProvidersConfig
     from gobby.workflows.definitions import WorkflowDefinition
 
 logger = logging.getLogger(__name__)
@@ -259,8 +260,13 @@ def create_executor(
     """
     Create an AgentExecutor for the given provider.
 
+    Routing strategy:
+    - api_key and adc auth modes: Route to LiteLLMExecutor for unified cost tracking
+    - subscription mode (Claude): Route to ClaudeExecutor (Claude Agent SDK)
+    - cli mode (Codex): Route to CodexExecutor (Codex CLI subprocess)
+
     Args:
-        provider: Provider name (claude, gemini, litellm).
+        provider: Provider name (claude, gemini, litellm, codex).
         config: Optional daemon config for provider settings.
         model: Optional model override.
 
@@ -279,19 +285,40 @@ def create_executor(
     if config and config.llm_providers:
         provider_config = getattr(config.llm_providers, provider, None)
 
+    # Determine auth_mode from config
+    auth_mode = "api_key"  # Default
+    if provider_config:
+        auth_mode = getattr(provider_config, "auth_mode", "api_key") or "api_key"
+
     try:
-        if provider == "claude":
+        # Route based on auth_mode:
+        # - subscription (Claude) -> ClaudeExecutor
+        # - cli (Codex) -> CodexExecutor
+        # - api_key/adc (all providers) -> LiteLLMExecutor
+
+        if provider == "claude" and auth_mode == "subscription":
+            # Subscription mode requires Claude Agent SDK
             return _create_claude_executor(provider_config, model)
-        elif provider == "gemini":
-            return _create_gemini_executor(provider_config, model)
+
+        elif provider == "codex" and auth_mode in ("subscription", "cli"):
+            # CLI mode requires Codex CLI subprocess
+            return _create_codex_executor(provider_config, model, auth_mode)
+
         elif provider == "litellm":
+            # Direct LiteLLM usage
             return _create_litellm_executor(provider_config, config, model)
-        elif provider == "codex":
-            return _create_codex_executor(provider_config, model)
+
+        elif auth_mode in ("api_key", "adc"):
+            # Route all api_key and adc modes through LiteLLM for unified cost tracking
+            return _create_litellm_executor_for_provider(
+                provider, auth_mode, provider_config, config, model
+            )
+
         else:
             raise ExecutorCreationError(
                 provider,
-                f"Unknown provider. Supported: {list(SUPPORTED_PROVIDERS)}",
+                f"Unknown provider/auth_mode combination: {provider}/{auth_mode}. "
+                f"Supported: {list(SUPPORTED_PROVIDERS)}",
             )
     except ProviderError:
         raise
@@ -303,15 +330,18 @@ def _create_claude_executor(
     provider_config: "LLMProviderConfig | None",
     model: str | None,
 ) -> AgentExecutor:
-    """Create ClaudeExecutor with appropriate auth mode."""
+    """
+    Create ClaudeExecutor for subscription mode only.
+
+    Note: api_key mode is now routed through LiteLLMExecutor for unified cost tracking.
+    This function should only be called when auth_mode is "subscription".
+    """
     from gobby.llm.claude_executor import ClaudeExecutor
 
-    # Determine auth mode and model from config
-    auth_mode = "api_key"
+    # Subscription mode only - api_key mode routes through LiteLLM
     default_model = "claude-sonnet-4-20250514"
 
     if provider_config:
-        auth_mode = getattr(provider_config, "auth_mode", "api_key") or "api_key"
         # Get first model from comma-separated list if set
         models_str = getattr(provider_config, "models", None)
         if models_str:
@@ -320,46 +350,71 @@ def _create_claude_executor(
                 default_model = models[0]
 
     return ClaudeExecutor(
-        auth_mode=auth_mode,  # type: ignore[arg-type]
+        auth_mode="subscription",
         default_model=model or default_model,
     )
 
 
-def _create_gemini_executor(
+def _create_litellm_executor(
     provider_config: "LLMProviderConfig | None",
+    config: "DaemonConfig | None",
     model: str | None,
 ) -> AgentExecutor:
-    """Create GeminiExecutor with appropriate auth mode."""
-    from gobby.llm.gemini_executor import GeminiExecutor
+    """Create LiteLLMExecutor with API keys from config (direct litellm usage)."""
+    from gobby.llm.litellm_executor import LiteLLMExecutor
 
-    # Determine auth mode and model from config
-    auth_mode = "api_key"
-    default_model = "gemini-2.0-flash"
+    # Determine model and API base from config
+    default_model = "gpt-4o-mini"
+    api_base = None
+    api_keys: dict[str, str] | None = None
 
     if provider_config:
-        auth_mode = getattr(provider_config, "auth_mode", "api_key") or "api_key"
         models_str = getattr(provider_config, "models", None)
         if models_str:
             models = [m.strip() for m in models_str.split(",") if m.strip()]
             if models:
                 default_model = models[0]
+        api_base = getattr(provider_config, "api_base", None)
 
-    return GeminiExecutor(
-        auth_mode=auth_mode,  # type: ignore[arg-type]
+    # Get API keys from llm_providers.api_keys
+    if config and config.llm_providers:
+        api_keys = config.llm_providers.api_keys or None
+
+    return LiteLLMExecutor(
         default_model=model or default_model,
+        api_base=api_base,
+        api_keys=api_keys,
     )
 
 
-def _create_litellm_executor(
+def _create_litellm_executor_for_provider(
+    provider: str,
+    auth_mode: str,
     provider_config: "LLMProviderConfig | None",
     config: "DaemonConfig | None",
     model: str | None,
 ) -> AgentExecutor:
-    """Create LiteLLMExecutor with API keys from config."""
+    """
+    Create LiteLLMExecutor configured for a specific provider's api_key/adc mode.
+
+    This routes provider-specific calls through LiteLLM for unified cost tracking:
+    - Claude (api_key) -> anthropic/model
+    - Gemini (api_key) -> gemini/model
+    - Gemini (adc) -> vertex_ai/model
+    - Codex/OpenAI (api_key) -> model (no prefix)
+    """
     from gobby.llm.litellm_executor import LiteLLMExecutor
 
-    # Determine model and API base from config
-    default_model = "gpt-4o-mini"
+    # Default models per provider
+    default_models = {
+        "claude": "claude-sonnet-4-20250514",
+        "gemini": "gemini-2.0-flash",
+        "codex": "gpt-4o",
+        "openai": "gpt-4o",
+    }
+
+    # Determine model from config
+    default_model = default_models.get(provider, "gpt-4o-mini")
     api_base = None
     api_keys: dict[str, str] | None = None
 
@@ -375,34 +430,42 @@ def _create_litellm_executor(
     if config and config.llm_providers:
         api_keys = config.llm_providers.api_keys or None
 
+    # Cast auth_mode to the expected literal type
+    litellm_auth_mode = auth_mode if auth_mode in ("api_key", "adc") else "api_key"
+
     return LiteLLMExecutor(
         default_model=model or default_model,
         api_base=api_base,
         api_keys=api_keys,
+        provider=provider,  # type: ignore[arg-type]
+        auth_mode=litellm_auth_mode,  # type: ignore[arg-type]
     )
 
 
 def _create_codex_executor(
     provider_config: "LLMProviderConfig | None",
     model: str | None,
+    auth_mode: str = "subscription",
 ) -> AgentExecutor:
     """
-    Create CodexExecutor with appropriate auth mode.
+    Create CodexExecutor for subscription/CLI mode only.
+
+    Note: api_key mode is now routed through LiteLLMExecutor for unified cost tracking.
+    This function should only be called when auth_mode is "subscription" or "cli".
 
-    Codex supports two modes with different capabilities:
-    - api_key: OpenAI API with function calling (full tool injection)
-    - subscription: Codex CLI with ChatGPT subscription (no custom tools)
+    CLI mode uses Codex CLI subprocess - no custom tool injection supported.
 
-    See CodexExecutor docstring for detailed mode differences.
+    Args:
+        provider_config: Provider configuration.
+        model: Optional model override.
+        auth_mode: Authentication mode - "subscription" or "cli".
     """
     from gobby.llm.codex_executor import CodexExecutor
 
-    # Determine auth mode and model from config
-    auth_mode = "api_key"
+    # CLI/subscription mode only - api_key mode routes through LiteLLM
     default_model = "gpt-4o"
 
     if provider_config:
-        auth_mode = getattr(provider_config, "auth_mode", "api_key") or "api_key"
         models_str = getattr(provider_config, "models", None)
         if models_str:
             models = [m.strip() for m in models_str.split(",") if m.strip()]
@@ -417,7 +480,7 @@ def _create_codex_executor(
 
 # Re-export for TYPE_CHECKING
 if TYPE_CHECKING:
-    from gobby.config.app import LLMProviderConfig
+    from gobby.config.llm_providers import LLMProviderConfig
 
 
 class ExecutorRegistry:

gobby/mcp_proxy/importer.py

@@ -5,6 +5,8 @@ import re
 from typing import TYPE_CHECKING, Any
 
 from gobby.config.app import DaemonConfig
+from gobby.config.features import DEFAULT_IMPORT_MCP_SERVER_PROMPT
+from gobby.prompts import PromptLoader
 from gobby.storage.database import DatabaseProtocol
 from gobby.storage.mcp import LocalMCPManager
 from gobby.storage.projects import LocalProjectManager
@@ -18,6 +20,21 @@ logger = logging.getLogger(__name__)
 # Pattern to detect placeholder secrets like <YOUR_API_KEY>
 SECRET_PLACEHOLDER_PATTERN = re.compile(r"<YOUR_[A-Z0-9_]+>")
 
+DEFAULT_GITHUB_FETCH_PROMPT = """Fetch the README from this GitHub repository and extract MCP server configuration:
+
+{github_url}
+
+If the URL doesn't point directly to a README, try to find and fetch the README.md file.
+
+After reading the documentation, extract the MCP server configuration as a JSON object."""
+
+DEFAULT_SEARCH_FETCH_PROMPT = """Search for MCP server: {search_query}
+
+Find the official documentation or GitHub repository for this MCP server.
+Then fetch and read the README or installation docs.
+
+After reading the documentation, extract the MCP server configuration as a JSON object."""
+
 
 class MCPServerImporter:
     """Handles importing MCP servers from various sources."""
@@ -46,6 +63,21 @@ class MCPServerImporter:
         self.mcp_client_manager = mcp_client_manager
         self.import_config = config.get_import_mcp_server_config()
 
+        # Initialize prompt loader
+        project_path = None
+        if current_project_id:
+            if project := self.project_manager.get(current_project_id):
+                project_path = project.repo_path
+
+        from pathlib import Path
+
+        self._loader = PromptLoader(project_dir=Path(project_path) if project_path else None)
+
+        # Register fallbacks
+        self._loader.register_fallback("import/github_fetch", lambda: DEFAULT_GITHUB_FETCH_PROMPT)
+        self._loader.register_fallback("import/search_fetch", lambda: DEFAULT_SEARCH_FETCH_PROMPT)
+        self._loader.register_fallback("import/system", lambda: DEFAULT_IMPORT_MCP_SERVER_PROMPT)
+
     async def import_from_project(
         self,
         source_project: str,
@@ -171,10 +203,23 @@ class MCPServerImporter:
             from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, TextBlock, query
 
             # Build prompt to fetch and extract config
-            prompt = self.import_config.github_fetch_prompt.format(github_url=github_url)
+            prompt_path = self.import_config.github_fetch_prompt_path or "import/github_fetch"
+            try:
+                prompt = self._loader.render(prompt_path, {"github_url": github_url})
+            except Exception as e:
+                logger.warning(f"Failed to load Github fetch prompt: {e}")
+                prompt = DEFAULT_GITHUB_FETCH_PROMPT.format(github_url=github_url)
+
+            # Get system prompt
+            sys_prompt_path = self.import_config.prompt_path or "import/system"
+            try:
+                system_prompt = self._loader.render(sys_prompt_path, {})
+            except Exception as e:
+                logger.warning(f"Failed to load import system prompt: {e}")
+                system_prompt = DEFAULT_IMPORT_MCP_SERVER_PROMPT
 
             options = ClaudeAgentOptions(
-                system_prompt=self.import_config.prompt,
+                system_prompt=system_prompt,
                 max_turns=3,
                 model=self.import_config.model,
                 allowed_tools=["WebFetch"],
@@ -222,10 +267,23 @@ class MCPServerImporter:
             from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, TextBlock, query
 
             # Build prompt to search and extract config
-            prompt = self.import_config.search_fetch_prompt.format(search_query=search_query)
+            prompt_path = self.import_config.search_fetch_prompt_path or "import/search_fetch"
+            try:
+                prompt = self._loader.render(prompt_path, {"search_query": search_query})
+            except Exception as e:
+                logger.warning(f"Failed to load search fetch prompt: {e}")
+                prompt = DEFAULT_SEARCH_FETCH_PROMPT.format(search_query=search_query)
+
+            # Get system prompt
+            sys_prompt_path = self.import_config.prompt_path or "import/system"
+            try:
+                system_prompt = self._loader.render(sys_prompt_path, {})
+            except Exception as e:
+                logger.warning(f"Failed to load import system prompt: {e}")
+                system_prompt = DEFAULT_IMPORT_MCP_SERVER_PROMPT
 
             options = ClaudeAgentOptions(
-                system_prompt=self.import_config.prompt,
+                system_prompt=system_prompt,
                 max_turns=5,  # More turns for search + fetch
                 model=self.import_config.model,
                 allowed_tools=["WebSearch", "WebFetch"],

gobby/mcp_proxy/instructions.py

@@ -0,0 +1,56 @@
+"""Gobby MCP server instructions.
+
+Provides XML-structured instructions that teach agents how to use Gobby correctly.
+These instructions are injected into the MCP server via FastMCP's `instructions` parameter.
+"""
+
+
+def build_gobby_instructions() -> str:
+    """Build XML-structured instructions for Gobby MCP server.
+
+    These instructions teach agents how to use Gobby correctly.
+    Every agent connecting to Gobby receives these automatically.
+
+    The instructions cover:
+    - Session startup sequence
+    - Progressive tool disclosure pattern
+    - Progressive skill disclosure pattern
+    - Critical rules for task management
+
+    Returns:
+        XML-structured instructions string
+    """
+    return """<gobby_system>
+
+<startup>
+At the start of EVERY session:
+1. `list_mcp_servers()` — Discover available servers
+2. `list_skills()` — Discover available skills
+3. Session ID: Look for `session_id: <uuid>` in your context.
+   If missing, call:
+   `call_tool("gobby-sessions", "get_current", {"external_id": "<your-session-id>", "source": "claude"})`
+
+Session and task references use `#N` format (e.g., `#1`, `#42`) which is project-scoped.
+</startup>
+
+<tool_discovery>
+NEVER assume tool schemas. Use progressive disclosure:
+1. `list_tools(server="...")` — Lightweight metadata (~100 tokens/tool)
+2. `get_tool_schema(server, tool)` — Full schema when needed
+3. `call_tool(server, tool, args)` — Execute
+</tool_discovery>
+
+<skill_discovery>
+Skills provide detailed guidance. Use progressive disclosure:
+1. `list_skills()` — Already done at startup
+2. `get_skill(name="...")` — Full content when needed
+3. `search_skills(query="...")` — Find by task description
+</skill_discovery>
+
+<rules>
+- Create/claim a task before using Edit, Write, or NotebookEdit tools
+- Pass session_id to create_task (required), claim_task (required), and close_task (optional, for tracking)
+- NEVER load all tool schemas upfront — use progressive disclosure
+</rules>
+
+</gobby_system>"""

gobby/mcp_proxy/models.py

@@ -31,6 +31,21 @@ class MCPError(Exception):
         self.code = code
 
 
+class ToolProxyErrorCode(str, Enum):
+    """Structured error codes for ToolProxyService responses.
+
+    Used by _process_tool_proxy_result to determine HTTP status codes
+    without fragile string matching.
+    """
+
+    SERVER_NOT_FOUND = "SERVER_NOT_FOUND"
+    SERVER_NOT_CONFIGURED = "SERVER_NOT_CONFIGURED"
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND"
+    INVALID_ARGUMENTS = "INVALID_ARGUMENTS"
+    EXECUTION_ERROR = "EXECUTION_ERROR"
+    CONNECTION_ERROR = "CONNECTION_ERROR"
+
+
 class HealthState(str, Enum):
     """Connection health state for monitoring."""
 

gobby/mcp_proxy/registries.py

@@ -16,13 +16,14 @@ if TYPE_CHECKING:
     from gobby.mcp_proxy.services.tool_proxy import ToolProxyService
     from gobby.memory.manager import MemoryManager
     from gobby.sessions.manager import SessionManager
+    from gobby.storage.clones import LocalCloneManager
+    from gobby.storage.inter_session_messages import InterSessionMessageManager
     from gobby.storage.merge_resolutions import MergeResolutionManager
     from gobby.storage.session_messages import LocalSessionMessageManager
     from gobby.storage.sessions import LocalSessionManager
     from gobby.storage.tasks import LocalTaskManager
     from gobby.storage.worktrees import LocalWorktreeManager
     from gobby.sync.tasks import TaskSyncManager
-    from gobby.tasks.expansion import TaskExpander
     from gobby.tasks.validation import TaskValidator
     from gobby.worktrees.git import WorktreeGitManager
     from gobby.worktrees.merge import MergeResolver
@@ -36,7 +37,6 @@ def setup_internal_registries(
     memory_manager: MemoryManager | None = None,
     task_manager: LocalTaskManager | None = None,
     sync_manager: TaskSyncManager | None = None,
-    task_expander: TaskExpander | None = None,
     task_validator: TaskValidator | None = None,
     message_manager: LocalSessionMessageManager | None = None,
     local_session_manager: LocalSessionManager | None = None,
@@ -44,11 +44,13 @@ def setup_internal_registries(
     llm_service: LLMService | None = None,
     agent_runner: AgentRunner | None = None,
     worktree_storage: LocalWorktreeManager | None = None,
+    clone_storage: LocalCloneManager | None = None,
     git_manager: WorktreeGitManager | None = None,
     merge_storage: MergeResolutionManager | None = None,
     merge_resolver: MergeResolver | None = None,
     project_id: str | None = None,
     tool_proxy_getter: Callable[[], ToolProxyService | None] | None = None,
+    inter_session_message_manager: InterSessionMessageManager | None = None,
 ) -> InternalRegistryManager:
     """
     Setup internal MCP registries (tasks, messages, memory, metrics, agents, worktrees).
@@ -59,7 +61,6 @@ def setup_internal_registries(
         memory_manager: Memory manager for memory operations
         task_manager: Task storage manager
         sync_manager: Task sync manager for git sync
-        task_expander: Task expander for AI expansion
         task_validator: Task validator for validation
         message_manager: Message storage manager
         local_session_manager: Local session manager for session CRUD
@@ -73,6 +74,7 @@ def setup_internal_registries(
         project_id: Default project ID for worktree operations
         tool_proxy_getter: Callable that returns ToolProxyService for routing
             tool calls in in-process agents. Called lazily during agent execution.
+        inter_session_message_manager: Inter-session message manager for agent messaging
 
     Returns:
         InternalRegistryManager containing all registries
@@ -99,7 +101,6 @@ def setup_internal_registries(
             tasks_registry = create_task_registry(
                 task_manager=task_manager,
                 sync_manager=sync_manager,
-                task_expander=task_expander,
                 task_validator=task_validator,
                 config=_config,
                 agent_runner=agent_runner,
@@ -113,7 +114,7 @@ def setup_internal_registries(
     # Initialize sessions registry (messages + session CRUD)
     # Register if either message_manager or local_session_manager is available
     if message_manager is not None or local_session_manager is not None:
-        from gobby.mcp_proxy.tools.session_messages import create_session_messages_registry
+        from gobby.mcp_proxy.tools.sessions import create_session_messages_registry
 
         session_messages_registry = create_session_messages_registry(
             message_manager=message_manager,
@@ -150,20 +151,41 @@ def setup_internal_registries(
     if metrics_manager is not None:
         from gobby.mcp_proxy.tools.metrics import create_metrics_registry
 
+        # Get daily budget from conductor config if available
+        daily_budget_usd = 50.0  # Default
+        if _config is not None:
+            conductor_config = _config.conductor
+            if conductor_config is not None:
+                daily_budget_usd = conductor_config.daily_budget_usd
+
         metrics_registry = create_metrics_registry(
             metrics_manager=metrics_manager,
+            session_storage=local_session_manager,
+            daily_budget_usd=daily_budget_usd,
         )
         manager.add_registry(metrics_registry)
-        logger.debug("Metrics registry initialized")
+        logger.debug("Metrics registry initialized with token tracking")
 
     # Initialize agents registry if agent_runner is available
     if agent_runner is not None:
+        from gobby.agents.registry import get_running_agent_registry
         from gobby.mcp_proxy.tools.agents import create_agents_registry
 
         agents_registry = create_agents_registry(
             runner=agent_runner,
-            tool_proxy_getter=tool_proxy_getter,
         )
+
+        # Add inter-agent messaging tools if message manager is available
+        if inter_session_message_manager is not None:
+            from gobby.mcp_proxy.tools.agent_messaging import add_messaging_tools
+
+            add_messaging_tools(
+                registry=agents_registry,
+                message_manager=inter_session_message_manager,
+                agent_registry=get_running_agent_registry(),
+            )
+            logger.debug("Agent messaging tools added to agents registry")
+
         manager.add_registry(agents_registry)
         logger.debug("Agents registry initialized")
 
@@ -175,11 +197,35 @@ def setup_internal_registries(
             worktree_storage=worktree_storage,
             git_manager=git_manager,
             project_id=project_id,
-            agent_runner=agent_runner,
         )
         manager.add_registry(worktrees_registry)
         logger.debug("Worktrees registry initialized")
 
+    # Initialize clones registry if clone_storage is available
+    if clone_storage is not None:
+        from gobby.clones.git import CloneGitManager
+        from gobby.mcp_proxy.tools.clones import create_clones_registry
+
+        # Create CloneGitManager from the same repo path as WorktreeGitManager
+        clone_git_manager = None
+        if git_manager is not None:
+            try:
+                clone_git_manager = CloneGitManager(git_manager.repo_path)
+            except Exception as e:
+                logger.warning(f"Failed to create CloneGitManager: {e}")
+
+        # Only create clones registry if we have a git manager
+        if clone_git_manager is not None:
+            clones_registry = create_clones_registry(
+                clone_storage=clone_storage,
+                git_manager=clone_git_manager,
+                project_id=project_id or "",
+            )
+            manager.add_registry(clones_registry)
+            logger.debug("Clones registry initialized")
+        else:
+            logger.debug("Clones registry not initialized: CloneGitManager not available")
+
     # Initialize merge resolution registry if merge components are available
     if merge_storage is not None and merge_resolver is not None:
         from gobby.mcp_proxy.tools.merge import create_merge_registry
@@ -204,6 +250,20 @@ def setup_internal_registries(
         manager.add_registry(hub_registry)
         logger.debug("Hub registry initialized")
 
+    # Initialize skills registry using the existing database from task_manager
+    # to avoid creating a duplicate connection that would leak
+    if task_manager is not None:
+        from gobby.mcp_proxy.tools.skills import create_skills_registry
+
+        skills_registry = create_skills_registry(
+            db=task_manager.db,
+            project_id=project_id,
+        )
+        manager.add_registry(skills_registry)
+        logger.debug("Skills registry initialized")
+    else:
+        logger.debug("Skills registry not initialized: task_manager is None")
+
     logger.info(f"Internal registries initialized: {len(manager)} registries")
     return manager
 

gobby/mcp_proxy/server.py

@@ -2,13 +2,16 @@
 Gobby Daemon Tools MCP Server.
 """
 
+import json
 import logging
 from datetime import UTC
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent
 
 from gobby.config.app import DaemonConfig
+from gobby.mcp_proxy.instructions import build_gobby_instructions
 from gobby.mcp_proxy.manager import MCPClientManager
 from gobby.mcp_proxy.services.recommendation import RecommendationService, SearchMode
 from gobby.mcp_proxy.services.server_mgmt import ServerManagementService
@@ -96,8 +99,35 @@ class GobbyDaemonTools:
         tool_name: str,
         arguments: dict[str, Any] | None = None,
     ) -> Any:
-        """Call a tool."""
-        return await self.tool_proxy.call_tool(server_name, tool_name, arguments)
+        """Call a tool.
+
+        Returns the tool result, or a CallToolResult with isError=True if the
+        underlying service indicates an error. This ensures the MCP protocol
+        properly signals errors to LLM clients instead of returning error dicts
+        as successful responses.
+        """
+        result = await self.tool_proxy.call_tool(server_name, tool_name, arguments)
+
+        # Check if result indicates an error (ToolProxyService returns dict with success: False)
+        if isinstance(result, dict) and result.get("success") is False:
+            # Build helpful error message with schema hint if available
+            error_msg = result.get("error", "Unknown error")
+            hint = result.get("hint", "")
+            schema = result.get("schema")
+
+            parts = [f"Error: {error_msg}"]
+            if hint:
+                parts.append(f"\n{hint}")
+            if schema:
+                parts.append(f"\nCorrect schema:\n{json.dumps(schema, indent=2)}")
+
+            # Return MCP error response with isError=True
+            return CallToolResult(
+                content=[TextContent(type="text", text="\n".join(parts))],
+                isError=True,
+            )
+
+        return result
 
     async def list_tools(self, server: str, session_id: str | None = None) -> dict[str, Any]:
         """List tools for a specific server, optionally filtered by workflow phase restrictions."""
@@ -513,7 +543,7 @@ class GobbyDaemonTools:
 
 def create_mcp_server(tools_handler: GobbyDaemonTools) -> FastMCP:
     """Create the FastMCP server instance for the HTTP daemon."""
-    mcp = FastMCP("gobby")
+    mcp = FastMCP("gobby", instructions=build_gobby_instructions())
 
     # System tools
     mcp.add_tool(tools_handler.status)