dirigent/crates/dirigent_tools/README.md

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)

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.