The architecture has been updated

hermes_code/acp_adapter/__init__.py

@@ -0,0 +1 @@
+"""ACP (Agent Communication Protocol) adapter for hermes-agent."""

hermes_code/acp_adapter/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the ACP adapter as ``python -m acp_adapter``."""
+
+from .entry import main
+
+main()

hermes_code/acp_adapter/auth.py

@@ -0,0 +1,24 @@
+"""ACP auth helpers — detect the currently configured Hermes provider."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def detect_provider() -> Optional[str]:
+    """Resolve the active Hermes runtime provider, or None if unavailable."""
+    try:
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+        runtime = resolve_runtime_provider()
+        api_key = runtime.get("api_key")
+        provider = runtime.get("provider")
+        if isinstance(api_key, str) and api_key.strip() and isinstance(provider, str) and provider.strip():
+            return provider.strip().lower()
+    except Exception:
+        return None
+    return None
+
+
+def has_provider() -> bool:
+    """Return True if Hermes can resolve any runtime provider credentials."""
+    return detect_provider() is not None

hermes_code/acp_adapter/entry.py

@@ -0,0 +1,85 @@
+"""CLI entry point for the hermes-agent ACP adapter.
+
+Loads environment variables from ``~/.hermes/.env``, configures logging
+to write to stderr (so stdout is reserved for ACP JSON-RPC transport),
+and starts the ACP agent server.
+
+Usage::
+
+    python -m acp_adapter.entry
+    # or
+    hermes acp
+    # or
+    hermes-acp
+"""
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+
+def _setup_logging() -> None:
+    """Route all logging to stderr so stdout stays clean for ACP stdio."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+
+    # Quiet down noisy libraries
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("openai").setLevel(logging.WARNING)
+
+
+def _load_env() -> None:
+    """Load .env from HERMES_HOME (default ``~/.hermes``)."""
+    from hermes_cli.env_loader import load_hermes_dotenv
+
+    hermes_home = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+    loaded = load_hermes_dotenv(hermes_home=hermes_home)
+    if loaded:
+        for env_file in loaded:
+            logging.getLogger(__name__).info("Loaded env from %s", env_file)
+    else:
+        logging.getLogger(__name__).info(
+            "No .env found at %s, using system env", hermes_home / ".env"
+        )
+
+
+def main() -> None:
+    """Entry point: load env, configure logging, run the ACP agent."""
+    _setup_logging()
+    _load_env()
+
+    logger = logging.getLogger(__name__)
+    logger.info("Starting hermes-agent ACP adapter")
+
+    # Ensure the project root is on sys.path so ``from run_agent import AIAgent`` works
+    project_root = str(Path(__file__).resolve().parent.parent)
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)
+
+    import acp
+    from .server import HermesACPAgent
+
+    agent = HermesACPAgent()
+    try:
+        asyncio.run(acp.run_agent(agent))
+    except KeyboardInterrupt:
+        logger.info("Shutting down (KeyboardInterrupt)")
+    except Exception:
+        logger.exception("ACP agent crashed")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

hermes_code/acp_adapter/events.py

@@ -0,0 +1,171 @@
+"""Callback factories for bridging AIAgent events to ACP notifications.
+
+Each factory returns a callable with the signature that AIAgent expects
+for its callbacks. Internally, the callbacks push ACP session updates
+to the client via ``conn.session_update()`` using
+``asyncio.run_coroutine_threadsafe()`` (since AIAgent runs in a worker
+thread while the event loop lives on the main thread).
+"""
+
+import asyncio
+import json
+import logging
+from collections import defaultdict, deque
+from typing import Any, Callable, Deque, Dict
+
+import acp
+
+from .tools import (
+    build_tool_complete,
+    build_tool_start,
+    make_tool_call_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _send_update(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    update: Any,
+) -> None:
+    """Fire-and-forget an ACP session update from a worker thread."""
+    try:
+        future = asyncio.run_coroutine_threadsafe(
+            conn.session_update(session_id, update), loop
+        )
+        future.result(timeout=5)
+    except Exception:
+        logger.debug("Failed to send ACP update", exc_info=True)
+
+
+# ------------------------------------------------------------------
+# Tool progress callback
+# ------------------------------------------------------------------
+
+def make_tool_progress_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+) -> Callable:
+    """Create a ``tool_progress_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        tool_progress_callback(name: str, preview: str, args: dict)
+
+    Emits ``ToolCallStart`` for each tool invocation and tracks IDs in a FIFO
+    queue per tool name so duplicate/parallel same-name calls still complete
+    against the correct ACP tool call.
+    """
+
+    def _tool_progress(name: str, preview: str, args: Any = None) -> None:
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except (json.JSONDecodeError, TypeError):
+                args = {"raw": args}
+        if not isinstance(args, dict):
+            args = {}
+
+        tc_id = make_tool_call_id()
+        queue = tool_call_ids.get(name)
+        if queue is None:
+            queue = deque()
+            tool_call_ids[name] = queue
+        elif isinstance(queue, str):
+            queue = deque([queue])
+            tool_call_ids[name] = queue
+        queue.append(tc_id)
+
+        update = build_tool_start(tc_id, name, args)
+        _send_update(conn, session_id, loop, update)
+
+    return _tool_progress
+
+
+# ------------------------------------------------------------------
+# Thinking callback
+# ------------------------------------------------------------------
+
+def make_thinking_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a ``thinking_callback`` for AIAgent."""
+
+    def _thinking(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_thought_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _thinking
+
+
+# ------------------------------------------------------------------
+# Step callback
+# ------------------------------------------------------------------
+
+def make_step_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+) -> Callable:
+    """Create a ``step_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        step_callback(api_call_count: int, prev_tools: list)
+    """
+
+    def _step(api_call_count: int, prev_tools: Any = None) -> None:
+        if prev_tools and isinstance(prev_tools, list):
+            for tool_info in prev_tools:
+                tool_name = None
+                result = None
+
+                if isinstance(tool_info, dict):
+                    tool_name = tool_info.get("name") or tool_info.get("function_name")
+                    result = tool_info.get("result") or tool_info.get("output")
+                elif isinstance(tool_info, str):
+                    tool_name = tool_info
+
+                queue = tool_call_ids.get(tool_name or "")
+                if isinstance(queue, str):
+                    queue = deque([queue])
+                    tool_call_ids[tool_name] = queue
+                if tool_name and queue:
+                    tc_id = queue.popleft()
+                    update = build_tool_complete(
+                        tc_id, tool_name, result=str(result) if result is not None else None
+                    )
+                    _send_update(conn, session_id, loop, update)
+                    if not queue:
+                        tool_call_ids.pop(tool_name, None)
+
+    return _step
+
+
+# ------------------------------------------------------------------
+# Agent message callback
+# ------------------------------------------------------------------
+
+def make_message_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a callback that streams agent response text to the editor."""
+
+    def _message(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_message_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _message

hermes_code/acp_adapter/permissions.py

@@ -0,0 +1,80 @@
+"""ACP permission bridging — maps ACP approval requests to hermes approval callbacks."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import TimeoutError as FutureTimeout
+from typing import Any, Callable, Optional
+
+from acp.schema import (
+    AllowedOutcome,
+    DeniedOutcome,
+    PermissionOption,
+    RequestPermissionRequest,
+    SelectedPermissionOutcome,
+)
+
+logger = logging.getLogger(__name__)
+
+# Maps ACP PermissionOptionKind -> hermes approval result strings
+_KIND_TO_HERMES = {
+    "allow_once": "once",
+    "allow_always": "always",
+    "reject_once": "deny",
+    "reject_always": "deny",
+}
+
+
+def make_approval_callback(
+    request_permission_fn: Callable,
+    loop: asyncio.AbstractEventLoop,
+    session_id: str,
+    timeout: float = 60.0,
+) -> Callable[[str, str], str]:
+    """
+    Return a hermes-compatible ``approval_callback(command, description) -> str``
+    that bridges to the ACP client's ``request_permission`` call.
+
+    Args:
+        request_permission_fn: The ACP connection's ``request_permission`` coroutine.
+        loop: The event loop on which the ACP connection lives.
+        session_id: Current ACP session id.
+        timeout: Seconds to wait for a response before auto-denying.
+    """
+
+    def _callback(command: str, description: str) -> str:
+        options = [
+            PermissionOption(option_id="allow_once", kind="allow_once", name="Allow once"),
+            PermissionOption(option_id="allow_always", kind="allow_always", name="Allow always"),
+            PermissionOption(option_id="deny", kind="reject_once", name="Deny"),
+        ]
+        import acp as _acp
+
+        tool_call = _acp.start_tool_call("perm-check", command, kind="execute")
+
+        coro = request_permission_fn(
+            session_id=session_id,
+            tool_call=tool_call,
+            options=options,
+        )
+
+        try:
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
+            response = future.result(timeout=timeout)
+        except (FutureTimeout, Exception) as exc:
+            logger.warning("Permission request timed out or failed: %s", exc)
+            return "deny"
+
+        outcome = response.outcome
+        if isinstance(outcome, AllowedOutcome):
+            option_id = outcome.option_id
+            # Look up the kind from our options list
+            for opt in options:
+                if opt.option_id == option_id:
+                    return _KIND_TO_HERMES.get(opt.kind, "deny")
+            return "once"  # fallback for unknown option_id
+        else:
+            return "deny"
+
+    return _callback

hermes_code/acp_adapter/server.py

@@ -0,0 +1,492 @@
+"""ACP agent server — exposes Hermes Agent via the Agent Client Protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict, deque
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Deque, Optional
+
+import acp
+from acp.schema import (
+    AgentCapabilities,
+    AuthenticateResponse,
+    AuthMethod,
+    ClientCapabilities,
+    EmbeddedResourceContentBlock,
+    ForkSessionResponse,
+    ImageContentBlock,
+    AudioContentBlock,
+    Implementation,
+    InitializeResponse,
+    ListSessionsResponse,
+    LoadSessionResponse,
+    NewSessionResponse,
+    PromptResponse,
+    ResumeSessionResponse,
+    ResourceContentBlock,
+    SessionCapabilities,
+    SessionForkCapabilities,
+    SessionListCapabilities,
+    SessionInfo,
+    TextContentBlock,
+    Usage,
+)
+
+from acp_adapter.auth import detect_provider, has_provider
+from acp_adapter.events import (
+    make_message_cb,
+    make_step_cb,
+    make_thinking_cb,
+    make_tool_progress_cb,
+)
+from acp_adapter.permissions import make_approval_callback
+from acp_adapter.session import SessionManager, SessionState
+
+logger = logging.getLogger(__name__)
+
+try:
+    from hermes_cli import __version__ as HERMES_VERSION
+except Exception:
+    HERMES_VERSION = "0.0.0"
+
+# Thread pool for running AIAgent (synchronous) in parallel.
+_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="acp-agent")
+
+
+def _extract_text(
+    prompt: list[
+        TextContentBlock
+        | ImageContentBlock
+        | AudioContentBlock
+        | ResourceContentBlock
+        | EmbeddedResourceContentBlock
+    ],
+) -> str:
+    """Extract plain text from ACP content blocks."""
+    parts: list[str] = []
+    for block in prompt:
+        if isinstance(block, TextContentBlock):
+            parts.append(block.text)
+        elif hasattr(block, "text"):
+            parts.append(str(block.text))
+        # Non-text blocks are ignored for now.
+    return "\n".join(parts)
+
+
+class HermesACPAgent(acp.Agent):
+    """ACP Agent implementation wrapping Hermes AIAgent."""
+
+    def __init__(self, session_manager: SessionManager | None = None):
+        super().__init__()
+        self.session_manager = session_manager or SessionManager()
+        self._conn: Optional[acp.Client] = None
+
+    # ---- Connection lifecycle -----------------------------------------------
+
+    def on_connect(self, conn: acp.Client) -> None:
+        """Store the client connection for sending session updates."""
+        self._conn = conn
+        logger.info("ACP client connected")
+
+    # ---- ACP lifecycle ------------------------------------------------------
+
+    async def initialize(
+        self,
+        protocol_version: int,
+        client_capabilities: ClientCapabilities | None = None,
+        client_info: Implementation | None = None,
+        **kwargs: Any,
+    ) -> InitializeResponse:
+        provider = detect_provider()
+        auth_methods = None
+        if provider:
+            auth_methods = [
+                AuthMethod(
+                    id=provider,
+                    name=f"{provider} runtime credentials",
+                    description=f"Authenticate Hermes using the currently configured {provider} runtime credentials.",
+                )
+            ]
+
+        client_name = client_info.name if client_info else "unknown"
+        logger.info("Initialize from %s (protocol v%s)", client_name, protocol_version)
+
+        return InitializeResponse(
+            protocol_version=acp.PROTOCOL_VERSION,
+            agent_info=Implementation(name="hermes-agent", version=HERMES_VERSION),
+            agent_capabilities=AgentCapabilities(
+                session_capabilities=SessionCapabilities(
+                    fork=SessionForkCapabilities(),
+                    list=SessionListCapabilities(),
+                ),
+            ),
+            auth_methods=auth_methods,
+        )
+
+    async def authenticate(self, method_id: str, **kwargs: Any) -> AuthenticateResponse | None:
+        if has_provider():
+            return AuthenticateResponse()
+        return None
+
+    # ---- Session management -------------------------------------------------
+
+    async def new_session(
+        self,
+        cwd: str,
+        mcp_servers: list | None = None,
+        **kwargs: Any,
+    ) -> NewSessionResponse:
+        state = self.session_manager.create_session(cwd=cwd)
+        logger.info("New session %s (cwd=%s)", state.session_id, cwd)
+        return NewSessionResponse(session_id=state.session_id)
+
+    async def load_session(
+        self,
+        cwd: str,
+        session_id: str,
+        mcp_servers: list | None = None,
+        **kwargs: Any,
+    ) -> LoadSessionResponse | None:
+        state = self.session_manager.update_cwd(session_id, cwd)
+        if state is None:
+            logger.warning("load_session: session %s not found", session_id)
+            return None
+        logger.info("Loaded session %s", session_id)
+        return LoadSessionResponse()
+
+    async def resume_session(
+        self,
+        cwd: str,
+        session_id: str,
+        mcp_servers: list | None = None,
+        **kwargs: Any,
+    ) -> ResumeSessionResponse:
+        state = self.session_manager.update_cwd(session_id, cwd)
+        if state is None:
+            logger.warning("resume_session: session %s not found, creating new", session_id)
+            state = self.session_manager.create_session(cwd=cwd)
+        logger.info("Resumed session %s", state.session_id)
+        return ResumeSessionResponse()
+
+    async def cancel(self, session_id: str, **kwargs: Any) -> None:
+        state = self.session_manager.get_session(session_id)
+        if state and state.cancel_event:
+            state.cancel_event.set()
+            try:
+                if getattr(state, "agent", None) and hasattr(state.agent, "interrupt"):
+                    state.agent.interrupt()
+            except Exception:
+                logger.debug("Failed to interrupt ACP session %s", session_id, exc_info=True)
+            logger.info("Cancelled session %s", session_id)
+
+    async def fork_session(
+        self,
+        cwd: str,
+        session_id: str,
+        mcp_servers: list | None = None,
+        **kwargs: Any,
+    ) -> ForkSessionResponse:
+        state = self.session_manager.fork_session(session_id, cwd=cwd)
+        new_id = state.session_id if state else ""
+        logger.info("Forked session %s -> %s", session_id, new_id)
+        return ForkSessionResponse(session_id=new_id)
+
+    async def list_sessions(
+        self,
+        cursor: str | None = None,
+        cwd: str | None = None,
+        **kwargs: Any,
+    ) -> ListSessionsResponse:
+        infos = self.session_manager.list_sessions()
+        sessions = [
+            SessionInfo(session_id=s["session_id"], cwd=s["cwd"])
+            for s in infos
+        ]
+        return ListSessionsResponse(sessions=sessions)
+
+    # ---- Prompt (core) ------------------------------------------------------
+
+    async def prompt(
+        self,
+        prompt: list[
+            TextContentBlock
+            | ImageContentBlock
+            | AudioContentBlock
+            | ResourceContentBlock
+            | EmbeddedResourceContentBlock
+        ],
+        session_id: str,
+        **kwargs: Any,
+    ) -> PromptResponse:
+        """Run Hermes on the user's prompt and stream events back to the editor."""
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            logger.error("prompt: session %s not found", session_id)
+            return PromptResponse(stop_reason="refusal")
+
+        user_text = _extract_text(prompt).strip()
+        if not user_text:
+            return PromptResponse(stop_reason="end_turn")
+
+        # Intercept slash commands — handle locally without calling the LLM
+        if user_text.startswith("/"):
+            response_text = self._handle_slash_command(user_text, state)
+            if response_text is not None:
+                if self._conn:
+                    update = acp.update_agent_message_text(response_text)
+                    await self._conn.session_update(session_id, update)
+                return PromptResponse(stop_reason="end_turn")
+
+        logger.info("Prompt on session %s: %s", session_id, user_text[:100])
+
+        conn = self._conn
+        loop = asyncio.get_running_loop()
+
+        if state.cancel_event:
+            state.cancel_event.clear()
+
+        tool_call_ids: dict[str, Deque[str]] = defaultdict(deque)
+        previous_approval_cb = None
+
+        if conn:
+            tool_progress_cb = make_tool_progress_cb(conn, session_id, loop, tool_call_ids)
+            thinking_cb = make_thinking_cb(conn, session_id, loop)
+            step_cb = make_step_cb(conn, session_id, loop, tool_call_ids)
+            message_cb = make_message_cb(conn, session_id, loop)
+            approval_cb = make_approval_callback(conn.request_permission, loop, session_id)
+        else:
+            tool_progress_cb = None
+            thinking_cb = None
+            step_cb = None
+            message_cb = None
+            approval_cb = None
+
+        agent = state.agent
+        agent.tool_progress_callback = tool_progress_cb
+        agent.thinking_callback = thinking_cb
+        agent.step_callback = step_cb
+        agent.message_callback = message_cb
+
+        if approval_cb:
+            try:
+                from tools import terminal_tool as _terminal_tool
+                previous_approval_cb = getattr(_terminal_tool, "_approval_callback", None)
+                _terminal_tool.set_approval_callback(approval_cb)
+            except Exception:
+                logger.debug("Could not set ACP approval callback", exc_info=True)
+
+        def _run_agent() -> dict:
+            try:
+                result = agent.run_conversation(
+                    user_message=user_text,
+                    conversation_history=state.history,
+                    task_id=session_id,
+                )
+                return result
+            except Exception as e:
+                logger.exception("Agent error in session %s", session_id)
+                return {"final_response": f"Error: {e}", "messages": state.history}
+            finally:
+                if approval_cb:
+                    try:
+                        from tools import terminal_tool as _terminal_tool
+                        _terminal_tool.set_approval_callback(previous_approval_cb)
+                    except Exception:
+                        logger.debug("Could not restore approval callback", exc_info=True)
+
+        try:
+            result = await loop.run_in_executor(_executor, _run_agent)
+        except Exception:
+            logger.exception("Executor error for session %s", session_id)
+            return PromptResponse(stop_reason="end_turn")
+
+        if result.get("messages"):
+            state.history = result["messages"]
+            # Persist updated history so sessions survive process restarts.
+            self.session_manager.save_session(session_id)
+
+        final_response = result.get("final_response", "")
+        if final_response and conn:
+            update = acp.update_agent_message_text(final_response)
+            await conn.session_update(session_id, update)
+
+        usage = None
+        usage_data = result.get("usage")
+        if usage_data and isinstance(usage_data, dict):
+            usage = Usage(
+                input_tokens=usage_data.get("prompt_tokens", 0),
+                output_tokens=usage_data.get("completion_tokens", 0),
+                total_tokens=usage_data.get("total_tokens", 0),
+                thought_tokens=usage_data.get("reasoning_tokens"),
+                cached_read_tokens=usage_data.get("cached_tokens"),
+            )
+
+        stop_reason = "cancelled" if state.cancel_event and state.cancel_event.is_set() else "end_turn"
+        return PromptResponse(stop_reason=stop_reason, usage=usage)
+
+    # ---- Slash commands (headless) -------------------------------------------
+
+    _SLASH_COMMANDS = {
+        "help": "Show available commands",
+        "model": "Show or change current model",
+        "tools": "List available tools",
+        "context": "Show conversation context info",
+        "reset": "Clear conversation history",
+        "compact": "Compress conversation context",
+        "version": "Show Hermes version",
+    }
+
+    def _handle_slash_command(self, text: str, state: SessionState) -> str | None:
+        """Dispatch a slash command and return the response text.
+
+        Returns ``None`` for unrecognized commands so they fall through
+        to the LLM (the user may have typed ``/something`` as prose).
+        """
+        parts = text.split(maxsplit=1)
+        cmd = parts[0].lstrip("/").lower()
+        args = parts[1].strip() if len(parts) > 1 else ""
+
+        handler = {
+            "help": self._cmd_help,
+            "model": self._cmd_model,
+            "tools": self._cmd_tools,
+            "context": self._cmd_context,
+            "reset": self._cmd_reset,
+            "compact": self._cmd_compact,
+            "version": self._cmd_version,
+        }.get(cmd)
+
+        if handler is None:
+            return None  # not a known command — let the LLM handle it
+
+        try:
+            return handler(args, state)
+        except Exception as e:
+            logger.error("Slash command /%s error: %s", cmd, e, exc_info=True)
+            return f"Error executing /{cmd}: {e}"
+
+    def _cmd_help(self, args: str, state: SessionState) -> str:
+        lines = ["Available commands:", ""]
+        for cmd, desc in self._SLASH_COMMANDS.items():
+            lines.append(f"  /{cmd:10s}  {desc}")
+        lines.append("")
+        lines.append("Unrecognized /commands are sent to the model as normal messages.")
+        return "\n".join(lines)
+
+    def _cmd_model(self, args: str, state: SessionState) -> str:
+        if not args:
+            model = state.model or getattr(state.agent, "model", "unknown")
+            provider = getattr(state.agent, "provider", None) or "auto"
+            return f"Current model: {model}\nProvider: {provider}"
+
+        new_model = args.strip()
+        target_provider = None
+        current_provider = getattr(state.agent, "provider", None) or "openrouter"
+
+        # Auto-detect provider for the requested model
+        try:
+            from hermes_cli.models import parse_model_input, detect_provider_for_model
+            target_provider, new_model = parse_model_input(new_model, current_provider)
+            if target_provider == current_provider:
+                detected = detect_provider_for_model(new_model, current_provider)
+                if detected:
+                    target_provider, new_model = detected
+        except Exception:
+            logger.debug("Provider detection failed, using model as-is", exc_info=True)
+
+        state.model = new_model
+        state.agent = self.session_manager._make_agent(
+            session_id=state.session_id,
+            cwd=state.cwd,
+            model=new_model,
+            requested_provider=target_provider or current_provider,
+        )
+        self.session_manager.save_session(state.session_id)
+        provider_label = getattr(state.agent, "provider", None) or target_provider or current_provider
+        logger.info("Session %s: model switched to %s", state.session_id, new_model)
+        return f"Model switched to: {new_model}\nProvider: {provider_label}"
+
+    def _cmd_tools(self, args: str, state: SessionState) -> str:
+        try:
+            from model_tools import get_tool_definitions
+            toolsets = getattr(state.agent, "enabled_toolsets", None) or ["hermes-acp"]
+            tools = get_tool_definitions(enabled_toolsets=toolsets, quiet_mode=True)
+            if not tools:
+                return "No tools available."
+            lines = [f"Available tools ({len(tools)}):"]
+            for t in tools:
+                name = t.get("function", {}).get("name", "?")
+                desc = t.get("function", {}).get("description", "")
+                # Truncate long descriptions
+                if len(desc) > 80:
+                    desc = desc[:77] + "..."
+                lines.append(f"  {name}: {desc}")
+            return "\n".join(lines)
+        except Exception as e:
+            return f"Could not list tools: {e}"
+
+    def _cmd_context(self, args: str, state: SessionState) -> str:
+        n_messages = len(state.history)
+        if n_messages == 0:
+            return "Conversation is empty (no messages yet)."
+        # Count by role
+        roles: dict[str, int] = {}
+        for msg in state.history:
+            role = msg.get("role", "unknown")
+            roles[role] = roles.get(role, 0) + 1
+        lines = [
+            f"Conversation: {n_messages} messages",
+            f"  user: {roles.get('user', 0)}, assistant: {roles.get('assistant', 0)}, "
+            f"tool: {roles.get('tool', 0)}, system: {roles.get('system', 0)}",
+        ]
+        model = state.model or getattr(state.agent, "model", "")
+        if model:
+            lines.append(f"Model: {model}")
+        return "\n".join(lines)
+
+    def _cmd_reset(self, args: str, state: SessionState) -> str:
+        state.history.clear()
+        self.session_manager.save_session(state.session_id)
+        return "Conversation history cleared."
+
+    def _cmd_compact(self, args: str, state: SessionState) -> str:
+        if not state.history:
+            return "Nothing to compress — conversation is empty."
+        try:
+            agent = state.agent
+            if hasattr(agent, "compress_context"):
+                agent.compress_context(state.history)
+                self.session_manager.save_session(state.session_id)
+                return f"Context compressed. Messages: {len(state.history)}"
+            return "Context compression not available for this agent."
+        except Exception as e:
+            return f"Compression failed: {e}"
+
+    def _cmd_version(self, args: str, state: SessionState) -> str:
+        return f"Hermes Agent v{HERMES_VERSION}"
+
+    # ---- Model switching (ACP protocol method) -------------------------------
+
+    async def set_session_model(
+        self, model_id: str, session_id: str, **kwargs: Any
+    ):
+        """Switch the model for a session (called by ACP protocol)."""
+        state = self.session_manager.get_session(session_id)
+        if state:
+            state.model = model_id
+            current_provider = getattr(state.agent, "provider", None)
+            current_base_url = getattr(state.agent, "base_url", None)
+            current_api_mode = getattr(state.agent, "api_mode", None)
+            state.agent = self.session_manager._make_agent(
+                session_id=session_id,
+                cwd=state.cwd,
+                model=model_id,
+                requested_provider=current_provider,
+                base_url=current_base_url,
+                api_mode=current_api_mode,
+            )
+            self.session_manager.save_session(session_id)
+            logger.info("Session %s: model switched to %s", session_id, model_id)
+        return None

hermes_code/acp_adapter/session.py

@@ -0,0 +1,459 @@
+"""ACP session manager — maps ACP sessions to Hermes AIAgent instances.
+
+Sessions are persisted to the shared SessionDB (``~/.hermes/state.db``) so they
+survive process restarts and appear in ``session_search``.  When the editor
+reconnects after idle/restart, the ``load_session`` / ``resume_session`` calls
+find the persisted session in the database and restore the full conversation
+history.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import logging
+import uuid
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _register_task_cwd(task_id: str, cwd: str) -> None:
+    """Bind a task/session id to the editor's working directory for tools."""
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import register_task_env_overrides
+        register_task_env_overrides(task_id, {"cwd": cwd})
+    except Exception:
+        logger.debug("Failed to register ACP task cwd override", exc_info=True)
+
+
+def _clear_task_cwd(task_id: str) -> None:
+    """Remove task-specific cwd overrides for an ACP session."""
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import clear_task_env_overrides
+        clear_task_env_overrides(task_id)
+    except Exception:
+        logger.debug("Failed to clear ACP task cwd override", exc_info=True)
+
+
+@dataclass
+class SessionState:
+    """Tracks per-session state for an ACP-managed Hermes agent."""
+
+    session_id: str
+    agent: Any  # AIAgent instance
+    cwd: str = "."
+    model: str = ""
+    history: List[Dict[str, Any]] = field(default_factory=list)
+    cancel_event: Any = None  # threading.Event
+
+
+class SessionManager:
+    """Thread-safe manager for ACP sessions backed by Hermes AIAgent instances.
+
+    Sessions are held in-memory for fast access **and** persisted to the
+    shared SessionDB so they survive process restarts and are searchable
+    via ``session_search``.
+    """
+
+    def __init__(self, agent_factory=None, db=None):
+        """
+        Args:
+            agent_factory: Optional callable that creates an AIAgent-like object.
+                           Used by tests. When omitted, a real AIAgent is created
+                           using the current Hermes runtime provider configuration.
+            db:            Optional SessionDB instance. When omitted, the default
+                           SessionDB (``~/.hermes/state.db``) is lazily created.
+        """
+        self._sessions: Dict[str, SessionState] = {}
+        self._lock = Lock()
+        self._agent_factory = agent_factory
+        self._db_instance = db  # None → lazy-init on first use
+
+    # ---- public API ---------------------------------------------------------
+
+    def create_session(self, cwd: str = ".") -> SessionState:
+        """Create a new session with a unique ID and a fresh AIAgent."""
+        import threading
+
+        session_id = str(uuid.uuid4())
+        agent = self._make_agent(session_id=session_id, cwd=cwd)
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", "") or "",
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        logger.info("Created ACP session %s (cwd=%s)", session_id, cwd)
+        return state
+
+    def get_session(self, session_id: str) -> Optional[SessionState]:
+        """Return the session for *session_id*, or ``None``.
+
+        If the session is not in memory but exists in the database (e.g. after
+        a process restart), it is transparently restored.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            return state
+        # Attempt to restore from database.
+        return self._restore(session_id)
+
+    def remove_session(self, session_id: str) -> bool:
+        """Remove a session from memory and database. Returns True if it existed."""
+        with self._lock:
+            existed = self._sessions.pop(session_id, None) is not None
+        db_existed = self._delete_persisted(session_id)
+        if existed or db_existed:
+            _clear_task_cwd(session_id)
+        return existed or db_existed
+
+    def fork_session(self, session_id: str, cwd: str = ".") -> Optional[SessionState]:
+        """Deep-copy a session's history into a new session."""
+        import threading
+
+        original = self.get_session(session_id)  # checks DB too
+        if original is None:
+            return None
+
+        new_id = str(uuid.uuid4())
+        agent = self._make_agent(
+            session_id=new_id,
+            cwd=cwd,
+            model=original.model or None,
+        )
+        state = SessionState(
+            session_id=new_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", original.model) or original.model,
+            history=copy.deepcopy(original.history),
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[new_id] = state
+        _register_task_cwd(new_id, cwd)
+        self._persist(state)
+        logger.info("Forked ACP session %s -> %s", session_id, new_id)
+        return state
+
+    def list_sessions(self) -> List[Dict[str, Any]]:
+        """Return lightweight info dicts for all sessions (memory + database)."""
+        # Collect in-memory sessions first.
+        with self._lock:
+            seen_ids = set(self._sessions.keys())
+            results = [
+                {
+                    "session_id": s.session_id,
+                    "cwd": s.cwd,
+                    "model": s.model,
+                    "history_len": len(s.history),
+                }
+                for s in self._sessions.values()
+            ]
+
+        # Merge any persisted sessions not currently in memory.
+        db = self._get_db()
+        if db is not None:
+            try:
+                rows = db.search_sessions(source="acp", limit=1000)
+                for row in rows:
+                    sid = row["id"]
+                    if sid in seen_ids:
+                        continue
+                    # Extract cwd from model_config JSON.
+                    cwd = "."
+                    mc = row.get("model_config")
+                    if mc:
+                        try:
+                            cwd = json.loads(mc).get("cwd", ".")
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                    results.append({
+                        "session_id": sid,
+                        "cwd": cwd,
+                        "model": row.get("model") or "",
+                        "history_len": row.get("message_count") or 0,
+                    })
+            except Exception:
+                logger.debug("Failed to list ACP sessions from DB", exc_info=True)
+
+        return results
+
+    def update_cwd(self, session_id: str, cwd: str) -> Optional[SessionState]:
+        """Update the working directory for a session and its tool overrides."""
+        state = self.get_session(session_id)  # checks DB too
+        if state is None:
+            return None
+        state.cwd = cwd
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        return state
+
+    def cleanup(self) -> None:
+        """Remove all sessions (memory and database) and clear task-specific cwd overrides."""
+        with self._lock:
+            session_ids = list(self._sessions.keys())
+            self._sessions.clear()
+        for session_id in session_ids:
+            _clear_task_cwd(session_id)
+            self._delete_persisted(session_id)
+        # Also remove any DB-only ACP sessions not currently in memory.
+        db = self._get_db()
+        if db is not None:
+            try:
+                rows = db.search_sessions(source="acp", limit=10000)
+                for row in rows:
+                    sid = row["id"]
+                    _clear_task_cwd(sid)
+                    db.delete_session(sid)
+            except Exception:
+                logger.debug("Failed to cleanup ACP sessions from DB", exc_info=True)
+
+    def save_session(self, session_id: str) -> None:
+        """Persist the current state of a session to the database.
+
+        Called by the server after prompt completion, slash commands that
+        mutate history, and model switches.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            self._persist(state)
+
+    # ---- persistence via SessionDB ------------------------------------------
+
+    def _get_db(self):
+        """Lazily initialise and return the SessionDB instance.
+
+        Returns ``None`` if the DB is unavailable (e.g. import error in a
+        minimal test environment).
+
+        Note: we resolve ``HERMES_HOME`` dynamically rather than relying on
+        the module-level ``DEFAULT_DB_PATH`` constant, because that constant
+        is evaluated at import time and won't reflect env-var changes made
+        later (e.g. by the test fixture ``_isolate_hermes_home``).
+        """
+        if self._db_instance is not None:
+            return self._db_instance
+        try:
+            import os
+            from pathlib import Path
+            from hermes_state import SessionDB
+            hermes_home = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+            self._db_instance = SessionDB(db_path=hermes_home / "state.db")
+            return self._db_instance
+        except Exception:
+            logger.debug("SessionDB unavailable for ACP persistence", exc_info=True)
+            return None
+
+    def _persist(self, state: SessionState) -> None:
+        """Write session state to the database.
+
+        Creates the session record if it doesn't exist, then replaces all
+        stored messages with the current in-memory history.
+        """
+        db = self._get_db()
+        if db is None:
+            return
+
+        # Ensure model is a plain string (not a MagicMock or other proxy).
+        model_str = str(state.model) if state.model else None
+        session_meta = {"cwd": state.cwd}
+        provider = getattr(state.agent, "provider", None)
+        base_url = getattr(state.agent, "base_url", None)
+        api_mode = getattr(state.agent, "api_mode", None)
+        if isinstance(provider, str) and provider.strip():
+            session_meta["provider"] = provider.strip()
+        if isinstance(base_url, str) and base_url.strip():
+            session_meta["base_url"] = base_url.strip()
+        if isinstance(api_mode, str) and api_mode.strip():
+            session_meta["api_mode"] = api_mode.strip()
+        cwd_json = json.dumps(session_meta)
+
+        try:
+            # Ensure the session record exists.
+            existing = db.get_session(state.session_id)
+            if existing is None:
+                db.create_session(
+                    session_id=state.session_id,
+                    source="acp",
+                    model=model_str,
+                    model_config={"cwd": state.cwd},
+                )
+            else:
+                # Update model_config (contains cwd) if changed.
+                try:
+                    with db._lock:
+                        db._conn.execute(
+                            "UPDATE sessions SET model_config = ?, model = COALESCE(?, model) WHERE id = ?",
+                            (cwd_json, model_str, state.session_id),
+                        )
+                        db._conn.commit()
+                except Exception:
+                    logger.debug("Failed to update ACP session metadata", exc_info=True)
+
+            # Replace stored messages with current history.
+            db.clear_messages(state.session_id)
+            for msg in state.history:
+                db.append_message(
+                    session_id=state.session_id,
+                    role=msg.get("role", "user"),
+                    content=msg.get("content"),
+                    tool_name=msg.get("tool_name") or msg.get("name"),
+                    tool_calls=msg.get("tool_calls"),
+                    tool_call_id=msg.get("tool_call_id"),
+                )
+        except Exception:
+            logger.warning("Failed to persist ACP session %s", state.session_id, exc_info=True)
+
+    def _restore(self, session_id: str) -> Optional[SessionState]:
+        """Load a session from the database into memory, recreating the AIAgent."""
+        import threading
+
+        db = self._get_db()
+        if db is None:
+            return None
+
+        try:
+            row = db.get_session(session_id)
+        except Exception:
+            logger.debug("Failed to query DB for ACP session %s", session_id, exc_info=True)
+            return None
+
+        if row is None:
+            return None
+
+        # Only restore ACP sessions.
+        if row.get("source") != "acp":
+            return None
+
+        # Extract cwd from model_config.
+        cwd = "."
+        requested_provider = row.get("billing_provider")
+        restored_base_url = row.get("billing_base_url")
+        restored_api_mode = None
+        mc = row.get("model_config")
+        if mc:
+            try:
+                meta = json.loads(mc)
+                if isinstance(meta, dict):
+                    cwd = meta.get("cwd", ".")
+                    requested_provider = meta.get("provider") or requested_provider
+                    restored_base_url = meta.get("base_url") or restored_base_url
+                    restored_api_mode = meta.get("api_mode") or restored_api_mode
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        model = row.get("model") or None
+
+        # Load conversation history.
+        try:
+            history = db.get_messages_as_conversation(session_id)
+        except Exception:
+            logger.warning("Failed to load messages for ACP session %s", session_id, exc_info=True)
+            history = []
+
+        try:
+            agent = self._make_agent(
+                session_id=session_id,
+                cwd=cwd,
+                model=model,
+                requested_provider=requested_provider,
+                base_url=restored_base_url,
+                api_mode=restored_api_mode,
+            )
+        except Exception:
+            logger.warning("Failed to recreate agent for ACP session %s", session_id, exc_info=True)
+            return None
+
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=model or getattr(agent, "model", "") or "",
+            history=history,
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        logger.info("Restored ACP session %s from DB (%d messages)", session_id, len(history))
+        return state
+
+    def _delete_persisted(self, session_id: str) -> bool:
+        """Delete a session from the database. Returns True if it existed."""
+        db = self._get_db()
+        if db is None:
+            return False
+        try:
+            return db.delete_session(session_id)
+        except Exception:
+            logger.debug("Failed to delete ACP session %s from DB", session_id, exc_info=True)
+            return False
+
+    # ---- internal -----------------------------------------------------------
+
+    def _make_agent(
+        self,
+        *,
+        session_id: str,
+        cwd: str,
+        model: str | None = None,
+        requested_provider: str | None = None,
+        base_url: str | None = None,
+        api_mode: str | None = None,
+    ):
+        if self._agent_factory is not None:
+            return self._agent_factory()
+
+        from run_agent import AIAgent
+        from hermes_cli.config import load_config
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+
+        config = load_config()
+        model_cfg = config.get("model")
+        default_model = "anthropic/claude-opus-4.6"
+        config_provider = None
+        if isinstance(model_cfg, dict):
+            default_model = str(model_cfg.get("default") or default_model)
+            config_provider = model_cfg.get("provider")
+        elif isinstance(model_cfg, str) and model_cfg.strip():
+            default_model = model_cfg.strip()
+
+        kwargs = {
+            "platform": "acp",
+            "enabled_toolsets": ["hermes-acp"],
+            "quiet_mode": True,
+            "session_id": session_id,
+            "model": model or default_model,
+        }
+
+        try:
+            runtime = resolve_runtime_provider(requested=requested_provider or config_provider)
+            kwargs.update(
+                {
+                    "provider": runtime.get("provider"),
+                    "api_mode": api_mode or runtime.get("api_mode"),
+                    "base_url": base_url or runtime.get("base_url"),
+                    "api_key": runtime.get("api_key"),
+                    "command": runtime.get("command"),
+                    "args": list(runtime.get("args") or []),
+                }
+            )
+        except Exception:
+            logger.debug("ACP session falling back to default provider resolution", exc_info=True)
+
+        _register_task_cwd(session_id, cwd)
+        return AIAgent(**kwargs)

hermes_code/acp_adapter/tools.py

@@ -0,0 +1,215 @@
+"""ACP tool-call helpers for mapping hermes tools to ACP ToolKind and building content."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, List, Optional
+
+import acp
+from acp.schema import (
+    ToolCallLocation,
+    ToolCallStart,
+    ToolCallProgress,
+    ToolKind,
+)
+
+# ---------------------------------------------------------------------------
+# Map hermes tool names -> ACP ToolKind
+# ---------------------------------------------------------------------------
+
+TOOL_KIND_MAP: Dict[str, ToolKind] = {
+    # File operations
+    "read_file": "read",
+    "write_file": "edit",
+    "patch": "edit",
+    "search_files": "search",
+    # Terminal / execution
+    "terminal": "execute",
+    "process": "execute",
+    "execute_code": "execute",
+    # Web / fetch
+    "web_search": "fetch",
+    "web_extract": "fetch",
+    # Browser
+    "browser_navigate": "fetch",
+    "browser_click": "execute",
+    "browser_type": "execute",
+    "browser_snapshot": "read",
+    "browser_vision": "read",
+    "browser_scroll": "execute",
+    "browser_press": "execute",
+    "browser_back": "execute",
+    "browser_close": "execute",
+    "browser_get_images": "read",
+    # Agent internals
+    "delegate_task": "execute",
+    "vision_analyze": "read",
+    "image_generate": "execute",
+    "text_to_speech": "execute",
+    # Thinking / meta
+    "_thinking": "think",
+}
+
+
+def get_tool_kind(tool_name: str) -> ToolKind:
+    """Return the ACP ToolKind for a hermes tool, defaulting to 'other'."""
+    return TOOL_KIND_MAP.get(tool_name, "other")
+
+
+def make_tool_call_id() -> str:
+    """Generate a unique tool call ID."""
+    return f"tc-{uuid.uuid4().hex[:12]}"
+
+
+def build_tool_title(tool_name: str, args: Dict[str, Any]) -> str:
+    """Build a human-readable title for a tool call."""
+    if tool_name == "terminal":
+        cmd = args.get("command", "")
+        if len(cmd) > 80:
+            cmd = cmd[:77] + "..."
+        return f"terminal: {cmd}"
+    if tool_name == "read_file":
+        return f"read: {args.get('path', '?')}"
+    if tool_name == "write_file":
+        return f"write: {args.get('path', '?')}"
+    if tool_name == "patch":
+        mode = args.get("mode", "replace")
+        path = args.get("path", "?")
+        return f"patch ({mode}): {path}"
+    if tool_name == "search_files":
+        return f"search: {args.get('pattern', '?')}"
+    if tool_name == "web_search":
+        return f"web search: {args.get('query', '?')}"
+    if tool_name == "web_extract":
+        urls = args.get("urls", [])
+        if urls:
+            return f"extract: {urls[0]}" + (f" (+{len(urls)-1})" if len(urls) > 1 else "")
+        return "web extract"
+    if tool_name == "delegate_task":
+        goal = args.get("goal", "")
+        if goal and len(goal) > 60:
+            goal = goal[:57] + "..."
+        return f"delegate: {goal}" if goal else "delegate task"
+    if tool_name == "execute_code":
+        return "execute code"
+    if tool_name == "vision_analyze":
+        return f"analyze image: {args.get('question', '?')[:50]}"
+    return tool_name
+
+
+# ---------------------------------------------------------------------------
+# Build ACP content objects for tool-call events
+# ---------------------------------------------------------------------------
+
+
+def build_tool_start(
+    tool_call_id: str,
+    tool_name: str,
+    arguments: Dict[str, Any],
+) -> ToolCallStart:
+    """Create a ToolCallStart event for the given hermes tool invocation."""
+    kind = get_tool_kind(tool_name)
+    title = build_tool_title(tool_name, arguments)
+    locations = extract_locations(arguments)
+
+    if tool_name == "patch":
+        mode = arguments.get("mode", "replace")
+        if mode == "replace":
+            path = arguments.get("path", "")
+            old = arguments.get("old_string", "")
+            new = arguments.get("new_string", "")
+            content = [acp.tool_diff_content(path=path, new_text=new, old_text=old)]
+        else:
+            # Patch mode — show the patch content as text
+            patch_text = arguments.get("patch", "")
+            content = [acp.tool_content(acp.text_block(patch_text))]
+        return acp.start_tool_call(
+            tool_call_id, title, kind=kind, content=content, locations=locations,
+            raw_input=arguments,
+        )
+
+    if tool_name == "write_file":
+        path = arguments.get("path", "")
+        file_content = arguments.get("content", "")
+        content = [acp.tool_diff_content(path=path, new_text=file_content)]
+        return acp.start_tool_call(
+            tool_call_id, title, kind=kind, content=content, locations=locations,
+            raw_input=arguments,
+        )
+
+    if tool_name == "terminal":
+        command = arguments.get("command", "")
+        content = [acp.tool_content(acp.text_block(f"$ {command}"))]
+        return acp.start_tool_call(
+            tool_call_id, title, kind=kind, content=content, locations=locations,
+            raw_input=arguments,
+        )
+
+    if tool_name == "read_file":
+        path = arguments.get("path", "")
+        content = [acp.tool_content(acp.text_block(f"Reading {path}"))]
+        return acp.start_tool_call(
+            tool_call_id, title, kind=kind, content=content, locations=locations,
+            raw_input=arguments,
+        )
+
+    if tool_name == "search_files":
+        pattern = arguments.get("pattern", "")
+        target = arguments.get("target", "content")
+        content = [acp.tool_content(acp.text_block(f"Searching for '{pattern}' ({target})"))]
+        return acp.start_tool_call(
+            tool_call_id, title, kind=kind, content=content, locations=locations,
+            raw_input=arguments,
+        )
+
+    # Generic fallback
+    import json
+    try:
+        args_text = json.dumps(arguments, indent=2, default=str)
+    except (TypeError, ValueError):
+        args_text = str(arguments)
+    content = [acp.tool_content(acp.text_block(args_text))]
+    return acp.start_tool_call(
+        tool_call_id, title, kind=kind, content=content, locations=locations,
+        raw_input=arguments,
+    )
+
+
+def build_tool_complete(
+    tool_call_id: str,
+    tool_name: str,
+    result: Optional[str] = None,
+) -> ToolCallProgress:
+    """Create a ToolCallUpdate (progress) event for a completed tool call."""
+    kind = get_tool_kind(tool_name)
+
+    # Truncate very large results for the UI
+    display_result = result or ""
+    if len(display_result) > 5000:
+        display_result = display_result[:4900] + f"\n... ({len(result)} chars total, truncated)"
+
+    content = [acp.tool_content(acp.text_block(display_result))]
+    return acp.update_tool_call(
+        tool_call_id,
+        kind=kind,
+        status="completed",
+        content=content,
+        raw_output=result,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Location extraction
+# ---------------------------------------------------------------------------
+
+
+def extract_locations(
+    arguments: Dict[str, Any],
+) -> List[ToolCallLocation]:
+    """Extract file-system locations from tool arguments."""
+    locations: List[ToolCallLocation] = []
+    path = arguments.get("path")
+    if path:
+        line = arguments.get("offset") or arguments.get("line")
+        locations.append(ToolCallLocation(path=path, line=line))
+    return locations