# Tools Module

> Provides AI agent capabilities through a robust tool system with decorators and specialized implementations.

- Skill: `tools-only/tools-module` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/tools-module`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/tools-module/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/tools-module

---


# Tools Module

## Purpose
Provides AI agent capabilities through a robust tool system with decorators and specialized implementations.

## Tool Decorator System (decorators.py)

### base_tool
Foundation decorator for all tools:
- Standardizes error handling (Exception → ToolExecutionError)
- Loads tool descriptions from XML prompt files
- Ensures consistent error propagation
- Preserves ModelRetry and ToolExecutionError exceptions

### file_tool
Specialized decorator for file system tools:
- Extends base_tool functionality
- Handles file-specific errors (FileNotFoundError, PermissionError, UnicodeDecodeError)
- Maps errors to appropriate exceptions (ModelRetry for recoverable, FileOperationError for fatal)

**XML Prompt Files:**
- `bash_prompt.xml` - Bash tool documentation
- `read_file_prompt.xml` - Read file documentation
- `submit_prompt.xml` - Submit tool documentation
- etc.

## Tool Implementations

### bash.py
Executes shell commands securely:
- Destructive pattern validation (blocks `rm -rf`, etc.)
- Configurable timeouts
- Stdout/stderr capture with exit codes
- Working directory management

### glob.py
Fast file pattern matching:
- Supports `**/*.py` style patterns
- Recursive searching
- .gitignore awareness
- Sorted results
- Shared ignore manager in `src/tunacode/tools/ignore.py`

### grep.py
Advanced content search:
**Search Strategies:**
- `smart` - Auto-selects best method
- `ripgrep` - Uses ripgrep binary
- `python` - Pure Python implementation
- `hybrid` - Combined approach

**Features:**
- Regex support
- Case sensitivity control
- File type filtering
- Context lines
- Output modes: content, files-only, count, JSON
- Broad pattern prevention
- Shared ignore manager for fast-glob prefiltering and `.gitignore` rules

### read_file.py
Reads file contents safely:
- Line range support (offset/limit)
- Line number preservation
- Long line truncation
- Streaming line reads to avoid loading entire files into memory
- File size limits
- Encoding handling

### write_file.py
Creates new files:
- Parent directory auto-creation
- Overwrite prevention (use update_file instead)
- LSP diagnostic triggers
- Atomic writes

### update_file.py
Modifies existing files:
**Fuzzy Matching Algorithms:**
- `line-trimmed` - Whitespace-tolerant
- `indentation-flexible` - Indent-tolerant
- `block-anchor` - Multi-line block matching

**Features:**
- Diff generation
- LSP diagnostic updates
- Change validation

### list_dir.py
Lists directory contents:
- Recursive tree view
- Ignore pattern support
- Hidden file visibility
- Output size limits
- Shared ignore manager in `src/tunacode/tools/ignore.py`

### ignore.py
Shared ignore manager for discovery tools:
- Loads default ignore patterns plus root `.gitignore`
- Root-only `.gitignore` support (no nested ignore files)
- Pathspec `gitwildmatch` matching for ignore rules
- Provides `should_ignore`/`should_ignore_dir` helpers and cached manager instances

### web_fetch.py
Fetches web content:
- HTTP/HTTPS only
- HTML to plain text conversion
- Security validation (blocks private IPs)
- Content size limits
- Timeout handling

### lsp/ (sub-package)
LSP integration for file tools:
- `client.py` - Minimal LSP client (JSON-RPC over stdin/stdout)
- `servers.py` - Server config mapping (extension → language server)
- `diagnostics.py` - `maybe_prepend_lsp_diagnostics()` helper for write/update tools

### submit.py
Completion signaling tool:
- `submit` marks the task as complete for the orchestrator
- Optional summary text for the final response

## Tool Utilities (tools/utils/)

### formatting.py
Diagnostic message formatting helpers:
- **truncate_diagnostic_message()** - Shortens verbose diagnostic text for LSP output

### ripgrep.py
Ripgrep integration wrapper:
- Binary detection
- Output parsing
- Error handling
- Async subprocess execution with timeouts

### text_match.py
Fuzzy matching algorithms for update_file:
- Line-trimmed matching
- Indentation-flexible matching
- Block-anchor matching

## Integration Points

- **core/agents/** - Tool registration and execution
- **core/agents/tool_executor.py** - Parallel execution
- **ui/renderers/** - Specialized output rendering

## Seams (M, D)

**Modification Points:**
- Add new tool implementations
- Extend decorator system with new features
- Add new fuzzy matching algorithms

**Extension Points:**
- Create custom tool types
- Add tool-specific validation
- Extend prompt XML system