# dirigent_tools Implementation Status

This document tracks the implementation status of the tools package, showing which features are complete and which are stubbed pending implementation.

## Status Legend

- ✅ **Completed** - Fully implemented with tests
- ⏸️ **Stubbed** - Function signatures present, returns `unimplemented!()`
- 🚧 **In Progress** - Actively being implemented

---

## Completed Features

### Core Infrastructure

- ✅ **Error Types** (`src/error.rs`) - Complete error handling with user-facing messages
- ✅ **Configuration Types** (`src/config.rs`) - All config structures with validation
- ✅ **Path Validation** (`src/path/validate.rs`) - Path normalization and validation
- ✅ **Path Canonicalization** (`src/path/canonicalize.rs`) - Cross-platform canonical paths
- ✅ **Path Containment** (`src/path/containment.rs`) - Sandbox boundary checking
- ✅ **Path Blocklist** (`src/path/blocklist.rs`) - Glob-based path blocking

---

## Stubbed Features (TODO)

### File Operations

- ⏸️ **Read Text File** (`src/fs/read.rs`) - TOOLS-FS-01
  - Function: `read_text_file()`
  - Types: `ReadTextFileRequest`, `ReadTextFileResponse`
  - Features: Line/limit support, UTF-8 validation, sandboxing

- ⏸️ **Write Text File** (`src/fs/write.rs`) - TOOLS-FS-02
  - Function: `write_text_file()`, `normalize_eol()`
  - Types: `WriteTextFileRequest`, `WriteTextFileResponse`
  - Features: Atomic writes, EOL normalization, permission checks

- ⏸️ **Generate Diff** (`src/fs/diff.rs`) - TOOLS-FS-03
  - Function: `generate_diff()`
  - Features: Unified diff generation, edge case handling

- ⏸️ **Edit File** (`src/fs/edit.rs`) - TOOLS-FS-04
  - Function: `edit_file()`
  - Types: `EditFileRequest`, `EditFileResponse`, `EditOperation`
  - Features: Read + transform + write, automatic diff generation

### Search Operations

- ⏸️ **Directory Listing** (`src/search/ls.rs`) - TOOLS-SEARCH-01
  - Function: `ls()`
  - Types: `LsRequest`, `LsResponse`, `LsEntry`, `FileKind`
  - Features: Sandboxing, exclude globs, file metadata

- ⏸️ **Glob Search** (`src/search/glob.rs`) - TOOLS-SEARCH-02
  - Function: `glob_search()`
  - Types: `GlobRequest`, `GlobResponse`
  - Features: Pattern matching, result limits, exclude patterns

- ⏸️ **Content Search** (`src/search/grep.rs`) - TOOLS-SEARCH-03
  - Function: `grep_search()`
  - Types: `GrepRequest`, `GrepResponse`, `GrepMatch`
  - Features: Regex search, context lines, binary file detection

### Terminal Operations

- ⏸️ **Create Terminal** (`src/terminal/create.rs`) - TOOLS-TERM-01
  - Function: `create_terminal()`
  - Types: `CreateTerminalRequest`, `CreateTerminalResponse`, `EnvVar`
  - Features: Process spawning, CWD validation, env filtering, output capture

- ⏸️ **Get Terminal Output** (`src/terminal/output.rs`) - TOOLS-TERM-02
  - Function: `get_terminal_output()`
  - Types: `TerminalOutputRequest`, `TerminalOutputResponse`
  - Features: Ring buffer snapshot, truncation tracking, exit status

- ⏸️ **Wait for Exit** (`src/terminal/wait.rs`) - TOOLS-TERM-03
  - Function: `wait_for_terminal_exit()`
  - Types: `WaitForTerminalExitRequest`, `WaitForTerminalExitResponse`
  - Features: Blocking wait, timeout enforcement

- ⏸️ **Kill Terminal** (`src/terminal/kill.rs`) - TOOLS-TERM-04
  - Function: `kill_terminal()`
  - Types: `KillTerminalCommandRequest`, `KillTerminalCommandResponse`
  - Features: Forceful termination, idempotent operations

- ⏸️ **Release Terminal** (`src/terminal/release.rs`) - TOOLS-TERM-05
  - Function: `release_terminal()`
  - Types: `ReleaseTerminalRequest`, `ReleaseTerminalResponse`
  - Features: Resource cleanup, registry removal

- ⏸️ **Ring Buffer** (`src/terminal/ring_buffer.rs`) - TOOLS-TERM-01
  - Type: `RingBuffer`
  - Features: Fixed-size circular buffer, UTF-8 boundary handling

### Security and Permissions

- ⏸️ **Permission System** (`src/permission.rs`) - TOOLS-PERM-01 through TOOLS-PERM-05
  - Functions: Permission checks, decision caching, whitelist matching
  - Features: Ask/whitelist/yolo modes, per-connector/session scope

### Observability

- ⏸️ **Audit Logging** (`src/audit.rs`) - TOOLS-AUDIT-01 through TOOLS-AUDIT-03
  - Functions: Structured audit logging, metrics
  - Features: Operation tracking, performance monitoring

### UI Integration

- ⏸️ **Tool Call Rendering** (`src/tool_call.rs`) - TOOLS-UI-01 through TOOLS-UI-03
  - Functions: ToolKind mapping, title generation, diff formatting
  - Features: ACP integration, location extraction

---

## When Implementing a Stubbed Feature

Follow these steps to properly implement a feature:

1. **Implement the Function**
   - Replace `unimplemented!()` with actual logic
   - Follow the task specification in `docs/building/04_acp_client/04_tasks_02_tools_and_sandboxing.md`
   - Reference the security spec in `docs/building/04_acp_client/03_fs_sandboxing_and_permissions_spec.md`

2. **Add Comprehensive Tests**
   - Unit tests for happy paths
   - Edge case testing
   - Error case validation
   - Cross-platform tests (Windows, Linux, macOS)

3. **Enable Capability** (if applicable)
   - Update `ClientCapabilities::default()` in `packages/dirigent_core/src/acp/connector_state.rs`
   - Change from `None` to `Some(...)` for the relevant capability
   - Document why the capability is now safe to advertise

4. **Update This Document**
   - Move feature from "Stubbed" to "Completed"
   - Add any notes or caveats
   - Update completion percentage

5. **Integration Testing**
   - Test with dirigent-acp-mocker
   - Verify tool calls work end-to-end
   - Test UI rendering if applicable

---

## Capability Enablement

**CRITICAL**: Do NOT enable capabilities in `ClientCapabilities::default()` until the corresponding tools are fully implemented and tested.

### Current Capability Defaults (dirigent_core)

```rust
impl Default for ClientCapabilities {
    fn default() -> Self {
        Self {
            fs: None,        // ❌ Disabled - file operations not yet implemented
            terminal: None,  // ❌ Disabled - terminal operations not yet implemented
            _meta: None,
        }
    }
}
```

### When to Enable

**File System (`fs`)**:
- ✅ TOOLS-FS-01 (read) is implemented and tested
- ✅ TOOLS-FS-02 (write) is implemented and tested (or omit `write_text_file: Some(true)`)
- ✅ Path validation and sandboxing are complete
- ✅ Permission system is integrated

**Terminal (`terminal`)**:
- ✅ TOOLS-TERM-01 through TOOLS-TERM-05 are implemented
- ✅ Ring buffer is working correctly
- ✅ Permission checks are in place
- ✅ Cross-platform spawn/kill is tested

---

## Progress Summary

- **Total Features**: 25
- **Completed**: 6 (24%)
- **Stubbed**: 19 (76%)
- **In Progress**: 0

---

## Task References

All task specifications are in:
- `docs/building/04_acp_client/04_tasks_02_tools_and_sandboxing.md`

Task ID format: `TOOLS-{AREA}-{NUMBER}`
- `TOOLS-SCAFFOLD-XX` - Package structure
- `TOOLS-PATH-XX` - Path operations
- `TOOLS-FS-XX` - File operations
- `TOOLS-SEARCH-XX` - Search operations
- `TOOLS-TERM-XX` - Terminal operations
- `TOOLS-PERM-XX` - Permission system
- `TOOLS-AUDIT-XX` - Audit and observability
- `TOOLS-UI-XX` - UI integration

---

## Next Steps

To continue implementation:

1. **Protocol Integration** (prerequisite)
   - Ensure ACP protocol handlers can call tool functions
   - Wire up request/response types
   - Handle tool call lifecycle (pending → in_progress → completed/failed)

2. **File Operations** (high priority for UI features)
   - TOOLS-FS-01: Read text file
   - TOOLS-FS-02: Write text file
   - TOOLS-FS-03: Generate diffs

3. **Search Operations** (useful for development)
   - TOOLS-SEARCH-01: Directory listing
   - TOOLS-SEARCH-02: Glob search

4. **Permission System** (security-critical)
   - TOOLS-PERM-01: Permission checks
   - TOOLS-PERM-02: Decision caching

5. **Terminal Operations** (complex, later priority)
   - TOOLS-TERM-01: Create terminal
   - TOOLS-TERM-02: Get output

---

*Last Updated: 2025-11-12*
*Status: All core infrastructure complete, tool operations stubbed and ready for implementation*