# TOOLS KNOWLEDGE BASE

## OVERVIEW
Custom tools extending agent capabilities: LSP (11 tools), AST-aware search/replace, background tasks, and multimodal analysis.

## STRUCTURE
```
tools/
├── ast-grep/           # AST-aware search/replace (25 languages)
│   ├── cli.ts          # @ast-grep/cli fallback
│   └── napi.ts         # @ast-grep/napi native binding (preferred)
├── background-task/    # Async agent task management
├── call-omo-agent/     # Spawn explore/librarian agents
├── glob/               # File pattern matching (timeout-safe)
├── grep/               # Content search (timeout-safe)
├── interactive-bash/   # Tmux session management
├── look-at/            # Multimodal analysis (PDF, images)
├── lsp/                # IDE-like code intelligence
│   ├── client.ts       # LSP connection lifecycle (632 lines)
│   ├── tools.ts        # Tool implementations
│   └── config.ts, types.ts, utils.ts
├── session-manager/    # OpenCode session history management
├── sisyphus-task/      # Category-based delegation (583 lines)
├── skill/              # Skill loading/execution
├── skill-mcp/          # Skill-embedded MCP invocation
├── slashcommand/       # Slash command execution
└── index.ts            # builtinTools export (82 lines)
```

## TOOL CATEGORIES
| Category | Tools | Purpose |
|----------|-------|---------|
| LSP | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_diagnostics, lsp_rename, etc. | IDE-grade code intelligence (11 tools) |
| AST | ast_grep_search, ast_grep_replace | Structural pattern matching/rewriting |
| Search | grep, glob | Timeout-safe file and content search |
| Session | session_list, session_read, session_search, session_info | History navigation and retrieval |
| Background | sisyphus_task, background_output, background_cancel | Parallel agent orchestration |
| UI/Terminal | look_at, interactive_bash | Visual analysis and tmux control |
| Execution | slashcommand, skill, skill_mcp | Command and skill-based extensibility |

## HOW TO ADD A TOOL
1. Create directory `src/tools/my-tool/`.
2. Implement `tools.ts` (factory), `types.ts`, and `constants.ts`.
3. Export via `index.ts` and register in `src/tools/index.ts`.

## LSP SPECIFICS
- **Lifecycle**: Lazy initialization on first call; auto-shutdown on idle.
- **Config**: Merges `opencode.json` and `oh-my-opencode.json`.
- **Capability**: Supports full LSP spec including `codeAction/resolve` and `prepareRename`.

## AST-GREP SPECIFICS
- **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls).
- **Binding**: Uses `@ast-grep/napi` for performance; ensure patterns are valid AST nodes.
- **Variables**: Supports `$VAR` and `$$$` meta-variables for capture.

## ANTI-PATTERNS
- **Sync Ops**: Never use synchronous file I/O; blocking the main thread kills responsiveness.
- **No Timeouts**: Always wrap external CLI/LSP calls in timeouts (default 60s).
- **Direct Subprocess**: Avoid raw `spawn` for ast-grep; use NAPI binding.
- **Manual Pathing**: Use `shared/utils` for path normalization across platforms.