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:

ead_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.
• etch_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 (

un_powershell)

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

Flow

1. The AI generates a un_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 ase_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

Immediately after any tool call turn finishes, i_client runs _reread_file_items. It fetches the latest disk state of all files in the current project context and appends them as a synthetic [FILES UPDATED] message to the tool result. 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 ead_file.