dirigent/crates/dirigent_tools/CLAUDE.md

Package: dirigent_tools

Tool implementations for ACP client operations with sandboxing and security.

Quick Facts

• Type: Library
• Main Entry: src/lib.rs
• Dependencies: tokio, serde, anyhow, thiserror, tracing, regex, globset, similar, dunce
• Status: Scaffolding phase - structure complete, implementation pending

Purpose

This package provides the foundational tool operations for the Dirigent ACP client, implementing file operations, terminal execution, and search capabilities with strong security guarantees. It is designed to support ACP-compliant agents by providing safe, sandboxed tool handlers.

Module Structure

Core Modules

• error (src/error.rs) - Error types for tool operations
• config (src/config.rs) - Configuration types (sandbox, permissions, terminal, search, embedding)
• path (src/path.rs) - Cross-platform path normalization and containment checking

Tool Modules

• fs (src/fs.rs) - File read/write/edit operations
• search (src/search.rs) - Glob/grep/ls search operations
• terminal (src/terminal.rs) - Command execution and output capture

Security Modules

• permission (src/permission.rs) - Permission prompt system and decision caching
• audit (src/audit.rs) - Structured audit logging

Integration Modules

• tool_call (src/tool_call.rs) - ACP tool call metadata and helpers

Security Model

All operations are subject to:

1. Sandbox Containment: Operations restricted to configured allowed roots
2. Blocklist Enforcement: Sensitive paths explicitly denied
3. Permission Prompts: Write/execute operations require user approval (configurable)
4. Resource Limits: Bounded file sizes, search results, terminal output
5. Audit Logging: All operations logged with structured context

Platform Support

Windows is a first-class platform with explicit support for:

• Backslash and forward slash separators
• Drive letters (C:, D:)
• UNC paths (\server\share...)
• Long path prefixes (\?...)
• MINGW-style paths (/c/Users/...)
• Junctions and symlinks
• cmd.exe and PowerShell

All path normalization and containment logic handles these cases.

Configuration (Future)

Configuration types will be implemented in SCAFF-05:

pub struct SandboxConfig {
    pub allowed_roots: Vec<PathBuf>,
    pub blocked_paths: Vec<String>,  // glob patterns
    pub allow_symlink_escape: bool,
    pub follow_symlinks_within_roots: bool,
    pub read_enabled: bool,
    pub write_enabled: bool,
    pub max_read_bytes: u64,
    pub max_write_bytes: u64,
    // ... more fields
}

pub struct PermissionConfig {
    pub mode: PermissionMode,  // Ask | Whitelist | Yolo
    pub remember_decisions: bool,
    pub remember_ttl_secs: u64,
    pub scope: DecisionScope,  // PerConnector | PerSession
    pub whitelist: WhitelistConfig,
}

pub struct TerminalConfig {
    pub enabled: bool,
    pub default_cwd: PathBuf,
    pub env_allowlist: Vec<String>,
    pub command_blocklist: Vec<String>,
    pub output_byte_limit: u64,
    pub max_runtime_secs: u64,
}

pub struct SearchConfig {
    pub max_results: u32,
    pub max_bytes: u64,
    pub default_include_globs: Vec<String>,
    pub default_exclude_globs: Vec<String>,
}

pub struct EmbeddingConfig {
    pub max_embed_bytes: u64,
    pub allow_resource_link: bool,
    pub redact_patterns: Vec<String>,  // regex patterns
}

Implementation Status

Current Phase: SCAFF-01 (Scaffolding) - Complete

All modules are stubs with unimplemented!(). Implementation will proceed in phases:

Phase 1: Path and Sandbox (Protocol tasks)

• Path normalization (Windows, Linux, macOS)
• Canonical path resolution (symlinks, junctions)
• Containment checking
• Blocklist matching

Phase 2: Tool Operations (Tool tasks)

• File read with line ranges
• File write with atomic operations
• File edit with diff generation
• Glob search
• Grep search with context
• LS directory listing
• Terminal creation and lifecycle
• Terminal output capture with ring buffer

Phase 3: Security and Integration (Integration tasks)

• Permission prompt flow
• Decision caching with TTL
• Audit logging with structured fields
• ACP tool call event generation
• Tool title formatting

Integration Points

dirigent_core

• Uses dirigent_tools for ACP client request handlers
• Passes configuration from connector params
• Routes tool operations through sandbox

api

• May use dirigent_tools for server function implementations
• Exposes configuration endpoints
• Handles permission prompts via UI

web

• Displays tool calls with titles, locations, diffs
• Renders permission prompts
• Shows audit logs

Testing Strategy

Test infrastructure will be set up in SCAFF-03:

• Unit tests for each module
• Integration tests with mocker
• Cross-platform tests (Windows, Linux, macOS)
• Golden transcript fixtures
• Test utilities for temp directories, file comparison, sandboxed environments

Related Packages

• dirigent_core - Uses this package for tool operations
• api - May use this package for server functions
• dirigent_protocol - Shared event types for tool calls

References

• Task file: docs/building/04_acp_client/04_tasks_00_scaffolding_and_finishing.md
• Tools research: docs/building/04_acp_client/03_tools_research.md
• Sandbox spec: docs/building/04_acp_client/03_fs_sandboxing_and_permissions_spec.md
• Roadmap: docs/building/04_acp_client/roadmap.md