regcode 0.1.0__py3-none-any.whl

regcode/main.py

@@ -0,0 +1,893 @@
+"""Core coding agent using litellm for LLM calls with tool support."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable
+
+import litellm
+
+from regcode.config import Config
+from regcode.conversation_manager import ConversationManager
+from regcode.monty_sandbox import MontySandbox, MontySandboxConfig
+from regcode.permissions import _TOOL_PERMISSIONS, AgentPermission
+from regcode.sandbox import Sandbox, SandboxConfig
+from regcode.tools.base import ToolResult
+from regcode.tools.builtins import create_default_tools
+from regcode.tools.registry import ToolRegistry
+from regcode.tools.review_notes import AddReviewNoteTool, ReadReviewNotesTool
+
+
+class _SafeEncoder(json.JSONEncoder):
+    def default(self, o):
+        if hasattr(o, "__repr__"):
+            return f"<{type(o).__name__}: {o}>"
+        return super().default(o)
+
+
+class AgentStatus(Enum):
+    """Agent status for status callback notifications."""
+
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    IDLE = "idle"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+
+
+class ToolCall:
+    """Represents a tool call from the agent to a specific tool with arguments."""
+
+    def __init__(self, tool_name: str, tool_args: dict | None = None):
+        self.tool_name = tool_name
+        self.tool_args = tool_args or {}
+
+    def __repr__(self) -> str:
+        return f"ToolCall({self.tool_name!r}, {self.tool_args})"
+
+
+class Agent:
+    """Core coding agent using litellm for LLM calls with tool support."""
+
+    def __init__(
+        self,
+        config: Config | None = None,
+        sandbox_config: SandboxConfig | None = None,
+        directory: str | None = None,
+        status_callback: Callable[[AgentStatus, ToolCall | None], None] | None = None,
+        result_callback: (
+            Callable[[AgentStatus, str, bool, ToolCall | None], None]
+            | None
+        )
+        | None = None,
+    ) -> None:
+        self.config = config or Config.load()
+        self.system_prompt = self.config.system_prompt
+        self._history: list[dict[str, Any]] = []
+        self.registry = ToolRegistry()
+        self._status_callback = status_callback
+        self._result_callback = result_callback
+        self._allowed_dir = directory
+        self._tool_budget = self.config.tool_budget
+        self._tool_budget_remaining = self._tool_budget
+        self._tool_budget_exhausted = False
+
+        # Context window manager
+        self.context_manager = ConversationManager()
+
+        # Review note tools - only register when compaction is enabled
+        if self.config.agent.enable_compaction:
+            self.registry.register(
+                AddReviewNoteTool(context_manager=self.context_manager)
+            )
+            self.registry.register(
+                ReadReviewNotesTool(context_manager=self.context_manager)
+            )
+
+        # Use MontySandbox if configured, otherwise fall back to old Sandbox
+        if self.config.sandbox.use_monty:
+            monty_config = MontySandboxConfig(
+                sandbox_dir=Path(directory or "."),
+                max_duration_secs=self.config.sandbox.max_duration_secs,
+                max_memory_mb=self.config.sandbox.max_memory_mb,
+                max_recursion_depth=self.config.sandbox.max_recursion_depth,
+            )
+            self.sandbox = MontySandbox(monty_config)
+        else:
+            self.sandbox = Sandbox(sandbox_config or SandboxConfig())
+
+        for tool in create_default_tools():
+            self.registry.register(tool)
+
+        # Apply permission filtering after tools are registered
+        self._filter_tools_by_permissions()
+
+    def _filter_tools_by_permissions(self) -> None:
+        """Disable tools that don't have the required permission."""
+        perms = self.config.permissions
+        for tool_name, required_perms in _TOOL_PERMISSIONS.items():
+            has_all = all(
+                p in perms or AgentPermission.ALL in perms
+                for p in required_perms
+            )
+            if not has_all:
+                self.registry.disable_tool(tool_name)
+
+    def _format_tool_descriptions(self) -> str:
+        """Format tool definitions for inclusion in system prompts.
+
+        Returns a formatted string with each tool's name and description.
+        """
+        tool_defs = self.registry.list_tools()
+        if not tool_defs:
+            return ""
+        lines = []
+        for t in tool_defs:
+            func_info = t.get("function", {})
+            lines.append(
+                f"- {func_info.get('name', '')}: "
+                f"{func_info.get('description', '')}"
+            )
+        header = (
+            "You have access to the following tools.\n"
+            "Use them when appropriate to gather information\n"
+            "or perform tasks:\n"
+        )
+        return header + "\n".join(lines)
+
+    def _format_review_notes(self) -> str:
+        """Format accumulated review notes for inclusion in system prompts."""
+        review_notes = self.context_manager.get_review_notes()
+        if not review_notes:
+            return ""
+        notes_lines = [
+            f"- [{note.get('importance', 'medium')}] {note.get('title')}: "
+            f"{note.get('content', '')}"
+            for note in review_notes
+        ]
+        return "\n\n### Prior Review Notes\n" + "\n".join(notes_lines)
+
+    def dump_history(self, output_file: str = "agent_history.json") -> None:
+        """Dump the agent's conversation history to a JSON file."""
+        with open(output_file, "w") as f:
+            json.dump(self._history, f, indent=2, cls=_SafeEncoder)
+
+    def _build_completion_kwargs(
+        self, messages: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """Build litellm.completion kwargs from messages and config.
+
+        Args:
+            messages: List of message dicts to include in the completion call.
+        """
+        base_kwargs = self.config.get_litellm_completion_kwargs()
+        base_kwargs["messages"] = messages
+        return base_kwargs
+
+    def chat(
+        self,
+        message: str | None = None,
+        stream: bool = False,
+        max_tool_calls: int = 10,
+        messages: list[dict[str, Any]] | None = None,
+        on_text_chunk: Callable[[str], None] | None = None,
+    ) -> str:
+        """Send a message and get a response, with automatic tool use.
+
+        Args:
+            message: User message (required if 'messages' not provided).
+            stream: Whether to stream the final response.
+            max_tool_calls: Maximum number of tool call turns.
+            messages: Pre-built message list (overrides 'message' parameter).
+
+        Returns:
+            The agent's final response string.
+        """
+        if messages is None:
+            if message is None:
+                raise ValueError("Either 'message' or 'messages' must be provided")
+            messages = [
+                {"role": "system", "content": self._build_system_prompt()},
+                *self._history,
+                {"role": "user", "content": message},
+            ]
+
+        # Add messages to context manager for compaction tracking
+        # Only add messages not already in history to avoid double-counting
+        existing_content_keys = {
+            (msg.get("role"), msg.get("content", ""))
+            for msg in self._history
+        }
+        for msg in messages:
+            if (msg.get("role"), msg.get("content", "")) not in existing_content_keys:
+                self.context_manager.add_message(msg)
+
+        # Check if compaction is needed
+        if (
+            self.config.agent.enable_compaction
+            and self.context_manager.should_compact()
+        ):
+            self.context_manager.compact()
+            messages = self.context_manager.get_messages()
+
+        tool_definitions = self.registry.list_tools()
+
+        if stream:
+            return self._stream(messages, tool_definitions, on_text_chunk)
+
+        response_message: dict[str, Any] = {}
+        final_text = ""
+        total_tool_calls = 0
+
+        for _ in range(max_tool_calls):
+            # When budget is exhausted, rebuild system prompt without tools
+            # to prevent the model from hallucinating tool calls
+            if self._tool_budget_exhausted:
+                system_prompt_text = self._build_system_prompt_no_tools()
+                # Replace system prompt in messages with no-tools version
+                messages = [
+                    {"role": "system", "content": system_prompt_text},
+                    *messages[1:],  # Keep everything after system prompt
+                ]
+
+            current_tool_defs = (
+                tool_definitions if not self._tool_budget_exhausted else None
+            )
+
+            completion_kwargs = self._build_completion_kwargs(messages)
+            if current_tool_defs:
+                completion_kwargs["tools"] = current_tool_defs
+                completion_kwargs["tool_choice"] = "auto"
+            elif self._tool_budget_exhausted:
+                # Explicitly tell the LLM no tools are available
+                completion_kwargs["tool_choice"] = "none"
+
+            response = litellm.completion(**completion_kwargs)
+
+            choice = response.choices[0] # type: ignore
+            message_obj = choice.message
+            response_message = {
+                "role": "assistant",
+                "content": message_obj.content or "",
+            }
+            if message_obj.tool_calls:
+                response_message["tool_calls"] = message_obj.tool_calls
+
+            messages.append(response_message)
+
+            # Track final text response
+            if message_obj.content:
+                final_text = message_obj.content
+
+            # If budget was exhausted in a previous iteration, the LLM was
+            # called without tools and returned text. Break and return it.
+            if self._tool_budget_exhausted:
+                break
+
+            # If the model returned actual tool calls, execute them
+            if message_obj.tool_calls and len(message_obj.tool_calls) > 0:
+                for tool_call in message_obj.tool_calls:
+                    # Validate tool call before processing - skip malformed calls
+                    if (not tool_call.id or
+                            not tool_call.function or
+                            not tool_call.function.name):
+                        err_msg = (
+                            "Error: Malformed tool call received from LLM "
+                            "(missing id or function name). Skipping."
+                        )
+                        if tool_call.id:
+                            messages.append({
+                                "role": "tool",
+                                "tool_call_id": tool_call.id,
+                                "name": tool_call.function.name or "unknown",
+                                "content": err_msg,
+                            })
+                        continue
+
+                    tool_name = str(tool_call.function.name)
+                    try:
+                        tool_args = json.loads(tool_call.function.arguments)
+                    except (json.JSONDecodeError, AttributeError):
+                        tool_args = {}
+                        err_msg = (
+                            f"Error: Failed to parse arguments for "
+                            f"tool '{tool_name}'."
+                        )
+                        messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "name": tool_name,
+                            "content": err_msg,
+                        })
+                        continue
+
+                    # Validate path-based arguments against allowed directory
+                    if self._allowed_dir is not None:
+                        for arg_name in ["path", "file_path"]:
+                            if arg_name in tool_args:
+                                arg_path = Path(tool_args[arg_name])
+                                try:
+                                    # Reject absolute paths or paths with '..'
+                                    if arg_path.is_absolute():
+                                        raise ValueError(
+                                            "Access denied: "
+                                            "absolute paths are not allowed"
+                                        )
+                                    if ".." in arg_path.parts:
+                                        raise ValueError(
+                                            "Access denied: "
+                                            "paths with '..' are not allowed"
+                                        )
+                                    if not arg_path.is_absolute():
+                                        arg_path = Path(self._allowed_dir) / arg_path
+                                    # Resolve to get full path
+                                    arg_path = arg_path.resolve()
+                                    if not arg_path.is_relative_to(
+                                        Path(self._allowed_dir).resolve()
+                                    ):
+                                        raise ValueError(
+                                            f"Access denied: '{arg_path}' is outside "
+                                            f"allowed directory '{self._allowed_dir}'"
+                                        )
+                                except ValueError as e:
+                                    # Return error message instead of crashing
+                                    messages.append(
+                                        {
+                                            "role": "tool",
+                                            "tool_call_id": tool_call.id,
+                                            "name": tool_name,
+                                            "content": str(e),
+                                        }
+                                    )
+                                    continue
+
+                    tool_call_obj = ToolCall(tool_name, tool_args)
+                    if self._status_callback is not None:
+                        self._status_callback(AgentStatus.TOOL_CALL, tool_call_obj)
+                    result = self.registry.execute(tool_name, **tool_args)
+                    result_str = str(result)
+                    if self._status_callback is not None:
+                        self._status_callback(AgentStatus.TOOL_RESULT, tool_call_obj)
+                    if self._result_callback is not None:
+                        is_error = "Error" in result_str or "Traceback" in result_str
+                        self._result_callback(
+                            AgentStatus.TOOL_RESULT, result_str, is_error, tool_call_obj
+                        )
+
+                    # Deduct one tool budget from remaining budget
+                    self._tool_budget_remaining -= 1
+                    if self._tool_budget_remaining <= 0:
+                        self._tool_budget_exhausted = True
+                        if self._status_callback is not None:
+                            self._status_callback(
+                                AgentStatus.BUDGET_EXHAUSTED, tool_call_obj
+                            )
+                        messages.append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": tool_call.id,
+                                "name": tool_name,
+                                "content": str(result),
+                            }
+                        )
+                        # Add explicit message telling the agent to stop using
+                        # tools and provide its final response
+                        messages.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    "You have exhausted your tool budget. "
+                                    "Provide your final answer in plain text only. "
+                                    "Do not use any special formatting, tags, or "
+                                    "code markers. Just the answer."
+                                ),
+                            }
+                        )
+                        total_tool_calls += 1
+                        # Continue to the next iteration so the LLM responds
+                        # with text (no tools passed due to _tool_budget_exhausted)
+                        continue
+
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "name": tool_name,
+                            "content": str(result),
+                        }
+                    )
+                    total_tool_calls += 1
+                # Safety: if model keeps calling tools without text, force break
+                if total_tool_calls >= 30:
+                    break
+                continue
+
+            break
+
+        self._history = [m for m in messages if m.get("role") != "system"]
+        return final_text or response_message.get("content", "") or ""
+
+    def _build_system_prompt(self) -> str:
+        """Build the full system prompt including tool definitions."""
+        tool_descriptions = self._format_tool_descriptions()
+        notes_section = self._format_review_notes()
+        return f"{self.system_prompt}{tool_descriptions}{notes_section}"
+
+    def _build_system_prompt_no_tools(self) -> str:
+        """Build the system prompt WITHOUT tool definitions.
+
+        Used when the tool budget is exhausted to prevent the model from
+        hallucinating tool calls based on tool names in the system prompt.
+
+        Review notes are intentionally still included even when tools are
+        stripped, because the accumulated review findings remain relevant
+        context for the LLM's final response.
+        """
+        return f"{self.system_prompt}{self._format_review_notes()}"
+
+    def _stream(
+        self,
+        messages: list[dict],
+        tool_definitions: list[dict[str, Any]] | None = None,
+        on_text_chunk: Callable[[str], None] | None = None,
+    ) -> str:
+        """Stream response with tool support.
+
+        Runs the same tool-call loop as chat() but streams the final
+        text response chunk-by-chunk. Tool calls are executed normally
+        and their results are communicated via the callbacks registered
+        on __init__ (status_callback / result_callback).
+
+        Args:
+            messages: The message list for the completion.
+            tool_definitions: Tool definitions for the LLM.
+            on_text_chunk: Optional callback invoked for each text chunk
+                from the LLM stream. Useful for the CLI to print
+                progressively.
+
+        Returns:
+            The complete final text response.
+        """
+        completion_kwargs = self.config.get_litellm_completion_kwargs()
+        completion_kwargs["messages"] = messages
+        if tool_definitions:
+            completion_kwargs["tools"] = tool_definitions
+            completion_kwargs["tool_choice"] = "auto"
+
+        full_text = ""
+        final_text = ""
+        response_message: dict[str, Any] = {}
+        total_tool_calls = 0
+
+        for _ in range(10):
+            # When budget is exhausted, rebuild system prompt without tools
+            if self._tool_budget_exhausted:
+                system_prompt_text = self._build_system_prompt_no_tools()
+                messages = [
+                    {"role": "system", "content": system_prompt_text},
+                    *messages[1:],
+                ]
+
+            current_tool_defs = (
+                tool_definitions if not self._tool_budget_exhausted else None
+            )
+
+            if current_tool_defs:
+                completion_kwargs["tools"] = current_tool_defs
+                completion_kwargs["tool_choice"] = "auto"
+            elif self._tool_budget_exhausted:
+                completion_kwargs["tool_choice"] = "none"
+                # Remove tools key if present
+                completion_kwargs.pop("tools", None)
+
+            completion_kwargs["stream"] = True
+            completion_kwargs["messages"] = messages
+
+            response = litellm.completion(**completion_kwargs)
+
+            # Stream the response — accumulate text and tool_calls
+            # across ALL chunks, not just the last one.
+            full_text = ""
+            # Accumulate delta tool calls by index so we can merge partial
+            # chunks (id in first chunk, function name in second, arguments
+            # accumulating in subsequent chunks) into a single per-call object.
+            accumulated_by_index: dict[int, dict[str, Any]] = {}
+            try:
+                for chunk in response:
+                    delta = chunk.choices[0].delta # type: ignore
+                    # Accumulate text content
+                    if delta.content:
+                        full_text += delta.content
+                        if on_text_chunk:
+                            on_text_chunk(delta.content)
+                    # Accumulate tool calls from any chunk
+                    if delta.tool_calls:
+                        for tc_delta in delta.tool_calls:
+                            idx = tc_delta.index  # type: ignore
+                            if idx not in accumulated_by_index:
+                                accumulated_by_index[idx] = {
+                                    "id": tc_delta.id or "",
+                                    "type": tc_delta.type or "function",
+                                    "function_name": "",
+                                    "function_arguments": "",
+                                }
+                            acc = accumulated_by_index[idx]
+                            if tc_delta.id is not None:
+                                acc["id"] = tc_delta.id
+                            if tc_delta.function is not None:
+                                if tc_delta.function.name:
+                                    acc["function_name"] = tc_delta.function.name
+                                if tc_delta.function.arguments:
+                                    acc["function_arguments"] += (
+                                        tc_delta.function.arguments
+                                    )
+            except Exception:
+                # Litellm's streaming iterator can crash on malformed responses
+                # or sentinel markers like [DONE]. If iteration fails, just use
+                # whatever text we accumulated so far.
+                pass
+
+            # Reconstruct tool call dicts from accumulated chunks and validate
+            valid_tool_calls = []
+            for idx, acc in accumulated_by_index.items():
+                if not acc.get("id") or not acc.get("function_name"):
+                    continue
+                valid_tool_calls.append({
+                    "id": acc["id"],
+                    "type": acc["type"],
+                    "index": idx,
+                    "function": {
+                        "name": acc["function_name"],
+                        "arguments": acc["function_arguments"],
+                    },
+                })
+
+            response_message = {
+                "role": "assistant",
+                "content": full_text or "",
+            }
+
+            # Attach only valid accumulated tool calls
+            if valid_tool_calls:
+                response_message["tool_calls"] = valid_tool_calls
+
+            messages.append(response_message)
+
+            if full_text:
+                final_text = full_text
+
+            if self._tool_budget_exhausted:
+                break
+
+            if valid_tool_calls:
+                for tc_dict in valid_tool_calls:
+                    tool_name = str(tc_dict["function"]["name"])
+                    tool_call_obj = ToolCall(tool_name, {})
+
+                    try:
+                        tool_args = json.loads(tc_dict["function"]["arguments"])
+                    except (json.JSONDecodeError, AttributeError):
+                        tool_args = {}
+                        if self._status_callback is not None:
+                            self._status_callback(AgentStatus.TOOL_CALL, tool_call_obj)
+                        if self._result_callback is not None:
+                            self._result_callback(
+                                AgentStatus.TOOL_RESULT,
+                                (
+                                    f"Error: Failed to parse arguments for "
+                                    f"tool '{tool_name}'."
+                                ),
+                                True,
+                                tool_call_obj,
+                            )
+                        messages.append({
+                            "role": "tool",
+                            "tool_call_id": tc_dict["id"],
+                            "name": tool_name,
+                            "content": (
+                                f"Error: Failed to parse arguments for "
+                                f"tool '{tool_name}'."
+                            ),
+                        })
+                        total_tool_calls += 1
+                        continue
+
+                    if self._allowed_dir is not None:
+                        for arg_name in ["path", "file_path"]:
+                            if arg_name in tool_args:
+                                arg_path = Path(tool_args[arg_name])
+                                try:
+                                    if arg_path.is_absolute():
+                                        raise ValueError(
+                                            "Access denied: "
+                                            "absolute paths are not allowed"
+                                        )
+                                    if ".." in arg_path.parts:
+                                        raise ValueError(
+                                            "Access denied: "
+                                            "paths with '..' are not allowed"
+                                        )
+                                    if not arg_path.is_absolute():
+                                        arg_path = Path(self._allowed_dir) / arg_path
+                                    arg_path = arg_path.resolve()
+                                    if not arg_path.is_relative_to(
+                                        Path(self._allowed_dir).resolve()
+                                    ):
+                                        raise ValueError(
+                                            f"Access denied: '{arg_path}' is outside "
+                                            f"allowed directory '{self._allowed_dir}'"
+                                        )
+                                except ValueError as e:
+                                    messages.append(
+                                        {
+                                            "role": "tool",
+                                            "tool_call_id": tc_dict["id"],
+                                            "name": tool_name,
+                                            "content": str(e),
+                                        }
+                                    )
+                                    continue
+
+                    tool_call_obj = ToolCall(tool_name, tool_args)
+                    if self._status_callback is not None:
+                        self._status_callback(AgentStatus.TOOL_CALL, tool_call_obj)
+                    result = self.registry.execute(tool_name, **tool_args)
+                    result_str = str(result)
+                    if self._status_callback is not None:
+                        self._status_callback(AgentStatus.TOOL_RESULT, tool_call_obj)
+                    if self._result_callback is not None:
+                        is_error = "Error" in result_str or "Traceback" in result_str
+                        self._result_callback(
+                            AgentStatus.TOOL_RESULT, result_str, is_error, tool_call_obj
+                        )
+
+                    self._tool_budget_remaining -= 1
+                    if self._tool_budget_remaining <= 0:
+                        self._tool_budget_exhausted = True
+                        if self._status_callback is not None:
+                            self._status_callback(
+                                AgentStatus.BUDGET_EXHAUSTED, tool_call_obj
+                            )
+                        messages.append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": tc_dict["id"],
+                                "name": tool_name,
+                                "content": str(result),
+                            }
+                        )
+                        messages.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    "You have exhausted your tool budget. "
+                                    "Provide your final answer in plain text only. "
+                                    "Do not use any special formatting, tags, or "
+                                    "code markers. Just the answer."
+                                ),
+                            }
+                        )
+                        total_tool_calls += 1
+                        continue
+
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tc_dict["id"],
+                            "name": tool_name,
+                            "content": str(result),
+                        }
+                    )
+                    total_tool_calls += 1
+                if total_tool_calls >= 30:
+                    break
+                continue
+
+            break
+
+        self._history = [m for m in messages if m.get("role") != "system"]
+        return final_text or response_message.get("content", "") or ""
+
+    def reset(self) -> None:
+        """Clear conversation history."""
+        self._history = []
+        self.context_manager.reset()
+
+    @property
+    def history(self) -> list[dict]:
+        return list(self._history)
+
+    def execute(self, tool_name: str, **kwargs: Any) -> ToolResult:
+        """Execute a tool directly without LLM involvement.
+
+        Args:
+            tool_name: Name of the tool to execute.
+            **kwargs: Parameters to pass to the tool.
+
+        Returns:
+            ToolResult from execution.
+        """
+        return self.registry.execute(tool_name, **kwargs)
+
+    def add_tool(self, tool: Any) -> None:
+        """Add a custom tool to the registry.
+
+        Args:
+            tool: A BaseTool instance to register.
+        """
+        self.registry.register(tool)
+
+    def remove_tool(self, tool_name: str) -> None:
+        """Remove a tool from the registry.
+
+        Args:
+            tool_name: Name of the tool to remove.
+        """
+        self.registry.unregister(tool_name)
+
+    @property
+    def available_tools(self) -> list[str]:
+        """List names of available tools."""
+        return self.registry.enabled_tools
+
+    def _scan_directory_tree(self, root_dir: str) -> str:
+        """Scan a directory and return a tree structure of files and dirs.
+
+        Args:
+            root_dir: The root directory to scan.
+
+        Returns:
+            A formatted string showing the directory tree.
+        """
+        path = Path(root_dir).resolve()
+        if not path.exists():
+            return f"Path not found: {root_dir}"
+        if not path.is_dir():
+            return f"Not a directory: {root_dir}"
+
+        lines: list[str] = []
+        ignore = {"__pycache__", ".git", ".venv", "node_modules", "dist", "build"}
+
+        def _walk(current: Path, prefix: str) -> None:
+            try:
+                entries = sorted(
+                    current.iterdir(),
+                    key=lambda p: (not p.is_dir(), p.name.lower()),
+                )
+            except PermissionError:
+                return
+
+            for idx, entry in enumerate(entries):
+                is_last = idx == len(entries) - 1
+                connector = "└── " if is_last else "├── "
+                lines.append(f"{prefix}{connector}{entry.name}")
+
+                if entry.is_dir() and entry.name not in ignore:
+                    child_prefix = prefix + ("    " if is_last else "│   ")
+                    _walk(entry, child_prefix)
+
+        lines.append(f"{path.name}/")
+        _walk(path, "  ")
+        return "\n".join(lines)
+
+    def _build_code_review_system_prompt(self, dir_tree: str) -> str:
+        """Build an enhanced system prompt for code review tasks.
+
+        Args:
+            dir_tree: The directory tree string to include in the prompt.
+
+        Returns:
+            The enhanced system prompt string.
+        """
+        base_prompt = self.system_prompt
+
+        tool_descriptions = self._format_tool_descriptions()
+
+        # Build a focused code review prompt
+        review_instructions = (
+            "You are a senior code reviewer specializing in Python, "
+            "FastAPI, and modern web development. Your task is to provide "
+            "thorough code reviews.\n\n"
+            "Before reviewing, scan the project structure to understand "
+            "the codebase architecture. Focus on:\n"
+            "- Code quality and readability\n"
+            "- Security vulnerabilities\n"
+            "- Performance issues\n"
+            "- Architectural concerns\n"
+            "- Best practices adherence\n"
+            "- Potential bugs and edge cases\n"
+            "Be constructive, specific, and actionable in your feedback. "
+            "Reference file paths and line numbers where possible. "
+            "THE PROJECT ROOT IS `.` — all paths in the tree are RELATIVE to it. "
+            "When calling read_file, use the path as shown in the tree (e.g., "
+            "`regcode/__init__.py`, `tests/conftest.py`). DO NOT add extra "
+            "directory prefixes.\n"
+            "CAUTION: do NOT ask for tool calls in <tool_call> format.\n"
+        )
+
+        # Append review notes so they survive compaction
+        notes_section = self._format_review_notes()
+
+        return (
+            f"{base_prompt}\n{review_instructions}\n"
+            "--- Project Structure ---\n"
+            f"{dir_tree}\n"
+            f"{tool_descriptions}{notes_section}"
+        )
+
+    def code_review(
+        self,
+        code_root_dir: str = ".",
+        max_tool_calls: int = 20,
+        stream: bool = False,
+        extra_instructions: str | None = None,
+        review_instruction: str | None = None,
+    ) -> str:
+        """Perform a code review on the given directory.
+
+        Scans the directory structure first, then engages the LLM with an
+        enhanced system prompt that includes the directory tree and
+        code-review-specific instructions.
+
+        Args:
+            code_root_dir: The root directory to review.
+            max_tool_calls: Maximum number of tool call turns.
+            stream: Whether to stream the final response.
+            extra_instructions: Optional additional instructions for the
+                code review. If None, uses the default message:
+                ``"Please review the code in this project. Start by
+                examining the project structure, then provide a thorough
+                code review."``
+            review_instruction: Deprecated. Use ``extra_instructions``
+                instead. Kept for backward compatibility.
+
+        Returns:
+            The agent's review response string.
+        """
+        if review_instruction is not None:
+            warnings.warn(
+                "The 'review_instruction' parameter is deprecated; "
+                "use 'extra_instructions' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if extra_instructions is None:
+                extra_instructions = review_instruction
+        # Scan the directory structure
+        dir_tree = self._scan_directory_tree(code_root_dir)
+
+        # Build enhanced system prompt with directory structure
+        system_prompt = self._build_code_review_system_prompt(dir_tree)
+
+        # Build user message
+        user_message = extra_instructions or (
+            "Please review the code in this project. "
+            "Start by examining the project structure, then provide "
+            "a thorough code review."
+        )
+
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system_prompt},
+            *self._history,
+            {"role": "user", "content": user_message},
+        ]
+
+        return self.chat(
+            messages=messages,
+            max_tool_calls=max_tool_calls,
+            stream=stream,
+        )
+
+    def cleanup(self) -> None:
+        """Clean up sandbox resources."""
+        self.sandbox.cleanup()
+
+    def __enter__(self) -> "Agent":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context manager."""
+        self.cleanup()