# Guide: Tooling

Overview of the tool dispatch and execution model.

---

The agent is provided two classes of tools: Read-Only MCP Tools, and a Destructive Execution Loop.

## 1. Read-Only Context (MCP Tools)

Implemented in mcp_client.py. These tools allow the AI to selectively expand its knowledge of the codebase without requiring the user to dump entire 10,000-line files into the static context prefix.

### Security & Scope

Every filesystem MCP tool passes its arguments through _resolve_and_check. This function ensures that the requested path falls under one of the allowed directories defined in the GUI's Base Dir configurations. 
If the AI attempts to read or search a path outside the project bounds, the tool safely catches the constraint violation and returns ACCESS DENIED.

### Supplied Tools:

* read_file(path): Returns the raw UTF-8 text of a file.
* list_directory(path): Returns a formatted table of a directory's contents, showing file vs dir and byte sizes.
* search_files(path, pattern): Executes an absolute glob search (e.g., **/*.py) to find specific files.
* get_file_summary(path): Invokes the local summarize.py heuristic parser to get the AST structure of a file without reading the whole body.
* web_search(query): Queries DuckDuckGo's raw HTML endpoint and returns the top 5 results (Titles, URLs, Snippets) using a native HTMLParser to avoid heavy dependencies.
* fetch_url(url): Downloads a target webpage and strips out all scripts, styling, and structural HTML, returning only the raw prose content (clamped to 40,000 characters).

## 2. Destructive Execution (run_powershell)

The core manipulation mechanism. This is a single, heavily guarded tool.

### Flow

1. The AI generates a 'run_powershell' payload containing a PowerShell script.
2. The AI background thread calls confirm_and_run_callback (injected by gui.py).
3. The background thread blocks completely, creating a modal popup on the main GUI thread.
4. The user reads the script and chooses to Approve or Reject.
5. If Approved, shell_runner.py executes the script using -NoProfile -NonInteractive -Command within the specified base_dir.
6. The combined stdout, stderr, and EXIT CODE are captured and returned to the AI in the tool result block.

### AI Guidelines

The core system prompt explicitly guides the AI on how to use this tool safely:

* Prefer targeted replacements (using PowerShell's .Replace()) over full rewrites where possible.
* If a file is large and complex (requiring specific escape characters), do not attempt an inline python -c script. Instead, use a PowerShell here-string (@'...'@) to write a temporary python helper script to disk, execute the python script, and then delete it.

### Synthetic Context Refresh

After the **last** tool call in each round finishes (when multiple tools are called in a single round, the refresh happens once after all of them), ai_client runs `_reread_file_items`. It fetches the latest disk state of all files in the current project context. The `file_items` variable is reassigned so subsequent tool rounds within the same request use the fresh content.

For Anthropic, the refreshed contents are injected as a text block in the `tool_results` user message. For Gemini, they are appended to the last function response's output string. In both cases, the block is prefixed with `[FILES UPDATED]` / `[SYSTEM: FILES UPDATED]`.

On the next tool round, stale file-refresh blocks from previous rounds are stripped from history to prevent token accumulation. This means if the AI writes to a file, it instantly "sees" the modification in its next turn without having to waste a cycle calling `read_file`, and the cost of carrying the full file snapshot is limited to one round.