🛰️ export from upstream (56c5a2dd)

crates/dirigent_tools/CLAUDE.md

@@ -1,169 +0,0 @@
-# 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:
-
-```rust
-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`