101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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.
|