ata-coder 2.4.2__py3-none-any.whl

ata_coder/tools/executor.py

@@ -0,0 +1,1036 @@
+"""
+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 logging
+import os
+import re
+import shutil
+import fnmatch
+from pathlib import Path
+from typing import Any, Callable
+
+# Cached reference for __del__ — avoids "import asyncio" during interpreter
+# shutdown, which fails with "ImportError: sys.meta_path is None".
+_asyncio_get_running_loop = asyncio.get_running_loop
+
+
+from ..config import AgentConfig
+from .result import ToolResult
+from .web import WebToolsMixin
+from .subagent import SubAgentToolsMixin
+
+logger = logging.getLogger(__name__)
+
+
+# ── Tool result type ─────────────────────────────────────────────────────────
+
+class ToolExecutor(WebToolsMixin, SubAgentToolsMixin):
+    """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",
+        ".mypy_cache", ".ruff_cache", ".tox", ".idea", ".vs",
+        ".vscode", "bower_components", ".terraform", ".eggs",
+        "*.egg-info", "htmlcov", ".coverage", "__pypackages__",
+    }
+
+    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, cached_at, content).
+        # "只读一遍" — files are read from disk once per session and served
+        # from memory after.  Entries older than _FILE_CACHE_TTL seconds are
+        # re-read to catch external modifications that don't update mtime.
+        # LRU eviction: hits refresh position (move-to-end), eviction drops
+        # from front (least-recently-used).
+        self._file_cache: dict[str, tuple[float, float, str]] = {}
+        self._file_cache_max_entries = 50
+        self._FILE_CACHE_TTL = 30.0  # seconds before a cache entry is revalidated
+        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()
+        # Streaming callback: set by agent to receive real-time output chunks
+        self._stream_cb: Callable[[str, str], None] | None = None  # (tool_name, chunk)
+
+    def set_stream_callback(self, cb: Callable[[str, str], None] | None) -> None:
+        """Set callback for real-time tool output streaming.
+
+        ``cb(tool_name, chunk)`` is called with incremental output chunks
+        during long-running tool execution (e.g. run_shell).
+        Set to None to disable streaming.
+        """
+        self._stream_cb = cb
+
+    def _build_handlers(self) -> dict[str, Callable]:
+        """Build a dispatch table: tool_name → handler callable.
+
+        Only registers callable methods — prevents accidental registration
+        of mixin properties, class attributes, or helper objects whose names
+        happen to match the ``_tool_`` prefix.
+        """
+        handlers: dict[str, Callable] = {}
+        for name in dir(self):
+            if name.startswith("_tool_"):
+                attr = getattr(self, name)
+                if callable(attr):
+                    tool_name = name[len("_tool_"):]
+                    handlers[tool_name] = attr
+        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.
+
+        Only calls close() outside an active asyncio event loop — during
+        interpreter shutdown the loop may already be closed, and touching
+        it from __del__ triggers spurious warnings/errors.
+
+        Uses a cached reference to asyncio.get_running_loop (the module-level
+        import at the top of this file) to avoid ``import asyncio`` inside
+        __del__, which fails with ``ImportError: sys.meta_path is None``
+        during interpreter shutdown.
+        """
+        try:
+            _asyncio_get_running_loop()
+        except RuntimeError:
+            # No running loop — safe to close synchronously
+            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 ────
+        import time as _time
+        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_at, cached_content = self._file_cache[cache_key]
+            age = _time.time() - cached_at
+            if age > self._FILE_CACHE_TTL:
+                # TTL expired — re-read from disk to catch external modifications
+                pass  # fall through to needs_disk_read
+            elif cached_mtime == current_mtime:
+                # Refresh LRU position: pop and re-insert moves key to end
+                self._file_cache.pop(cache_key)
+                self._file_cache[cache_key] = (cached_mtime, _time.time(), cached_content)
+                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, _time.time(), raw)
+            # LRU eviction: dict preserves insertion order (Python 3.7+).
+            # Cache hits move entries to the end, so the first keys are
+            # always the least-recently-used ones.
+            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 += ", 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)
+
+        MAX_OUTPUT_BYTES = 500_000  # cap total stdout+stderr to prevent memory exhaustion
+        proc = None
+        try:
+            # DEVNULL on stdin prevents hangs when child processes try to read
+            # from inherited stdin (common cause of "exec task freeze").
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(self.workspace),
+            )
+
+            # Stream stdout+stderr concurrently — avoids pipe-buffer deadlock
+            # and hangs from child processes inheriting pipes.
+            # When a stream_callback is set, emit chunks in real-time so the
+            # user sees command progress instead of waiting for completion.
+            async def _read_stream(stream, chunks: list[bytes]):
+                total = 0
+                while True:
+                    try:
+                        chunk = await stream.read(65536)
+                    except (asyncio.CancelledError, Exception):
+                        return
+                    if not chunk:
+                        return
+                    total += len(chunk)
+                    if total <= MAX_OUTPUT_BYTES:
+                        chunks.append(chunk)
+                    # Real-time streaming to UI
+                    if self._stream_cb:
+                        try:
+                            text = chunk.decode("utf-8", errors="replace")
+                            self._stream_cb("run_shell", text)
+                        except Exception:
+                            pass
+
+            stdout_chunks: list[bytes] = []
+            stderr_chunks: list[bytes] = []
+            stdout_task = asyncio.create_task(_read_stream(proc.stdout, stdout_chunks))
+            stderr_task = asyncio.create_task(_read_stream(proc.stderr, stderr_chunks))
+
+            # Wait for process to exit (with timeout), NOT for pipes to close
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=timeout)
+            except asyncio.TimeoutError:
+                # Kill the process FIRST — sends EOF to pipes, unblocking reader tasks
+                try:
+                    proc.kill()
+                except ProcessLookupError:
+                    pass
+                # Cancel reader tasks AFTER kill (kill unblocks pipe reads)
+                stdout_task.cancel()
+                stderr_task.cancel()
+                try:
+                    await proc.wait()
+                except (ProcessLookupError, Exception):
+                    pass
+                return ToolResult(
+                    success=False, output="",
+                    error=f"Command timed out after {timeout}s",
+                )
+
+            # Process exited — wait briefly for remaining pipe data
+            try:
+                await asyncio.wait_for(stdout_task, timeout=5)
+            except asyncio.TimeoutError:
+                stdout_task.cancel()
+            try:
+                await asyncio.wait_for(stderr_task, timeout=5)
+            except asyncio.TimeoutError:
+                stderr_task.cancel()
+
+            stdout_bytes = b"".join(stdout_chunks)
+            stderr_bytes = b"".join(stderr_chunks)
+            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}]"
+            if len(stdout_bytes) + len(stderr_bytes) >= MAX_OUTPUT_BYTES:
+                output += "\n[output truncated — exceeded 500KB limit]"
+            return ToolResult(
+                success=returncode == 0,
+                output=output.strip() or "(no output)",
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False, output="", error=f"Command failed: {e}"
+            )
+        finally:
+            # Explicitly close pipes to prevent "I/O operation on closed pipe"
+            # during BaseSubprocessTransport.__del__ at GC time.
+            if proc is not None:
+                for pipe in (proc.stdin, proc.stdout, proc.stderr):
+                    if pipe is not None:
+                        try:
+                            pipe.close()
+                        except Exception:
+                            pass
+
+    # ── 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))
+
+
+# ── 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