# dirigent_tools

Tool implementations for ACP (Agent-Client Protocol) client operations with sandboxing and permission management.

## Overview

This package provides the core tool operations for interacting with the filesystem, terminal, and search capabilities in a secure, sandboxed environment. It is designed to support ACP-compliant agents (like Claude) by implementing the client-side tool handlers with safety guarantees.

## Features

### File Operations
- **Read** text files with line range support
- **Write** text files with atomic writes and parent directory creation
- **Edit** files with diff generation for previews

### Terminal Operations
- **Create** terminals and spawn commands
- **Capture** output with byte limits and ring-buffer truncation
- **Wait** for command completion
- **Kill** running commands
- **Release** terminal resources

### Search Operations
- **Glob** file matching with patterns
- **Grep** content search with regex
- **LS** directory listing

### Security Features
- **Sandboxing**: All operations restricted to configured allowed roots
- **Blocklists**: Explicit deny patterns for sensitive paths
- **Permissions**: Configurable prompt modes (ask, whitelist, yolo)
- **Audit Logging**: Structured logs for all operations
- **Resource Limits**: Bounded file sizes, search results, and terminal output

## Platform Support

Windows is a first-class platform:
- Handles Windows paths (backslashes, drive letters, UNC shares, `\\?\` prefixes)
- Supports MINGW-style paths (`/c/...`)
- Works with cmd.exe and PowerShell
- Normalizes path separators for consistent policy enforcement

All tests run on Windows, Linux, and macOS.

## Status

**Phase**: Scaffolding (SCAFF-01) - Structure created, implementation pending

All modules are stubs with `unimplemented!()` placeholders. Actual implementation will occur in subsequent phases:
- **Protocol tasks**: Path normalization, sandbox enforcement
- **Tool tasks**: File operations, terminal execution, search
- **Integration tasks**: Permission prompts, audit logging, ACP event generation

## Configuration

See `src/config.rs` for configuration types (to be implemented in SCAFF-05):
- `SandboxConfig` - Filesystem sandboxing
- `PermissionConfig` - Permission prompts and caching
- `TerminalConfig` - Terminal limits and restrictions
- `SearchConfig` - Search result limits
- `EmbeddingConfig` - File embedding thresholds

## Usage Example (Future)

```rust
use dirigent_tools::{fs, SandboxConfig};

// Configure sandbox
let sandbox = SandboxConfig {
    allowed_roots: vec!["C:/work/project".to_string()],
    blocked_paths: vec!["**/.env".to_string()],
    // ... other fields
};

// Read a file (within sandbox)
let content = fs::read_text_file(
    Path::new("C:/work/project/src/main.rs"),
    None,  // line
    None,  // limit
)?;
```

## Testing

Test infrastructure will be set up in SCAFF-03. Tests will cover:
- Path normalization (especially Windows paths)
- Sandbox containment
- Permission flows
- File operations
- Terminal lifecycle
- Search operations

## Documentation

- **CLAUDE.md**: Package context for AI assistants
- **docs/**: API documentation (to be generated with `cargo doc`)

## License

Same as parent Dirigent project.