ata-coder 2.4.2__py3-none-any.whl

ata_coder/tools.py

@@ -0,0 +1,1576 @@
+"""
+Tool system for the ATA Coder.
+
+Provides a set of tools the agent can use:
+- read_file: Read file contents
+- write_file: Create or overwrite a file
+- edit_file: Precise string replacement in a file
+- run_shell: Execute a shell command
+- grep: Search file contents with regex
+- glob: Find files matching a pattern
+- list_dir: List directory contents
+- web_search: Search the web (optional)
+"""
+
+import asyncio
+import html
+import html.parser
+import logging
+import os
+import re
+import shutil
+import subprocess
+import fnmatch
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from .config import AgentConfig
+from .clawd_integration import get_clawd
+
+logger = logging.getLogger(__name__)
+
+
+# ── Tool result type ─────────────────────────────────────────────────────────
+
+class ToolResult:
+    """Result of executing a tool."""
+
+    def __init__(self, success: bool, output: str, error: str = ""):
+        self.success = success
+        self.output = output
+        self.error = error
+
+    def to_message(self) -> str:
+        """Format as a message to the LLM."""
+        if self.success:
+            return self.output
+        return f"Error: {self.error}\n\n{self.output}".strip()
+
+    def to_tool_result(self, tool_call_id: str) -> dict:
+        """Format as an OpenAI tool result message."""
+        return {
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": self.to_message(),
+        }
+
+
+# ── Tool definitions (OpenAI function format) ────────────────────────────────
+# Extracted to tool_defs.py to keep this file under 1600 lines.
+
+from .tool_defs import TOOL_DEFINITIONS  # noqa: E402
+
+# TOOL_DEFINITIONS are now in tool_defs.py (extracted to keep this file focused
+# on implementations). The import above re-exports them transparently.
+
+# ── Tool implementations ─────────────────────────────────────────────────────
+
+class ToolExecutor:
+    """Executes tool calls and manages workspace context."""
+
+    # Result limits
+    MAX_GREP_RESULTS = 100
+    MAX_GREP_PER_FILE = 20
+    MAX_GLOB_RESULTS = 200
+    MAX_DIR_ENTRIES = 500
+
+    # Directories to skip during recursive operations
+    SKIP_DIRS = {
+        "node_modules", "__pycache__", ".git", "venv", ".venv",
+        "dist", "build", "target", ".next", ".pytest_cache",
+    }
+
+    def __init__(self, config: AgentConfig | None = None):
+        self.config = config or AgentConfig()
+        self.workspace = Path(self.config.workspace_dir).resolve()
+        self._mcp = None  # set via set_mcp_client()
+        self._edit_callback: Callable[[str, str], None] | None = None
+        # File read cache: path -> (mtime, content).  "只读一遍" — files
+        # are read from disk once per session and served from memory after.
+        self._file_cache: dict[str, tuple[float, str]] = {}
+        self._file_cache_max_entries = 50  # LRU eviction threshold
+        self._cache_dir: Path | None = None
+        # Sub-agent manager (set by agent)
+        self._sub_agent_mgr: Any = None
+        # Pre-built handler map (validated at init time)
+        self._handlers: dict[str, Callable] = self._build_handlers()
+
+    def _build_handlers(self) -> dict[str, Callable]:
+        """Build a dispatch table: tool_name → handler callable."""
+        handlers: dict[str, Callable] = {}
+        for name in dir(self):
+            if name.startswith("_tool_"):
+                tool_name = name[len("_tool_"):]
+                handlers[tool_name] = getattr(self, name)
+        return handlers
+
+    def set_sub_agent_manager(self, mgr: Any) -> None:
+        """Set the SubAgentManager for spawn/collect sub-agent tool support."""
+        self._sub_agent_mgr = mgr
+
+    def set_mcp_client(self, mcp: Any) -> None:
+        """Set the MCPClient for mcp_search tool support."""
+        self._mcp = mcp
+
+    def setup_file_cache(self, cache_dir: str | Path) -> None:
+        """Create session cache directory. Call once before running the agent."""
+        self._cache_dir = Path(cache_dir)
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def clear_file_cache(self) -> None:
+        """Remove all cached files and the cache directory."""
+        self._file_cache.clear()
+        if self._cache_dir and self._cache_dir.exists():
+            shutil.rmtree(self._cache_dir, ignore_errors=True)
+            self._cache_dir = None
+
+    def close(self) -> None:
+        """Release all held resources (httpx clients, file caches)."""
+        self.clear_file_cache()
+        if hasattr(self, "_http") and self._http is not None:
+            try:
+                self._http.close()
+            except Exception:
+                pass
+            self._http = None
+
+    def __del__(self) -> None:
+        """Safety net: ensure httpx client is closed on GC."""
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def on_edit(self, callback: Callable[[str, str], None]) -> None:
+        """Register callback for edit notifications: callback(file_path, old_content)."""
+        self._edit_callback = callback
+
+    def _notify_edit(self, file_path: str, old_content: str) -> None:
+        """Notify the UI of a file edit for diff display."""
+        if self._edit_callback:
+            try:
+                self._edit_callback(file_path, old_content)
+            except Exception:
+                logger.exception("Edit callback failed for %s", file_path)
+
+    def _resolve_path(self, file_path: str) -> Path:
+        """Resolve a file path relative to workspace.
+
+        Raises ValueError if the resolved path escapes the workspace via
+        path traversal (e.g., ``../../etc/passwd``).
+        """
+        p = Path(file_path)
+        if not p.is_absolute():
+            p = self.workspace / p
+        resolved = p.resolve()
+        try:
+            resolved.relative_to(self.workspace.resolve())
+        except ValueError:
+            raise ValueError(
+                f"Path traversal blocked: {file_path} → {resolved} "
+                f"is outside workspace {self.workspace}"
+            )
+        return resolved
+
+    def _ensure_in_workspace(self, path: Path) -> Path:
+        """
+        Ensure path is within workspace for safety.
+        For files outside workspace, allow with a warning.
+        """
+        try:
+            path.resolve().relative_to(self.workspace)
+        except ValueError:
+            logger.warning("Path outside workspace: %s", path)
+        return path
+
+    # Global output cap — every tool result is trimmed to this many chars.
+    # ~25k tokens, still generous for legitimate work but prevents a single
+    # result from eating the whole context window.
+    MAX_OUTPUT_CHARS = 100_000
+
+    async def execute(self, tool_name: str, arguments: dict[str, Any]) -> ToolResult:
+        """Dispatch a tool call to the appropriate handler.
+
+        All results are capped at MAX_OUTPUT_CHARS to prevent any single
+        tool response from blowing up the conversation context.
+        """
+        handler = self._handlers.get(tool_name)
+        if handler is None:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Unknown tool: {tool_name}",
+            )
+        try:
+            result = await handler(**arguments)
+        except Exception as e:
+            logger.exception("Tool %s failed", tool_name)
+            return ToolResult(
+                success=False, output="", error=f"{type(e).__name__}: {e}"
+            )
+
+        # ── Global size cap ──────────────────────────────────────────
+        if len(result.output) > self.MAX_OUTPUT_CHARS:
+            original_len = len(result.output)
+            cut = result.output[:self.MAX_OUTPUT_CHARS]
+            result.output = (
+                cut + f"\n\n... [truncated {original_len - self.MAX_OUTPUT_CHARS:,} "
+                f"chars — result was {original_len:,} chars total]"
+            )
+            logger.warning(
+                "Tool %s output truncated: %d → %d chars",
+                tool_name, original_len, self.MAX_OUTPUT_CHARS,
+            )
+
+        return result
+
+    # ── File tools ───────────────────────────────────────────────────────────
+
+    # ── Output limits (prevent token bloat from large file reads) ──────
+    MAX_READ_LINES = 2000        # auto-truncate reads without an explicit limit
+    MAX_READ_CHARS = 80_000      # hard cap on output chars (~20k tokens)
+
+    async def _tool_read_file(
+        self,
+        file_path: str,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> ToolResult:
+        """Read a file with optional line range.
+
+        When *limit* is not set, output is capped at MAX_READ_LINES to
+        prevent a single file read from eating tens of thousands of context
+        tokens.  Use *offset* + *limit* to page through larger files.
+        """
+        path = self._resolve_path(file_path)
+        if not path.exists():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"File not found: {path}",
+            )
+        if path.is_dir():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Path is a directory, not a file: {path}",
+            )
+
+        # ── File cache: "只读一遍" — return short note on re-read ────
+        cache_key = str(path.resolve())
+        current_mtime = path.stat().st_mtime
+        needs_disk_read = True
+
+        if cache_key in self._file_cache:
+            cached_mtime, cached_content = self._file_cache[cache_key]
+            if cached_mtime == current_mtime:
+                if offset is not None or limit is not None:
+                    # Specific section — serve from memory, skip disk
+                    needs_disk_read = False
+                    lines = cached_content.splitlines(keepends=True)
+                    if lines and not lines[-1].endswith("\n"):
+                        lines[-1] += "\n"
+                else:
+                    # Whole file re-read — DON'T send content again
+                    total = cached_content.count("\n") + 1
+                    chars = len(cached_content)
+                    return ToolResult(
+                        success=True,
+                        output=(
+                            f"[cached] {file_path} — {total} lines, {chars:,} chars.\n"
+                            f"Already in conversation context from earlier read. "
+                            f"Use offset/limit to read specific sections if needed."
+                        ),
+                    )
+
+        if needs_disk_read:
+            try:
+                with open(path, "r", encoding="utf-8", errors="replace") as f:
+                    raw = f.read()
+            except Exception as e:
+                return ToolResult(
+                    success=False, output="", error=f"Cannot read file: {e}"
+                )
+            self._file_cache[cache_key] = (current_mtime, raw)
+            # LRU eviction: drop oldest entries when cache exceeds limit
+            if len(self._file_cache) > self._file_cache_max_entries:
+                overflow = len(self._file_cache) - self._file_cache_max_entries
+                oldest = list(self._file_cache.keys())[:overflow]
+                for k in oldest:
+                    del self._file_cache[k]
+            lines = raw.splitlines(keepends=True)
+            if lines and not lines[-1].endswith("\n"):
+                lines[-1] += "\n"
+            # Mirror to disk cache dir if configured
+            if self._cache_dir:
+                # Cross-platform safe filename: strip drive letter on Windows,
+                # replace path separators with underscores
+                resolved = str(path.resolve())
+                if len(resolved) >= 2 and resolved[1] == ":":
+                    resolved = resolved[2:]  # strip "C:"
+                safe_name = resolved.lstrip("\\/").replace("\\", "_").replace("/", "_")
+                try:
+                    (self._cache_dir / safe_name).write_text(raw, encoding="utf-8")
+                except Exception:
+                    pass
+
+        total_lines = len(lines)
+        user_specified_range = limit is not None
+
+        # Default cap: when the caller didn't ask for a specific range,
+        # truncate to MAX_READ_LINES so one file doesn't blow the context.
+        effective_limit = limit if user_specified_range else min(
+            len(lines), self.MAX_READ_LINES
+        )
+
+        start = (offset or 1) - 1
+        end = start + effective_limit
+
+        # Clamp
+        start = max(0, start)
+        end = min(len(lines), end)
+
+        selected = lines[start:end]
+        was_truncated = (end - start) < (total_lines - start) if not user_specified_range else False
+        # Also truncate if the user explicitly asked for a range but total
+        # output still exceeds the hard char cap (safety net).
+        char_truncated = False
+
+        # Format with line numbers
+        output_lines: list[str] = []
+        chars = 0
+        for i, line in enumerate(selected, start=start + 1):
+            formatted = f"{i:6d}\t{line.rstrip()}"
+            chars += len(formatted) + 1  # +1 for newline
+            if chars > self.MAX_READ_CHARS:
+                output_lines.append(f"... (output truncated at {self.MAX_READ_CHARS} chars, use offset/limit to read more)")
+                char_truncated = True
+                break
+            output_lines.append(formatted)
+
+        truncated = was_truncated or char_truncated
+        shown_lines = len(output_lines) - (1 if char_truncated else 0)
+        header = f"File: {path} (lines {start+1}-{start+shown_lines} of {total_lines}"
+        if truncated:
+            header += f", truncated — use offset/limit to page"
+        header += ")\n"
+        return ToolResult(success=True, output=header + "\n".join(output_lines))
+
+    async def _tool_write_file(
+        self, file_path: str, content: str
+    ) -> ToolResult:
+        """Create or overwrite a file. Captures old content for diff display."""
+        path = self._resolve_path(file_path)
+        self._ensure_in_workspace(path)
+
+        # Capture old content for diff (if file exists)
+        old_content = ""
+        if path.exists():
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    old_content = f.read()
+            except Exception:
+                pass
+
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+            size = path.stat().st_size
+
+            # Notify UI for diff display if overwriting
+            if old_content:
+                self._notify_edit(str(path), old_content)
+
+            return ToolResult(
+                success=True,
+                output=f"File written: {path} ({size} bytes, {content.count(chr(10))} lines)",
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="", error=f"Cannot write file: {e}"
+            )
+
+    async def _tool_edit_file(
+        self, file_path: str, old_string: str, new_string: str
+    ) -> ToolResult:
+        """Replace text in a file. Uses CST for Python (preserves formatting),
+        falls back to text replacement for other languages."""
+        if old_string == new_string:
+            return ToolResult(
+                success=False,
+                output="",
+                error="old_string and new_string are identical",
+            )
+
+        path = self._resolve_path(file_path)
+        if not path.exists():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"File not found: {path}",
+            )
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception as e:
+            return ToolResult(
+                success=False, output="", error=f"Cannot read file: {e}"
+            )
+
+        # Store old content for diff display (via UI callback)
+        old_content = content
+
+        # ── CST-based edit for Python files ──────────────────────────────
+        if path.suffix == ".py" or path.suffix == ".pyi":
+            result = self._cst_edit(content, old_string, new_string, path)
+            if result is not None:
+                new_content = result
+                try:
+                    with open(path, "w", encoding="utf-8") as f:
+                        f.write(new_content)
+                    self._notify_edit(str(path), old_content)
+                    return ToolResult(
+                        success=True,
+                        output=f"File edited (AST): {path} (1 replacement)",
+                    )
+                except Exception as e:
+                    return ToolResult(
+                        success=False, output="", error=f"Cannot write file: {e}"
+                    )
+            # CST edit failed — fall through to text-based replacement
+
+        # ── Text-based fallback ──────────────────────────────────────────
+        count = content.count(old_string)
+        if count == 0:
+            return ToolResult(
+                success=False,
+                output="",
+                error="old_string not found in file. Check whitespace/indentation.",
+            )
+        if count > 1:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"old_string found {count} times in file. Must be unique. Use a larger string with more surrounding context.",
+            )
+
+        new_content = content.replace(old_string, new_string, 1)
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+            self._notify_edit(str(path), old_content)
+
+            return ToolResult(
+                success=True,
+                output=f"File edited: {path} (1 replacement)",
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="", error=f"Cannot write file: {e}"
+            )
+
+    @staticmethod
+    def _cst_edit(content: str, old_str: str, new_str: str, path: Any) -> str | None:
+        """Attempt a CST-based edit for Python files using libcst.
+
+        Parses the file as a Concrete Syntax Tree, finds the node matching
+        old_str, replaces it with new_str parsed as the same node type,
+        and returns the formatted code. Preserves ALL formatting.
+
+        Returns None if the edit cannot be performed via CST (fallback to text).
+        """
+        try:
+            import libcst as cst
+        except ImportError:
+            return None  # libcst not installed — use text fallback
+
+        try:
+            tree = cst.parse_module(content)
+        except Exception:
+            return None  # Can't parse — fall back to text
+
+        # Strategy: parse old_str as a statement, find it in the tree, replace
+        try:
+            # Try parsing old_str as a full module body (the typical case for
+            # function/method/class-level edits)
+            old_module = cst.parse_module(old_str + "\n")
+            if len(old_module.body) == 1:
+                old_node = old_module.body[0]
+                # Parse new_str as the same node type
+                new_module = cst.parse_module(new_str + "\n")
+                if len(new_module.body) == 1:
+                    new_node = new_module.body[0]
+                    transformer = _NodeReplacer(old_node, new_node)
+                    new_tree = tree.visit(transformer)
+                    if transformer.found:
+                        return new_tree.code
+        except Exception:
+            pass
+
+        # Strategy 2: try parsing old_str as a simple statement line
+        try:
+            old_module = cst.parse_module(old_str + "\n")
+            if len(old_module.body) == 1:
+                old_stmt = old_module.body[0]
+                # For simple statements, use a body-statement-level replacer
+                new_module = cst.parse_module(new_str + "\n")
+                if len(new_module.body) == 1:
+                    new_stmt = new_module.body[0]
+                    transformer = _StatementReplacer(old_stmt, new_stmt)
+                    new_tree = tree.visit(transformer)
+                    if transformer.found:
+                        return new_tree.code
+        except Exception:
+            pass
+
+        return None  # All CST strategies failed — fall back to text
+
+
+    # ── CST Transformers (libcst optional — guarded at module level) ──────────
+
+    try:
+        import libcst as _cst_lib
+
+        class _NodeReplacer(_cst_lib.CSTTransformer):
+            """Replace a specific CST node with another, preserving all else."""
+
+            def __init__(self, old_node: _cst_lib.CSTNode, new_node: _cst_lib.CSTNode):
+                self.old_node = old_node
+                self.new_node = new_node
+                self.found = False
+
+            def on_visit(self, node: _cst_lib.CSTNode) -> bool:
+                if node.deep_equals(self.old_node) and not self.found:
+                    self.found = True
+                    return False
+                return True
+
+            def on_leave(self, original_node: _cst_lib.CSTNode, updated_node: _cst_lib.CSTNode) -> _cst_lib.CSTNode:
+                if original_node.deep_equals(self.old_node) and self.found:
+                    return self.new_node
+                return updated_node
+
+        class _StatementReplacer(_cst_lib.CSTTransformer):
+            """Replace a statement within a body, matching by deep equality."""
+
+            def __init__(self, old_stmt: _cst_lib.CSTNode, new_stmt: _cst_lib.CSTNode):
+                self.old_stmt = old_stmt
+                self.new_stmt = new_stmt
+                self.found = False
+
+            def leave_SimpleStatementLine(
+                self, original_node: _cst_lib.SimpleStatementLine, updated_node: _cst_lib.SimpleStatementLine
+            ):
+                if not self.found and len(updated_node.body) == 1:
+                    if updated_node.body[0].deep_equals(self.old_stmt):
+                        self.found = True
+                        return updated_node.with_changes(body=[self.new_stmt])
+                return updated_node
+
+    except ImportError:
+        # libcst not installed — AST editing will fall back to text replacement
+        _NodeReplacer = None   # type: ignore
+        _StatementReplacer = None  # type: ignore
+
+    # ── Rename symbol (AST-aware) ────────────────────────────────────────────
+
+    async def _tool_rename_symbol(
+        self, file_path: str, old_name: str, new_name: str,
+        symbol_type: str = "variable"
+    ) -> ToolResult:
+        """Safely rename a Python symbol using libcst AST matching.
+        Never touches strings, comments, or imports of the same name.
+        """
+        if old_name == new_name:
+            return ToolResult(success=False, output="", error="Names are identical.")
+        if not old_name.isidentifier() or not new_name.isidentifier():
+            return ToolResult(success=False, output="", error="Names must be valid Python identifiers.")
+
+        path = self._resolve_path(file_path)
+        if not path.exists():
+            return ToolResult(success=False, output="", error=f"File not found: {path}")
+        if path.suffix not in (".py", ".pyi"):
+            return ToolResult(success=False, output="", error="rename_symbol only works with Python files.")
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except Exception as e:
+            return ToolResult(success=False, output="", error=f"Cannot read file: {e}")
+
+        try:
+            import libcst as cst
+        except ImportError:
+            return ToolResult(success=False, output="", error="libcst not installed. Run: pip install libcst")
+
+        try:
+            tree = cst.parse_module(content)
+        except Exception as e:
+            return ToolResult(success=False, output="", error=f"Cannot parse Python file: {e}")
+
+        # Choose the right renamer for the symbol type
+        if symbol_type == "function":
+            renamer = _FunctionRenamer(old_name, new_name)
+        elif symbol_type == "class":
+            renamer = _ClassRenamer(old_name, new_name)
+        else:
+            renamer = _VariableRenamer(old_name, new_name)
+
+        new_tree = tree.visit(renamer)
+        if not renamer.changes:
+            return ToolResult(success=False, output="", error=f"Symbol '{old_name}' not found in file.")
+
+        new_content = new_tree.code
+        old_content = content
+
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+            self._notify_edit(str(path), old_content)
+            return ToolResult(
+                success=True,
+                output=f"Renamed {renamer.changes} occurrence(s) of '{old_name}' → '{new_name}' in {path}",
+            )
+        except Exception as e:
+            return ToolResult(success=False, output="", error=f"Cannot write file: {e}")
+
+    # ── Shell tool ───────────────────────────────────────────────────────────
+
+    async def _tool_run_shell(
+        self, command: str, timeout: int = 120
+    ) -> ToolResult:
+        """Execute a shell command."""
+        # Safety checks
+        cmd_lower = command.lower().strip()
+
+        # Check blocked patterns (hard block — unforgivable operations)
+        for blocked in self.config.blocked_commands:
+            if blocked.lower() in cmd_lower:
+                return ToolResult(
+                    success=False,
+                    output="",
+                    error=f"Blocked command pattern detected: {blocked}",
+                )
+
+        # Check if first word is allowed (soft warning — safety_guard is the real gate)
+        first_word = command.strip().split()[0] if command.strip() else ""
+        if first_word and first_word not in self.config.allowed_commands:
+            logger.debug("Command '%s' not in allowed_commands whitelist, proceeding", first_word)
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(self.workspace),
+            )
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout
+            )
+            output = stdout_bytes.decode("utf-8", errors="replace")
+            if stderr_bytes:
+                output += f"\n[stderr]\n{stderr_bytes.decode('utf-8', errors='replace')}"
+            returncode = proc.returncode or 0
+            if returncode != 0:
+                output += f"\n[exit code: {returncode}]"
+            return ToolResult(
+                success=returncode == 0,
+                output=output.strip() or "(no output)",
+            )
+        except asyncio.TimeoutError:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Command timed out after {timeout}s",
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="", error=f"Command failed: {e}"
+            )
+
+    # ── Search tools ─────────────────────────────────────────────────────────
+
+    async def _tool_grep(
+        self,
+        pattern: str,
+        path: str | None = None,
+        glob: str | None = None,
+        case_sensitive: bool = False,
+    ) -> ToolResult:
+        """Search file contents with regex."""
+        search_dir = self._resolve_path(path or ".")
+        if not search_dir.exists():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Directory not found: {search_dir}",
+            )
+
+        flags = 0 if case_sensitive else re.IGNORECASE
+        try:
+            regex = re.compile(pattern, flags)
+        except re.error as e:
+            return ToolResult(
+                success=False, output="", error=f"Invalid regex: {e}"
+            )
+
+        # Run filesystem walk + file reads in thread pool to avoid
+        # blocking the asyncio event loop on large codebases.
+        def _do_grep():
+            results: list[str] = []
+            total_matches = 0
+            for root, dirs, files in os.walk(search_dir):
+                dirs[:] = [
+                    d for d in dirs
+                    if not d.startswith(".")
+                    and d not in self.SKIP_DIRS
+                ]
+                for fname in files:
+                    if glob and not fnmatch.fnmatch(fname, glob):
+                        continue
+
+                    full_path = os.path.join(root, fname)
+                    try:
+                        rel_path = os.path.relpath(full_path, self.workspace)
+                    except ValueError:
+                        rel_path = full_path
+
+                    try:
+                        with open(full_path, "r", encoding="utf-8", errors="replace") as fh:
+                            file_lines = fh.readlines()
+                    except Exception:
+                        continue
+
+                    matches_in_file = []
+                    for line_no, line_text in enumerate(file_lines, 1):
+                        if regex.search(line_text):
+                            matches_in_file.append(
+                                f"  {line_no}: {line_text.rstrip()[:200]}"
+                            )
+                            total_matches += 1
+                            if len(matches_in_file) >= self.MAX_GREP_PER_FILE:
+                                matches_in_file.append("  ... (truncated)")
+                                break
+
+                    if matches_in_file:
+                        results.append(f"{rel_path}:")
+                        results.extend(matches_in_file)
+
+                    if len(results) >= self.MAX_GREP_RESULTS:
+                        results.append("... (result limit reached)")
+                        return results, total_matches
+
+                if len(results) >= self.MAX_GREP_RESULTS:
+                    break
+            return results, total_matches
+
+        results, total_matches = await self._run_in_thread(_do_grep)
+
+        if not results:
+            return ToolResult(
+                success=True,
+                output=f"No matches found for pattern: {pattern}",
+            )
+        return ToolResult(
+            success=True,
+            output=f"Found {total_matches} matches:\n\n" + "\n".join(results),
+        )
+
+    async def _tool_glob(
+        self,
+        pattern: str,
+        path: str | None = None,
+    ) -> ToolResult:
+        """Find files by glob pattern."""
+        search_dir = self._resolve_path(path or ".")
+        if not search_dir.exists():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Directory not found: {search_dir}",
+            )
+
+        import glob as glob_mod
+
+        # Auto-add **/ prefix for recursive matching if not already present
+        if "**" not in pattern:
+            pattern = f"**/{pattern}"
+        search_pattern = str(search_dir / pattern)
+        matches = glob_mod.glob(search_pattern, recursive=True)
+
+        if not matches:
+            return ToolResult(
+                success=True, output=f"No files matching: {pattern}"
+            )
+
+        # Sort and format
+        matches.sort()
+        output_lines = []
+        for m in matches[:200]:
+            try:
+                rel = os.path.relpath(m, self.workspace)
+            except ValueError:
+                rel = m
+            size = os.path.getsize(m) if os.path.isfile(m) else 0
+            output_lines.append(f"  {rel}  ({size:,} bytes)")
+
+        if len(matches) > 200:
+            output_lines.append(
+                f"  ... and {len(matches) - 200} more files"
+            )
+
+        return ToolResult(
+            success=True,
+            output=f"Found {len(matches)} files matching '{pattern}':\n"
+            + "\n".join(output_lines),
+        )
+
+    async def _tool_list_dir(
+        self,
+        path: str | None = None,
+        recursive: bool = False,
+    ) -> ToolResult:
+        """List directory contents."""
+        target = self._resolve_path(path or ".")
+        if not target.exists():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Directory not found: {target}",
+            )
+        if not target.is_dir():
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Not a directory: {target}",
+            )
+
+        output_lines = [f"Directory: {target}"]
+        entries: list[str] = []
+
+        if recursive:
+            for root, dirs, files in os.walk(target):
+                dirs[:] = [
+                    d for d in dirs
+                    if not d.startswith(".") and d not in self.SKIP_DIRS
+                ]
+                level = root.replace(str(target), "").count(os.sep)
+                indent = "  " * level
+                if level > 0:
+                    entries.append(f"{indent}{os.path.basename(root)}/")
+                for f in sorted(files):
+                    fp = os.path.join(root, f)
+                    size = os.path.getsize(fp)
+                    entries.append(f"{indent}  {f}  ({size:,}B)")
+        else:
+            items = sorted(target.iterdir(), key=lambda x: (not x.is_dir(), x.name))
+            for item in items:
+                suffix = "/" if item.is_dir() else ""
+                size = ""
+                if item.is_file():
+                    size = f"  ({item.stat().st_size:,}B)"
+                entries.append(f"  {item.name}{suffix}{size}")
+
+        output_lines.extend(entries[:500])
+        if len(entries) > 500:
+            output_lines.append(f"  ... and {len(entries) - 500} more entries")
+
+        return ToolResult(success=True, output="\n".join(output_lines))
+
+
+    # ── Web tools ──────────────────────────────────────────────────────────
+
+    # Internal HTTP client (lazy-init, shared across web tools)
+    _http: httpx.Client | None = None
+
+    async def _run_in_thread(self, func, *args, **kwargs):
+        """Run a sync function in a thread pool to avoid blocking the event loop."""
+        from functools import partial
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, partial(func, *args, **kwargs))
+
+    @property
+    def http(self) -> httpx.Client:
+        if self._http is None:
+            self._http = httpx.Client(
+                timeout=httpx.Timeout(30.0),
+                follow_redirects=True,
+                headers={
+                    "User-Agent": (
+                        "ATA-Coder/2.0 (AI Coding Assistant; "
+                        "+https://github.com/ata-coder/ata-coder)"
+                    ),
+                    "Accept": "text/html,application/xhtml+xml,*/*",
+                    "Accept-Language": "en-US,zh-CN;q=0.9",
+                },
+            )
+        return self._http
+
+    async def _tool_web_search(
+        self,
+        query: str,
+        max_results: int = 10,
+    ) -> ToolResult:
+        """Search the web with tiered fallback: Bing → Baidu → Google.
+
+        All three use web scraping (no API key required).
+        Set ATA_CODER_SEARCH_BACKEND to force a single backend:
+          "bing" / "baidu" / "google" / "duckduckgo"
+        """
+        import os
+        max_results = min(max(max_results, 1), 20)
+        forced = os.environ.get("ATA_CODER_SEARCH_BACKEND", "")
+
+        errors: list[str] = []
+
+        # Build fallback chain: respect forced backend, otherwise tiered
+        if forced:
+            chain = [(forced, getattr(self, f"_search_{forced}", None))]
+        else:
+            chain = [
+                ("Bing",   self._search_bing),
+                ("Baidu",  self._search_baidu),
+                ("Google", self._search_google),
+            ]
+
+        for name, searcher in chain:
+            if searcher is None:
+                errors.append(f"{name}: unsupported backend")
+                continue
+            try:
+                # Run sync search in thread pool to avoid blocking event loop
+                results = await self._run_in_thread(searcher, query)
+                if results:
+                    return self._format_search_results(query, results, max_results, name)
+                errors.append(f"{name} returned no results")
+            except httpx.TimeoutException:
+                errors.append(f"{name} timed out")
+            except httpx.HTTPStatusError as e:
+                errors.append(f"{name} HTTP {e.response.status_code}")
+            except Exception as e:
+                errors.append(f"{name}: {e}")
+
+        return ToolResult(
+            success=False, output="",
+            error=f"Search failed: {'; '.join(errors)}"
+        )
+
+    def _search_bing(self, query: str) -> list[dict[str, str]]:
+        """Search Bing (web scraping, no API key)."""
+        import urllib.parse
+        url = f"https://www.bing.com/search?q={urllib.parse.quote(query)}&setlang=en"
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                          "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+            "Accept-Language": "en-US,en;q=0.9",
+        }
+        resp = self.http.get(url, headers=headers)
+        resp.raise_for_status()
+
+        results: list[dict[str, str]] = []
+        # Bing results are in <li class="b_algo"> blocks
+        blocks = re.findall(
+            r'<li[^>]*class="[^"]*b_algo[^"]*"[^>]*>(.*?)</li>',
+            resp.text, re.DOTALL | re.IGNORECASE,
+        )
+        for block in blocks:
+            # Title + link in <h2><a href="...">title</a></h2>
+            m = re.search(r'<a[^>]*href="([^"]*)"[^>]*>(.*?)</a>', block, re.DOTALL)
+            if not m:
+                continue
+            href = html.unescape(m.group(1).strip())
+            title = re.sub(r'<[^>]+>', '', m.group(2)).strip()
+            if not title or not href.startswith("http"):
+                continue
+            # Snippet in <p> or <div class="b_caption">
+            snippet = ""
+            sm = re.search(
+                r'<(?:p|div)[^>]*class="[^"]*(?:b_caption|b_lineclamp)[^"]*"[^>]*>(.*?)</(?:p|div)>',
+                block, re.DOTALL | re.IGNORECASE,
+            )
+            if sm:
+                snippet = re.sub(r'<[^>]+>', '', sm.group(1)).strip()
+            snippet = html.unescape(snippet)
+            results.append({"title": title, "url": href, "snippet": snippet})
+
+        return results
+
+    def _search_baidu(self, query: str) -> list[dict[str, str]]:
+        """Search Baidu (web scraping, no API key)."""
+        import urllib.parse
+        url = f"https://www.baidu.com/s?wd={urllib.parse.quote(query)}&ie=utf-8"
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                          "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+            "Accept-Language": "zh-CN,zh;q=0.9",
+        }
+        resp = self.http.get(url, headers=headers)
+        resp.raise_for_status()
+
+        results: list[dict[str, str]] = []
+        # Baidu results: <div class="result c-container"> or <div class="c-container">
+        blocks = re.findall(
+            r'<div[^>]*class="[^"]*(?:result|c-container)[^"]*"[^>]*>(.*?)</div>\s*(?=<div[^>]*class="[^"]*(?:result|c-container)|$)',
+            resp.text, re.DOTALL | re.IGNORECASE,
+        )
+        if not blocks:
+            # Fallback: match h3 titles with links
+            blocks = re.findall(
+                r'<div[^>]*class="[^"]*c-container[^"]*"[^>]*>(.*?)</div>',
+                resp.text, re.DOTALL | re.IGNORECASE,
+            )
+
+        for block in blocks:
+            m = re.search(r'<a[^>]*href="([^"]*)"[^>]*>(.*?)</a>', block, re.DOTALL)
+            if not m:
+                continue
+            href = html.unescape(m.group(1).strip())
+            title = re.sub(r'<[^>]+>', '', m.group(2)).strip()
+            if not title or not href.startswith("http"):
+                continue
+            snippet = ""
+            sm = re.search(
+                r'<(?:span|div|p)[^>]*class="[^"]*(?:content-right_[^"]*|c-abstract|content)[^"]*"[^>]*>(.*?)</(?:span|div|p)>',
+                block, re.DOTALL | re.IGNORECASE,
+            )
+            if sm:
+                snippet = re.sub(r'<[^>]+>', '', sm.group(1)).strip()
+            snippet = html.unescape(snippet)
+            results.append({"title": title, "url": href, "snippet": snippet})
+
+        return results
+
+    def _search_google(self, query: str) -> list[dict[str, str]]:
+        """Search Google (web scraping, no API key)."""
+        import urllib.parse
+        url = f"https://www.google.com/search?q={urllib.parse.quote(query)}&hl=en"
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                          "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+            "Accept-Language": "en-US,en;q=0.9",
+        }
+        resp = self.http.get(url, headers=headers)
+        resp.raise_for_status()
+
+        results: list[dict[str, str]] = []
+        # Google results are in <div class="g"> or <div data-sokoban-container>
+        blocks = re.findall(
+            r'<(?:div|li)[^>]*\b(?:class="g\b|data-sokoban-container)[^>]*>(.*?)</(?:div|li)>',
+            resp.text, re.DOTALL | re.IGNORECASE,
+        )
+        for block in blocks:
+            # Title + link: <h3>...<a href="...">title</a></h3>
+            m = re.search(r'<a[^>]*href="(/url\?q=|)([^"&]*)"[^>]*>(.*?)</a>', block, re.DOTALL)
+            if not m:
+                continue
+            href = html.unescape(m.group(2).strip())
+            if not href.startswith("http"):
+                href = "https://www.google.com" + m.group(1) + m.group(2)
+            title = re.sub(r'<[^>]+>', '', m.group(3)).strip()
+            if not title:
+                continue
+            # Snippet: <span class="aCOpRe"> or various other classes
+            snippet = ""
+            sm = re.search(
+                r'<(?:span|div)[^>]*\b(?:class="[^"]*(?:\baCOpRe\b|st\b)[^"]*")[^>]*>(.*?)</(?:span|div)>',
+                block, re.DOTALL | re.IGNORECASE,
+            )
+            if sm:
+                snippet = re.sub(r'<[^>]+>', '', sm.group(1)).strip()
+            snippet = html.unescape(snippet)
+            results.append({"title": title, "url": href, "snippet": snippet})
+
+        return results
+
+    @staticmethod
+    def _format_search_results(
+        query: str, results: list[dict[str, str]], max_results: int, source: str
+    ) -> ToolResult:
+        out = [f"Search results for: {query}  (via {source})\n"]
+        for i, r in enumerate(results[:max_results], 1):
+            out.append(f"{i}. **{html.unescape(r['title'])}**")
+            out.append(f"   {r['url']}")
+            if r.get("snippet"):
+                out.append(f"   {html.unescape(r['snippet'])}")
+            out.append("")
+        return ToolResult(success=True, output="\n".join(out))
+
+    @staticmethod
+    def _parse_ddg_lite(html_text: str) -> list[dict[str, str]]:
+        """Extract search results from DuckDuckGo Lite HTML."""
+        results: list[dict[str, str]] = []
+
+        # DDG Lite: results are in <a> tags with class="result-link"
+        # and snippets in <td class="result-snippet">
+        link_pattern = re.compile(
+            r'<a[^>]*href="([^"]*)"[^>]*class="[^"]*result-link[^"]*"[^>]*>(.*?)</a>',
+            re.DOTALL | re.IGNORECASE,
+        )
+        snippet_pattern = re.compile(
+            r'<td[^>]*class="[^"]*result-snippet[^"]*"[^>]*>(.*?)</td>',
+            re.DOTALL | re.IGNORECASE,
+        )
+
+        links = link_pattern.findall(html_text)
+        snippets = snippet_pattern.findall(html_text)
+
+        for i, (href, title) in enumerate(links):
+            href = html.unescape(href.strip())
+            title = re.sub(r'<[^>]+>', '', title).strip()
+            if not title:
+                continue
+
+            # Pick corresponding snippet
+            snippet = ""
+            if i < len(snippets):
+                snippet = re.sub(r'<[^>]+>', '', snippets[i])
+                snippet = html.unescape(snippet.strip())
+
+            results.append({
+                "title": title,
+                "url": href,
+                "snippet": snippet[:300],
+            })
+
+        return results
+
+    async def _tool_web_fetch(self, url: str) -> ToolResult:
+        """Fetch a URL and extract its text content."""
+        if not url.startswith(("http://", "https://")):
+            return ToolResult(
+                success=False, output="",
+                error=f"Invalid URL: must start with http:// or https://"
+            )
+
+        def _do_fetch():
+            return self.http.get(url)
+
+        try:
+            resp = await self._run_in_thread(_do_fetch)
+            resp.raise_for_status()
+        except httpx.TimeoutException:
+            return ToolResult(
+                success=False, output="",
+                error=f"Request timed out: {url}"
+            )
+        except httpx.HTTPStatusError as e:
+            return ToolResult(
+                success=False, output="",
+                error=f"HTTP {e.response.status_code} for {url}"
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="",
+                error=f"Fetch failed: {e}"
+            )
+
+        content_type = resp.headers.get("content-type", "")
+        if "text/html" not in content_type and "text/plain" not in content_type:
+            return ToolResult(
+                success=False, output="",
+                error=f"Cannot process content type: {content_type}. Only text/html and text/plain are supported."
+            )
+
+        text = self._extract_text(resp.text, url)
+
+        # Truncate
+        MAX_CHARS = 15_000
+        if len(text) > MAX_CHARS:
+            text = text[:MAX_CHARS] + (
+                f"\n\n... [truncated {len(text) - MAX_CHARS:,} "
+                f"chars from {url}]"
+            )
+
+        return ToolResult(
+            success=True,
+            output=f"Content from: {url}\n\n{text}",
+        )
+
+    # ── Sub-agent tools ──────────────────────────────────────────────────
+
+    async def _tool_spawn_subagent(self, task: str, skill: str = "",
+                             model: str = "") -> ToolResult:
+        """Spawn a sub-agent to work on a task in parallel."""
+        if not self._sub_agent_mgr:
+            return ToolResult(
+                success=False, output="",
+                error="SubAgentManager not available. "
+                      "Ensure agent_controller is used.",
+            )
+        try:
+            # Clawd: SubagentStart
+            get_clawd().subagent_start()
+
+            agent_id = self._sub_agent_mgr.spawn(
+                task=task,
+                skill_prompt=skill,
+                model=model or None,
+            )
+            return ToolResult(
+                success=True,
+                output=(
+                    f"Sub-agent spawned: {agent_id}\n"
+                    f"Status: running\n"
+                    f"Active sub-agents: {self._sub_agent_mgr.active_count}\n\n"
+                    f"Use collect_subagent('{agent_id}') to retrieve results, "
+                    f"or list_subagents() to check all statuses."
+                ),
+            )
+        except RuntimeError as e:
+            return ToolResult(
+                success=False, output="",
+                error=f"Cannot spawn sub-agent: {e}",
+            )
+
+    async def _tool_collect_subagent(self, agent_id: str,
+                                timeout: float = 300.0) -> ToolResult:
+        """Collect results from a spawned sub-agent."""
+        if not self._sub_agent_mgr:
+            return ToolResult(
+                success=False, output="",
+                error="SubAgentManager not available.",
+            )
+        result = self._sub_agent_mgr.collect(agent_id, timeout=timeout)
+
+        # Clawd: SubagentStop
+        get_clawd().subagent_stop()
+
+        if result.success:
+            lines = [
+                f"Sub-agent {agent_id} completed successfully.",
+                f"Tool calls: {result.tool_call_count}",
+                f"",
+                f"Result:",
+                result.result or "(empty)",
+            ]
+            return ToolResult(success=True, output="\n".join(lines))
+        else:
+            return ToolResult(
+                success=False,
+                output=f"Sub-agent {agent_id} failed: {result.error}",
+                error=result.error,
+            )
+
+    async def _tool_list_subagents(self) -> ToolResult:
+        """List all sub-agents and their statuses."""
+        if not self._sub_agent_mgr:
+            return ToolResult(
+                success=False, output="",
+                error="SubAgentManager not available.",
+            )
+        agents = self._sub_agent_mgr.list_all()
+        if not agents:
+            return ToolResult(success=True, output="No sub-agents.")
+
+        lines = [f"Sub-agents ({len(agents)} total):", ""]
+        for a in agents:
+            status_icon = {"running": "🔄", "done": "✅",
+                           "failed": "❌", "cancelled": "⏹️"}.get(a.status, "❓")
+            lines.append(
+                f"  {status_icon} {a.id} — {a.status} "
+                f"(tool_calls={a.tool_call_count})"
+            )
+        return ToolResult(success=True, output="\n".join(lines))
+
+    async def _tool_mcp_search(self, query: str, type: str = "all") -> ToolResult:
+        """Search MCP tools and resources across all connected servers."""
+        if not self._mcp:
+            return ToolResult(
+                success=False, output="",
+                error="MCP not configured. Add MCP servers via --mcp-config.",
+            )
+
+        servers = self._mcp.connected_servers
+        if not servers:
+            return ToolResult(success=True, output="No MCP servers connected.")
+
+        lines = [f"MCP search results for '{query}' across {len(servers)} server(s):", ""]
+        found = 0
+
+        if type in ("tools", "all"):
+            tools = self._mcp.search_tools(query, limit=20)
+            if tools:
+                lines.append(f"  Tools ({len(tools)}):")
+                for t in tools:
+                    name = t.get("name", "?")
+                    desc = (t.get("description") or "")[:100]
+                    server = t.get("_mcp_server", "?")
+                    lines.append(f"    ● {name}  @{server}")
+                    if desc:
+                        lines.append(f"      {desc}")
+                found += len(tools)
+            else:
+                lines.append("  Tools: none found")
+
+        if type in ("resources", "all"):
+            resources = self._mcp.search_resources(query, limit=20)
+            if resources:
+                lines.append(f"\n  Resources ({len(resources)}):")
+                for r in resources:
+                    uri = r.get("uri", "?")
+                    name = r.get("name", "")
+                    desc = (r.get("description") or "")[:80]
+                    server = r.get("_mcp_server", "?")
+                    label = name or uri
+                    lines.append(f"    ● {label}  @{server}")
+                    if desc:
+                        lines.append(f"      {desc}")
+                found += len(resources)
+            else:
+                lines.append("\n  Resources: none found")
+
+        if found == 0:
+            return ToolResult(
+                success=True,
+                output=f"No MCP tools or resources found matching '{query}'.\n"
+                       f"Connected servers: {', '.join(servers)}.",
+            )
+
+        return ToolResult(success=True, output="\n".join(lines))
+
+    async def _tool_analyze_image(self, image_path: str, prompt: str = "Describe this image in detail.") -> ToolResult:
+        """Analyze an image using a multimodal vision model.
+
+        Uses the configured vision model, falling back to the main LLM config.
+        Configure via ~/.ata_coder/settings.json:
+          {"vision": {"model": "...", "api_base": "...", "api_key": "..."}}
+        Or env vars: VISION_MODEL, VISION_API_BASE, VISION_API_KEY.
+        """
+        import base64
+        from pathlib import Path
+
+        img_path = Path(image_path)
+        if not img_path.exists():
+            return ToolResult(
+                success=False, output="",
+                error=f"Image not found: {image_path}",
+            )
+
+        ext = img_path.suffix.lower()
+        supported = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+        if ext not in supported:
+            return ToolResult(
+                success=False, output="",
+                error=f"Unsupported image format: {ext}. Supported: {', '.join(sorted(supported))}",
+            )
+
+        try:
+            with open(img_path, "rb") as f:
+                img_b64 = base64.standard_b64encode(f.read()).decode("ascii")
+        except Exception as e:
+            return ToolResult(success=False, output="", error=f"Failed to read image: {e}")
+
+        # ── Resolve vision config ──
+        # Priority: env var > settings.json > main api config
+        from .settings import get_settings
+        settings = get_settings()
+
+        # API key: VISION_API_KEY env > settings.json vision.api_key > main api key
+        api_key = (
+            os.environ.get("VISION_API_KEY", "")
+            or settings.vision_api_key
+            or os.environ.get("ATA_CODER_API_KEY", "")
+            or os.environ.get("OPENAI_API_KEY", "")
+            or settings.api_key
+        )
+        if not api_key:
+            return ToolResult(
+                success=False, output="",
+                error="No API key configured. Set ATA_CODER_API_KEY or add vision.api_key in ~/.ata_coder/settings.json.",
+            )
+
+        # API base: VISION_API_BASE env > settings.json vision.api_base > main base_url
+        api_base = (
+            os.environ.get("VISION_API_BASE", "")
+            or settings.vision_api_base
+            or os.environ.get("ATA_CODER_BASE_URL", "")
+            or os.environ.get("OPENAI_BASE_URL", "")
+            or settings.api_base_url
+        )
+
+        # Model: VISION_MODEL env > settings.json vision.model > main model
+        model = (
+            os.environ.get("VISION_MODEL", "")
+            or settings.vision_model
+            or os.environ.get("ATA_CODER_DEFAULT_MODEL", "")
+            or os.environ.get("OPENAI_MODEL", "")
+            or settings.default_model
+        )
+
+        mime = ext.replace("jpg", "jpeg").replace(".", "image/")
+        body = {
+            "model": model,
+            "messages": [{
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {"type": "image_url", "image_url": {
+                        "url": f"data:{mime};base64,{img_b64}",
+                        "detail": "auto"
+                    }},
+                ]
+            }],
+            "max_tokens": 2048,
+            "temperature": 0.3,
+        }
+
+        try:
+            import json as _json
+            from urllib.request import Request, urlopen
+            from urllib.error import HTTPError
+
+            data = _json.dumps(body).encode("utf-8")
+            req = Request(
+                f"{api_base.rstrip('/')}/chat/completions",
+                data=data,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {api_key}",
+                },
+            )
+            with urlopen(req, timeout=120) as resp:
+                result = _json.loads(resp.read().decode("utf-8"))
+            content = (
+                result.get("choices", [{}])[0]
+                .get("message", {})
+                .get("content", "(no response)")
+            )
+            usage = result.get("usage", {})
+            tokens = usage.get("total_tokens", "?")
+            return ToolResult(
+                success=True,
+                output=f"[Vision: {model} | {tokens} tokens]\n\n{content}",
+            )
+        except HTTPError as e:
+            error_body = e.read().decode("utf-8", errors="replace")[:300]
+            return ToolResult(
+                success=False, output="",
+                error=f"Vision API error {e.code}: {error_body}",
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="",
+                error=f"Vision API call failed: {e}",
+            )
+
+    @staticmethod
+    def _extract_text(html_text: str, url: str = "") -> str:
+        """Strip HTML down to readable text."""
+
+        class _TextExtractor(html.parser.HTMLParser):
+            def __init__(self):
+                super().__init__()
+                self.parts: list[str] = []
+                self._skip_count = 0  # counter for nested skip-tags
+                self._skip_tags = {"script", "style", "noscript", "iframe",
+                                   "nav", "footer", "header", "aside"}
+                self._block_tags = {"div", "p", "h1", "h2", "h3", "h4", "h5",
+                                    "h6", "li", "tr", "section", "article",
+                                    "pre", "blockquote", "table", "ul", "ol",
+                                    "dl", "br", "hr"}
+
+            def handle_starttag(self, tag, attrs):
+                tag = tag.lower()
+                if tag in self._skip_tags:
+                    self._skip_count += 1
+                elif tag in self._block_tags:
+                    self.parts.append("\n")
+
+            def handle_endtag(self, tag):
+                tag = tag.lower()
+                if tag in self._skip_tags and self._skip_count > 0:
+                    self._skip_count -= 1
+                elif tag in self._block_tags:
+                    self.parts.append("\n")
+
+            def handle_data(self, data):
+                if self._skip_count == 0:
+                    text = data.strip()
+                    if text:
+                        self.parts.append(text + " ")
+
+        try:
+            extractor = _TextExtractor()
+            extractor.feed(html_text)
+            raw = "".join(extractor.parts)
+        except Exception:
+            # Fallback: regex strip
+            raw = re.sub(r'<script[^>]*>.*?</script>', '', html_text, flags=re.DOTALL | re.IGNORECASE)
+            raw = re.sub(r'<style[^>]*>.*?</style>', '', raw, flags=re.DOTALL | re.IGNORECASE)
+            raw = re.sub(r'<[^>]+>', ' ', raw)
+            raw = html.unescape(raw)
+
+        # Collapse whitespace
+        raw = re.sub(r'[ \t]+', ' ', raw)
+        raw = re.sub(r'\n{3,}', '\n\n', raw)
+        return raw.strip()
+
+
+# ── Factory ──────────────────────────────────────────────────────────────────
+
+def create_tool_executor(workspace_dir: str | None = None) -> ToolExecutor:
+    """Create a tool executor with the given workspace."""
+    from .config import AgentConfig
+    if workspace_dir:
+        cfg = AgentConfig(workspace_dir=workspace_dir)
+        return ToolExecutor(cfg)
+    return ToolExecutor()
+
+
+# ── CST Renamers (for rename_symbol tool) ───────────────────────────────────
+# These use libcst to safely rename symbols without touching strings or comments.
+
+class _SymbolRenamer:
+    """Base class for CST symbol renamers — shared leave_Name/leave_Call logic."""
+
+    def __init__(self, old_name: str, new_name: str):
+        self.old = old_name
+        self.new = new_name
+        self.changes = 0
+
+    def leave_Name(self, original_node, updated_node):
+        import libcst as cst
+        if isinstance(updated_node, cst.Name) and updated_node.value == self.old:
+            self.changes += 1
+            return updated_node.with_changes(value=self.new)
+        return updated_node
+
+    def leave_Call(self, original_node, updated_node):
+        import libcst as cst
+        if isinstance(updated_node.func, cst.Name) and updated_node.func.value == self.old:
+            self.changes += 1
+            return updated_node.with_changes(func=cst.Name(value=self.new))
+        return updated_node
+
+
+class _VariableRenamer(_SymbolRenamer):
+    """Rename variable references — names only, not touching strings/comments."""
+
+
+class _FunctionRenamer(_SymbolRenamer):
+    """Rename function/method definitions and calls."""
+
+    def leave_FunctionDef(self, original_node, updated_node):
+        import libcst as cst
+        if updated_node.name.value == self.old:
+            self.changes += 1
+            return updated_node.with_changes(name=cst.Name(value=self.new))
+        return updated_node
+
+
+class _ClassRenamer(_SymbolRenamer):
+    """Rename class definitions and constructor calls."""
+
+    def leave_ClassDef(self, original_node, updated_node):
+        import libcst as cst
+        if updated_node.name.value == self.old:
+            self.changes += 1
+            return updated_node.with_changes(name=cst.Name(value=self.new))
+        return updated_node