File System and Execution Tools

To build a coding assistant, you must bridge the gap between "Talking about code" and "Acting on files." This requires a suite of specialized tools that allow the model to interact with the Operating System.

In this lesson, we will learn the technical implementation of "Atomic File Tools" and how to manage the risks of direct file manipulation.

---

1. Tool 1: The View_Tree (Structure Awareness)

The agent needs to know the "Shape" of the project.

@tool
def get_file_structure(root_dir: str):
    """Returns a visual tree of the file system (ignoring .git and node_modules)."""
    # implementation using os.walk
    pass

Why ignore .git? Most models will get confused by the binary blobs in the git folder. Keep the context clean.

---

2. Tool 2: Read_Content (Context Gulping)

Agents should read files selectively.

• Bad: read_all_files() (Kills context window).
• Good: read_file_range(path, start_line, end_line).

By allowing the agent to read specific chunks (e.g., just the imports or just a specific class), you allow it to work on massive codebases using small models.

---

3. Tool 3: Atomic_Write (The Surgery Tool)

Never allow an agent to "Overwrite" a 1,000-line file with a 1,000-line response. LLMs are bad at copying long text and often drop characters.

The Search/Replace Pattern:

Instead of write_file, use edit_file:

• Parameter: target_string (find this exactly).
• Parameter: replacement_string (put this there).

Advantage: If the target_string isn't found exactly, the tool returns an error. This prevents the agent from accidentally deleting unrelated code if it gets "Lost" in the file.

---

4. Tool 4: The Shell_Exec (The Reality Check)

An agent cannot know if its code works just by looking at it. It must Run it.

@tool
def run_command(command: str):
    """Executes a bash command and returns the stdout and stderr."""
    # This MUST run in the Docker container (Module 7.2)
    pass

The Workflow:

1. Agent writes a test_math.py.
2. Agent calls run_command("pytest test_math.py").
3. Agent sees FAIL: Assert 2+2 == 5.
4. Agent Self-Corrects (Module 5.2).

---

5. Security: Path Sanitization

Always validate that the path provided by the model is relative to the project root.

• Attack: read_file("/etc/passwd").
• Defense:

  if "../" in path or path.startswith("/"):
      raise PermissionError("Access outside workspace is forbidden.")
  

---

6. Implementation Example: The "File Manager" Class

A robust coding agent uses a stateful "File Manager" that keeps track of which files are currently "Open" in the model's memory.

class CodeContext:
    open_files: List[str] = []
    current_working_directory: str = "./"
    
    def add_file(self, path):
        # Adds the file to the 'System Prompt' on the next turn
        pass

---

Summary and Mental Model

Think of File System Tools like Surgical Instruments.

• You don't take a chainsaw to a patient (Overwriting files).
• You use a scalpel (Atomic edits) to change exactly what needs to be changed.
• You use a monitor (Shell Execution) to check the patient's heart rate (Tests) after the surgery.

---

Exercise: Tool Implementation

1. Safety: Write a Python function for a delete_file tool that refuses to delete any file with a .lock, .env, or .git extension.
2. Efficiency: Create a tool search_codebase(regex) that uses grep.
   • Why is this better for an agent than reading every file in a loop?
3. Logic: What happens if an agent tries to run_command("npm install") but there is no internet connection in its sandbox?
   • (Hint: How should the tool explain this "Environment Error" to the LLM?) Ready for the team workflow? Next lesson: Git and CI/CD Integration.