[Phase 2.5-B] Implement write agent tools (edit_file, create_file)

[frankbria]

Summary

Add the file-modification tools to codeframe/core/tools.py: edit_file (search-replace via editor.py) and create_file (whole-file for new files only).

Acceptance Criteria

• edit_file tool:
  • Input: { path, edits: [{ search, replace }] }
  • Delegates to SearchReplaceEditor.apply_edits() from editor.py
  • On success: returns unified diff
  • On failure: returns actual file content near expected match (for LLM retry)
  • Must read file before editing (verified internally)
• create_file tool:
  • Input: { path, content }
  • Creates file with content, auto-creates parent directories
  • Fails if file already exists — returns error suggesting edit_file instead
  • This prevents the Add Claude Code GitHub Workflow #1 failure mode (config file overwrites)
• Both tools added to AGENT_TOOLS list and execute_tool dispatcher
• Tests in tests/core/test_tools.py covering:
  • Successful edit with diff output
  • Edit failure with context feedback
  • Create new file success
  • Create existing file → error with suggestion
  • Path traversal attempts blocked
• All existing tests pass

Implementation Notes

• edit_file wraps SearchReplaceEditor from Phase A issue [Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343
• create_file reuses logic from executor.py:_execute_file_create() (simplified)
• The "file already exists" check is a critical design decision — it structurally prevents the pyproject.toml overwrite problem

Dependencies

• Phase A: [Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343 (editor.py for edit_file)
• Phase B read-only tools: [Phase 2.5-B] Implement read-only agent tools (read_file, list_files, search_codebase) #344 (tools.py infrastructure)

Reference

• docs/AGENT_V3_UNIFIED_PLAN.md (Tool Set → edit_file, create_file)
• docs/AGENT_ARCHITECTURE_CRITIQUE.md (Section 2.1 — greenfield vs brownfield)

[traycerai]

Plan

Observations

The codebase currently uses LLM-based whole-file generation for file operations in file:codeframe/core/executor.py. The ticket requires implementing two new agent tools: edit_file (using search-replace via a new SearchReplaceEditor) and create_file (whole-file for new files only). These tools will be added to a new file:codeframe/core/tools.py module. The critical design decision is that create_file must fail if the file already exists, preventing config file overwrites. The existing executor has graceful fallback behavior that will need to be replaced with strict enforcement.

Approach

The implementation follows a three-layer architecture: (1) SearchReplaceEditor in file:codeframe/core/editor.py for precise search-replace operations with context feedback, (2) tool wrappers in file:codeframe/core/tools.py that expose edit_file and create_file with proper validation and error handling, and (3) comprehensive tests in file:tests/core/test_tools.py. The approach leverages existing patterns from file:codeframe/core/executor.py for file operations and path validation from file:codeframe/config/security.py, while introducing strict "fail-fast" semantics to prevent the pyproject.toml overwrite problem.

Implementation Steps

1. Create SearchReplaceEditor in codeframe/core/editor.py

Purpose: Implement the core search-replace editing engine that edit_file will delegate to.

Key Components:

• SearchReplaceEditor class with apply_edits(file_path, edits) method
• Each edit is a dict with {"search": str, "replace": str}
• Read file content before editing (internal verification)
• Apply edits sequentially, tracking line numbers
• On success: generate unified diff using difflib.unified_diff (see pattern in file:codeframe/core/prd.py lines 662-670)
• On failure: return context around expected match location (±5 lines) for LLM retry
• Handle edge cases: empty search string, multiple matches, no matches

Error Handling:

• If search string not found: return {"success": False, "error": "Search string not found", "context": <nearby_lines>}
• If multiple matches: apply to first occurrence, log warning
• If file doesn't exist: raise FileNotFoundError

Path Security: Use Path.resolve() to prevent path traversal attacks (pattern from file:codeframe/core/prd.py line 79)

2. Create tools infrastructure in codeframe/core/tools.py

Purpose: Define the agent tool interface and dispatcher.

Structure:

AGENT_TOOLS = [
    {
        "name": "edit_file",
        "description": "Edit existing file using search-replace operations",
        "parameters": {
            "path": "File path relative to repo root",
            "edits": "List of {search, replace} operations"
        }
    },
    {
        "name": "create_file", 
        "description": "Create new file (fails if exists)",
        "parameters": {
            "path": "File path to create",
            "content": "Complete file content"
        }
    }
]

execute_tool(tool_name, params, repo_path) dispatcher:

• Route to _tool_edit_file() or _tool_create_file()
• Return standardized result dict: {"success": bool, "output": str, "error": str}

3. Implement edit_file tool

Input Validation:

• Verify path is string and not empty
• Verify edits is list of dicts with "search" and "replace" keys
• Resolve path relative to repo_path
• Check path doesn't escape repo (use Path.resolve() and verify starts with repo_path)

Execution Flow:

1. Instantiate SearchReplaceEditor
2. Call editor.apply_edits(file_path, edits)
3. On success: return {"success": True, "output": <unified_diff>}
4. On failure: return {"success": False, "error": <message>, "context": <file_content_near_match>}

Context Feedback Pattern: When search fails, return 10-20 lines around where the LLM likely expected the match (use heuristics: similar variable names, function signatures)

4. Implement create_file tool

Critical Design Decision: Fail if file exists - this prevents the #1 failure mode.

Input Validation:

• Verify path is string and not empty
• Verify content is string
• Resolve path relative to repo_path
• Check path security (no traversal)

Execution Flow:

1. Check if file exists: if file_path.exists(): return error
2. Error message: "File already exists: {path}. Use edit_file to modify existing files."
3. Create parent directories: file_path.parent.mkdir(parents=True, exist_ok=True) (pattern from file:codeframe/core/executor.py line 350)
4. Write content: file_path.write_text(content, encoding="utf-8")
5. Return success with created file path

Reuse Logic: Adapt from file:codeframe/core/executor.py _execute_file_create() (lines 285-370), but remove the graceful fallback behavior (lines 298-337) - replace with strict failure.

5. Add tools to AGENT_TOOLS list and execute_tool dispatcher

AGENT_TOOLS List: Define tool metadata for agent discovery (name, description, parameters schema)

execute_tool Dispatcher:

def execute_tool(tool_name: str, params: dict, repo_path: Path) -> dict:
    if tool_name == "edit_file":
        return _tool_edit_file(params, repo_path)
    elif tool_name == "create_file":
        return _tool_create_file(params, repo_path)
    else:
        return {"success": False, "error": f"Unknown tool: {tool_name}"}

6. Create comprehensive tests in tests/core/test_tools.py

Test Structure (follow pattern from file:tests/core/test_executor.py):

Test Classes:

• TestSearchReplaceEditor: Test editor.py functionality

  • test_apply_edits_success: Single edit, verify diff output
  • test_apply_edits_multiple: Multiple sequential edits
  • test_apply_edits_not_found: Search string missing, verify context feedback
  • test_apply_edits_file_not_found: File doesn't exist
  • test_apply_edits_empty_search: Edge case handling

• TestEditFileTool: Test edit_file tool

  • test_edit_file_success: Successful edit with diff output
  • test_edit_file_failure_with_context: Edit fails, returns context
  • test_edit_file_invalid_params: Missing/invalid parameters
  • test_edit_file_path_traversal: Security check (e.g., ../../etc/passwd)

• TestCreateFileTool: Test create_file tool

  • test_create_file_success: Create new file
  • test_create_file_nested_dirs: Auto-create parent directories
  • test_create_file_already_exists: Critical test - verify error with suggestion
  • test_create_file_path_traversal: Security check

• TestToolDispatcher: Test execute_tool

  • test_execute_tool_edit_file: Route to edit_file
  • test_execute_tool_create_file: Route to create_file
  • test_execute_tool_unknown: Unknown tool name

Fixtures (pattern from file:tests/core/test_executor.py lines 127-146):

• tmp_path: Pytest fixture for temporary directory
• sample_repo: Create sample repo structure with test files

Assertions:

• Verify file content changes
• Verify diff format (starts with ---, +++, contains @@)
• Verify error messages contain helpful suggestions
• Verify path traversal attempts are blocked

7. Ensure all existing tests pass

Verification Steps:

1. Run pytest tests/core/test_executor.py - ensure no regressions
2. Run pytest tests/core/test_tools.py - new tests pass
3. Run full test suite: pytest tests/
4. Check for import errors or circular dependencies

Potential Issues:

• If tools.py imports from executor.py, ensure no circular imports
• Verify SearchReplaceEditor doesn't conflict with existing LLM-based editing in executor

Visual Architecture

sequenceDiagram
    participant Agent
    participant tools.py
    participant editor.py
    participant FileSystem

    Agent->>tools.py: execute_tool("edit_file", {path, edits})
    tools.py->>tools.py: Validate params & path security
    tools.py->>editor.py: SearchReplaceEditor.apply_edits()
    editor.py->>FileSystem: Read file content
    FileSystem-->>editor.py: Original content
    editor.py->>editor.py: Apply search-replace edits
    alt Edit successful
        editor.py->>FileSystem: Write updated content
        editor.py->>editor.py: Generate unified diff
        editor.py-->>tools.py: {success: True, diff}
        tools.py-->>Agent: {success: True, output: diff}
    else Search string not found
        editor.py->>editor.py: Extract context around expected location
        editor.py-->>tools.py: {success: False, error, context}
        tools.py-->>Agent: {success: False, error, context}
    end

    Agent->>tools.py: execute_tool("create_file", {path, content})
    tools.py->>tools.py: Validate params & path security
    tools.py->>FileSystem: Check if file exists
    alt File already exists
        tools.py-->>Agent: {success: False, error: "Use edit_file"}
    else File doesn't exist
        tools.py->>FileSystem: Create parent dirs
        tools.py->>FileSystem: Write content
        tools.py-->>Agent: {success: True, output: path}
    end

Loading

File References

New Files to Create:

• file:codeframe/core/editor.py - SearchReplaceEditor implementation
• file:codeframe/core/tools.py - Agent tools infrastructure
• file:tests/core/test_tools.py - Comprehensive test suite

Existing Files to Reference:

• file:codeframe/core/executor.py - File operation patterns (lines 285-370, 349-350)
• file:codeframe/core/prd.py - Unified diff pattern (lines 662-670), path security (line 79)
• file:codeframe/config/security.py - Security patterns
• file:tests/core/test_executor.py - Test patterns and fixtures

Dependencies:

• Phase A ([Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343): SearchReplaceEditor in editor.py
• Phase B ([Phase 2.5-B] Implement read-only agent tools (read_file, list_files, search_codebase) #344): tools.py infrastructure with AGENT_TOOLS list

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently uses LLM-based whole-file generation for file operations in `file:codeframe/core/executor.py`. The ticket requires implementing two new agent tools: `edit_file` (using search-replace via a new `SearchReplaceEditor`) and `create_file` (whole-file for new files only). These tools will be added to a new `file:codeframe/core/tools.py` module. The critical design decision is that `create_file` must fail if the file already exists, preventing config file overwrites. The existing executor has graceful fallback behavior that will need to be replaced with strict enforcement.

## Approach

The implementation follows a three-layer architecture: (1) `SearchReplaceEditor` in `file:codeframe/core/editor.py` for precise search-replace operations with context feedback, (2) tool wrappers in `file:codeframe/core/tools.py` that expose `edit_file` and `create_file` with proper validation and error handling, and (3) comprehensive tests in `file:tests/core/test_tools.py`. The approach leverages existing patterns from `file:codeframe/core/executor.py` for file operations and path validation from `file:codeframe/config/security.py`, while introducing strict "fail-fast" semantics to prevent the pyproject.toml overwrite problem.

## Implementation Steps

### 1. Create SearchReplaceEditor in codeframe/core/editor.py

**Purpose**: Implement the core search-replace editing engine that `edit_file` will delegate to.

**Key Components**:
- `SearchReplaceEditor` class with `apply_edits(file_path, edits)` method
- Each edit is a dict with `{"search": str, "replace": str}`
- Read file content before editing (internal verification)
- Apply edits sequentially, tracking line numbers
- On success: generate unified diff using `difflib.unified_diff` (see pattern in `file:codeframe/core/prd.py` lines 662-670)
- On failure: return context around expected match location (±5 lines) for LLM retry
- Handle edge cases: empty search string, multiple matches, no matches

**Error Handling**:
- If search string not found: return `{"success": False, "error": "Search string not found", "context": <nearby_lines>}`
- If multiple matches: apply to first occurrence, log warning
- If file doesn't exist: raise `FileNotFoundError`

**Path Security**: Use `Path.resolve()` to prevent path traversal attacks (pattern from `file:codeframe/core/prd.py` line 79)

### 2. Create tools infrastructure in codeframe/core/tools.py

**Purpose**: Define the agent tool interface and dispatcher.

**Structure**:
```
AGENT_TOOLS = [
    {
        "name": "edit_file",
        "description": "Edit existing file using search-replace operations",
        "parameters": {
            "path": "File path relative to repo root",
            "edits": "List of {search, replace} operations"
        }
    },
    {
        "name": "create_file", 
        "description": "Create new file (fails if exists)",
        "parameters": {
            "path": "File path to create",
            "content": "Complete file content"
        }
    }
]
```

**execute_tool(tool_name, params, repo_path)** dispatcher:
- Route to `_tool_edit_file()` or `_tool_create_file()`
- Return standardized result dict: `{"success": bool, "output": str, "error": str}`

### 3. Implement edit_file tool

**Input Validation**:
- Verify `path` is string and not empty
- Verify `edits` is list of dicts with "search" and "replace" keys
- Resolve path relative to `repo_path`
- Check path doesn't escape repo (use `Path.resolve()` and verify starts with `repo_path`)

**Execution Flow**:
1. Instantiate `SearchReplaceEditor`
2. Call `editor.apply_edits(file_path, edits)`
3. On success: return `{"success": True, "output": <unified_diff>}`
4. On failure: return `{"success": False, "error": <message>, "context": <file_content_near_match>}`

**Context Feedback Pattern**: When search fails, return 10-20 lines around where the LLM likely expected the match (use heuristics: similar variable names, function signatures)

### 4. Implement create_file tool

**Critical Design Decision**: **Fail if file exists** - this prevents the #1 failure mode.

**Input Validation**:
- Verify `path` is string and not empty
- Verify `content` is string
- Resolve path relative to `repo_path`
- Check path security (no traversal)

**Execution Flow**:
1. Check if file exists: `if file_path.exists(): return error`
2. Error message: `"File already exists: {path}. Use edit_file to modify existing files."`
3. Create parent directories: `file_path.parent.mkdir(parents=True, exist_ok=True)` (pattern from `file:codeframe/core/executor.py` line 350)
4. Write content: `file_path.write_text(content, encoding="utf-8")`
5. Return success with created file path

**Reuse Logic**: Adapt from `file:codeframe/core/executor.py` `_execute_file_create()` (lines 285-370), but remove the graceful fallback behavior (lines 298-337) - replace with strict failure.

### 5. Add tools to AGENT_TOOLS list and execute_tool dispatcher

**AGENT_TOOLS List**: Define tool metadata for agent discovery (name, description, parameters schema)

**execute_tool Dispatcher**:
```python
def execute_tool(tool_name: str, params: dict, repo_path: Path) -> dict:
    if tool_name == "edit_file":
        return _tool_edit_file(params, repo_path)
    elif tool_name == "create_file":
        return _tool_create_file(params, repo_path)
    else:
        return {"success": False, "error": f"Unknown tool: {tool_name}"}
```

### 6. Create comprehensive tests in tests/core/test_tools.py

**Test Structure** (follow pattern from `file:tests/core/test_executor.py`):

**Test Classes**:
- `TestSearchReplaceEditor`: Test editor.py functionality
  - `test_apply_edits_success`: Single edit, verify diff output
  - `test_apply_edits_multiple`: Multiple sequential edits
  - `test_apply_edits_not_found`: Search string missing, verify context feedback
  - `test_apply_edits_file_not_found`: File doesn't exist
  - `test_apply_edits_empty_search`: Edge case handling

- `TestEditFileTool`: Test edit_file tool
  - `test_edit_file_success`: Successful edit with diff output
  - `test_edit_file_failure_with_context`: Edit fails, returns context
  - `test_edit_file_invalid_params`: Missing/invalid parameters
  - `test_edit_file_path_traversal`: Security check (e.g., `../../etc/passwd`)

- `TestCreateFileTool`: Test create_file tool
  - `test_create_file_success`: Create new file
  - `test_create_file_nested_dirs`: Auto-create parent directories
  - `test_create_file_already_exists`: **Critical test** - verify error with suggestion
  - `test_create_file_path_traversal`: Security check

- `TestToolDispatcher`: Test execute_tool
  - `test_execute_tool_edit_file`: Route to edit_file
  - `test_execute_tool_create_file`: Route to create_file
  - `test_execute_tool_unknown`: Unknown tool name

**Fixtures** (pattern from `file:tests/core/test_executor.py` lines 127-146):
- `tmp_path`: Pytest fixture for temporary directory
- `sample_repo`: Create sample repo structure with test files

**Assertions**:
- Verify file content changes
- Verify diff format (starts with `---`, `+++`, contains `@@`)
- Verify error messages contain helpful suggestions
- Verify path traversal attempts are blocked

### 7. Ensure all existing tests pass

**Verification Steps**:
1. Run `pytest tests/core/test_executor.py` - ensure no regressions
2. Run `pytest tests/core/test_tools.py` - new tests pass
3. Run full test suite: `pytest tests/`
4. Check for import errors or circular dependencies

**Potential Issues**:
- If `tools.py` imports from `executor.py`, ensure no circular imports
- Verify `SearchReplaceEditor` doesn't conflict with existing LLM-based editing in executor

## Visual Architecture

```mermaid
sequenceDiagram
    participant Agent
    participant tools.py
    participant editor.py
    participant FileSystem

    Agent->>tools.py: execute_tool("edit_file", {path, edits})
    tools.py->>tools.py: Validate params & path security
    tools.py->>editor.py: SearchReplaceEditor.apply_edits()
    editor.py->>FileSystem: Read file content
    FileSystem-->>editor.py: Original content
    editor.py->>editor.py: Apply search-replace edits
    alt Edit successful
        editor.py->>FileSystem: Write updated content
        editor.py->>editor.py: Generate unified diff
        editor.py-->>tools.py: {success: True, diff}
        tools.py-->>Agent: {success: True, output: diff}
    else Search string not found
        editor.py->>editor.py: Extract context around expected location
        editor.py-->>tools.py: {success: False, error, context}
        tools.py-->>Agent: {success: False, error, context}
    end

    Agent->>tools.py: execute_tool("create_file", {path, content})
    tools.py->>tools.py: Validate params & path security
    tools.py->>FileSystem: Check if file exists
    alt File already exists
        tools.py-->>Agent: {success: False, error: "Use edit_file"}
    else File doesn't exist
        tools.py->>FileSystem: Create parent dirs
        tools.py->>FileSystem: Write content
        tools.py-->>Agent: {success: True, output: path}
    end
```

## File References

**New Files to Create**:
- `file:codeframe/core/editor.py` - SearchReplaceEditor implementation
- `file:codeframe/core/tools.py` - Agent tools infrastructure
- `file:tests/core/test_tools.py` - Comprehensive test suite

**Existing Files to Reference**:
- `file:codeframe/core/executor.py` - File operation patterns (lines 285-370, 349-350)
- `file:codeframe/core/prd.py` - Unified diff pattern (lines 662-670), path security (line 79)
- `file:codeframe/config/security.py` - Security patterns
- `file:tests/core/test_executor.py` - Test patterns and fixtures

**Dependencies**:
- Phase A (#343): `SearchReplaceEditor` in editor.py
- Phase B (#344): tools.py infrastructure with AGENT_TOOLS list

---

Execution Information

Branch: main
Commit: 99f0ea9

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#306 - feat(env): add environment validation with tool detection [merged]
#342 - feat: agent execution resilience - file conflicts, verification recovery, observability [closed]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!