# Functional Spec: Agent Capabilities

## Overview
The Agent interacts with the Target Project through a set of deterministic Tools. These tools are exposed as Tauri Commands to the frontend, which acts as the orchestrator for the LLM.

## 1. Filesystem Tools
All filesystem operations are **strictly scoped** to the active `SessionState.project_root`. Attempting to access paths outside this root (e.g., `../foo`) must return an error.

### `read_file`
*   **Input:** `path: String` (Relative to project root)
*   **Output:** `Result<String, AppError>`
*   **Behavior:** Returns the full text content of the file.

### `write_file`
*   **Input:** `path: String`, `content: String`
*   **Output:** `Result<(), AppError>`
*   **Behavior:** Overwrites the file. Creates parent directories if they don't exist.

### `list_directory`
*   **Input:** `path: String` (Relative)
*   **Output:** `Result<Vec<FileEntry>, AppError>`
*   **Data Structure:** `FileEntry { name: String, kind: "file" | "dir" }`

## 2. Search Tools
High-performance text search is critical for the Agent to "read" the codebase without dumping all files into context.

### `search_files`
*   **Input:** `query: String` (Regex or Literal), `glob: Option<String>`
*   **Output:** `Result<Vec<Match>, AppError>`
*   **Engine:** Rust `ignore` crate (WalkBuilder) + `grep_searcher`.
*   **Constraints:**
    *   Must respect `.gitignore`.
    *   Limit results (e.g., top 100 matches) to prevent freezing.

## 3. Shell Tools
The Agent needs to compile code, run tests, and manage git.

### `exec_shell`
*   **Input:** `command: String`, `args: Vec<String>`
*   **Output:** `Result<CommandOutput, AppError>`
*   **Data Structure:** `CommandOutput { stdout: String, stderr: String, exit_code: i32 }`
*   **Security Policy:**
    *   **Allowlist:** `git`, `cargo`, `npm`, `yarn`, `pnpm`, `node`, `bun`, `ls`, `find`, `grep`, `mkdir`, `rm`, `mv`, `cp`, `touch`.
    *   **cwd:** Always executed in `SessionState.project_root`.
    *   **Timeout:** Hard limit (e.g., 30s) to prevent hanging processes.

## Error Handling
All tools must return a standardized JSON error object to the frontend so the LLM knows *why* a tool failed (e.g., "File not found", "Permission denied").