feat: core agent tools (fs, search, shell)

.living_spec/README.md

@@ -50,7 +50,7 @@ When the user asks for a feature, follow this 4-step loop strictly:
     *   **User Story:** "As a user, I want..."
     *   **Acceptance Criteria:** Bullet points of observable success.
     *   **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy
-*   **Git:** Make a local feature branch for the story. 
+*   **Git:** The Assistant initiates a new local feature branch (e.g., `feature/story-name`) immediately.
 
 ### Step 2: The Spec (Digest)
 *   **Action:** Update the files in `specs/`.
@@ -67,7 +67,7 @@ When the user asks for a feature, follow this 4-step loop strictly:
 ### Step 4: Verification (Close)
 *   **Action:** Write a test case that maps directly to the Acceptance Criteria in the Story.
    **Action:** Run compilation and make sure it succeeds without errors. Fix warnings if possible. Run tests and make sure they all pass before proceeding. Ask questions here if needed.
-*  **Action:** Ask the user to accept the story. Move to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary)
+*  **Action:** Ask the user to accept the story. Move to `stories/archive/`. Tell the user to **Squash Merge** the feature branch (e.g. `git merge --squash feature/story-name`) and commit. This ensures the main history reflects one atomic commit per Story.
 
 
 ---

.living_spec/specs/functional/AGENT_CAPABILITIES.md

@@ -0,0 +1,48 @@
+# 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").

.living_spec/specs/tech/STACK.md

@@ -75,6 +75,7 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 *   **Rust:**
     *   `serde`, `serde_json`: Serialization.
     *   `ignore`: Fast recursive directory iteration respecting gitignore.
+    *   `walkdir`: Simple directory traversal.
     *   `tokio`: Async runtime.
     *   `reqwest`: For LLM API calls (if backend-initiated).
     *   `tauri-plugin-dialog`: Native system dialogs.

.living_spec/stories/02_core_agent_tools.md

@@ -0,0 +1,20 @@
+# Story: Core Agent Tools (The Hands)
+
+## User Story
+**As an** Agent
+**I want to** be able to read files, list directories, search content, and execute shell commands
+**So that** I can autonomously explore and modify the target project.
+
+## Acceptance Criteria
+*   [ ] Rust Backend: Implement `read_file(path)` command (scoped to project).
+*   [ ] Rust Backend: Implement `write_file(path, content)` command (scoped to project).
+*   [ ] Rust Backend: Implement `list_directory(path)` command.
+*   [ ] Rust Backend: Implement `exec_shell(command, args)` command.
+    *   [ ] Must enforce allowlist (git, cargo, npm, etc).
+    *   [ ] Must run in project root.
+*   [ ] Rust Backend: Implement `search_files(query, globs)` using `ignore` crate.
+*   [ ] Frontend: Expose these as tools to the (future) LLM interface.
+
+## Out of Scope
+*   The LLM Chat UI itself (connecting these to a visual chat window comes later).
+*   Complex git merges (simple commands only).