manual_slop/docs/guide_tools.md

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.