sync from monorepo @ 2452e92e

2026-05-08 01:59:04 +02:00
commit b03dc15371
459 changed files with 129586 additions and 0 deletions
@@ -0,0 +1,100 @@
+# 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.