Commit 9736477

@@ -0,0 +1,319 @@
+# Del Tool Call Dialects
+
+Del supports **universal tool calling** across multiple AI model formats. This document describes the various tool call dialects that Del can parse and execute.
+
+## 🎯 Overview
+
+Del uses a **two-stage execution process**:
+1. **Stage 1**: Model generates tool calls in its native format
+2. **Stage 2**: Del executes tools and feeds real results back to the model
+
+This prevents AI hallucination and ensures accurate, real-world data.
+
+## 🔧 Supported Tool Call Formats
+
+### 1. Chinese Models Format (DeepSeek, Qwen, ChatGLM, etc.)
+
+**Format**: Used by Chinese AI models like DeepSeek Coder, Qwen2.5, ChatGLM, etc.
+
+**Basic Structure**:
+```
+<｜tool▁calls▁begin｜>
+<｜tool▁call▁begin｜>
+function<｜tool▁sep｜>tool_name
+```json
+{
+  "arg1": "value1",
+  "arg2": "value2"
+}
+```
+<｜tool▁call▁end｜>
+<｜tool▁calls▁end｜>
+```
+
+**Real Example**:
+```
+<｜tool▁calls▁begin｜>
+<｜tool▁call▁begin｜>
+function<｜tool▁sep｜>list_dir
+```json
+{"path": "."}
+```
+<｜tool▁call▁end｜>
+<｜tool▁calls▁end｜>
+```
+
+**Variations Supported**:
+- With or without closing tags
+- Inline JSON: `function<｜tool▁sep｜>list_dir {"path": "."}`
+- Empty arguments: `function<｜tool▁sep｜>project_context {}`
+
+### 2. OpenAI XML Format
+
+**Format**: Used by OpenAI GPT models and compatible APIs.
+
+**Structure**:
+```xml
+<tool_calls>
+<invoke name="tool_name">
+<parameter name="arg1">value1</parameter>
+<parameter name="arg2">value2</parameter>
+</invoke>
+</tool_calls>
+```
+
+**Example**:
+```xml
+<tool_calls>
+<invoke name="read_file">
+<parameter name="path">main.go</parameter>
+</invoke>
+</tool_calls>
+```
+
+### 3. OpenAI JSON Format
+
+**Format**: JSON array format used by some OpenAI integrations.
+
+**Structure**:
+```json
+[{"name": "tool_name", "parameters": {"arg1": "value1", "arg2": "value2"}}]
+```
+
+**Example**:
+```json
+[{"name": "git_operation", "parameters": {"operation": "status"}}]
+```
+
+### 4. Llama Function Format
+
+**Format**: Used by Llama models and Meta's function calling implementations.
+
+**Structure**:
+```
+<function=tool_name>{"arg1": "value1", "arg2": "value2"}</function>
+```
+
+**Example**:
+```
+<function=security_scan>{"path": "."}</function>
+```
+
+### 5. Markdown Format
+
+**Format**: Human-readable format sometimes used by models.
+
+**Structure**:
+```markdown
+## Function Call
+tool_name({"arg1": "value1", "arg2": "value2"})
+```
+
+**Example**:
+```markdown
+## Tool Call
+analyze_code({"content": "package main..."})
+```
+
+### 6. Legacy Del Format (Deprecated)
+
+**Format**: Del's original custom format (maintained for backward compatibility).
+
+**Structure**:
+```
+TOOL_USE: tool_name {"arg1": "value1", "arg2": "value2"}
+```
+
+**Example**:
+```
+TOOL_USE: run_command {"command": "git status"}
+```
+
+## 🚀 Available Tools
+
+### Core File Operations
+- `read_file` - Read file contents
+- `write_file` - Write content to files
+- `list_dir` - List directory contents
+
+### Multi-File Operations
+- `multi_edit` - Batch edit multiple files
+- `batch_operations` - Execute multiple file operations
+
+### Code Analysis
+- `analyze_code` - Analyze code metrics
+- `extract_functions` - Extract function names
+- `find_references` - Find symbol references
+- `search_code` - Search code patterns
+- `format_code` - Auto-format code
+- `lint_code` - Run linters
+
+### Git Operations
+- `git_operation` - Execute git commands (status, commit, push, diff, etc.)
+
+### Project Intelligence
+- `project_context` - Analyze project structure
+- `security_scan` - Scan for vulnerabilities
+
+### External Operations
+- `run_command` - Execute shell commands
+- `web_search` - Search the web for information
+- `test_runner` - Auto-detect and run tests
+
+## 📋 Tool Arguments Reference
+
+### Common Arguments
+
+**File Operations**:
+```json
+{
+  "path": "relative/or/absolute/path"
+}
+```
+
+**Git Operations**:
+```json
+{
+  "operation": "status|add|commit|push|pull|diff|log|branch",
+  "files": "optional file pattern",
+  "message": "commit message for commits",
+  "branch": "branch name for branch operations"
+}
+```
+
+**Multi-Edit Operations**:
+```json
+{
+  "operations": [
+    {"file": "path1", "old": "text to replace", "new": "replacement text"},
+    {"file": "path2", "old": "another text", "new": "new text"}
+  ]
+}
+```
+
+**Command Execution**:
+```json
+{
+  "command": "shell command to execute"
+}
+```
+
+## 🔍 Parsing Logic
+
+Del uses a **universal parser** that tries formats in this order:
+
+1. **Chinese Model Format** (most common)
+2. **OpenAI XML Format**
+3. **OpenAI JSON Format** 
+4. **Llama Format**
+5. **Markdown Format**
+6. **Legacy Del Format**
+
+The first matching format is used. This ensures maximum compatibility across different models.
+
+## 🛡️ Safety Features
+
+Del includes a **safe mode** system that requires confirmation for dangerous operations:
+
+**Sensitive Operations** (require confirmation):
+- File writes (`write_file`, `multi_edit`)
+- Git commits/pushes (`git_operation` with commit/push)
+- Shell commands with dangerous patterns (`run_command` with rm, sudo, etc.)
+- Code formatting (`format_code`)
+
+**Toggle Safety**:
+- `safe` - Toggle safe mode on/off
+- `unsafe` - Disable safe mode (use with caution!)
+
+## 🧪 Testing Tool Calls
+
+You can test tool call parsing by asking Del to perform various operations:
+
+**File Operations**:
+- "show me the main function" → `read_file`
+- "list files in this directory" → `list_dir`
+
+**Git Operations**:
+- "what's the git status?" → `git_operation`
+- "commit these changes" → `git_operation`
+
+**Analysis**:
+- "analyze this project" → `project_context`
+- "scan for vulnerabilities" → `security_scan`
+
+## 🔧 Model-Specific Tips
+
+### DeepSeek Coder
+- Naturally uses Chinese format
+- May include fake output blocks (Del filters these out)
+- Works best with explicit tool requests
+
+### Qwen2.5 Coder
+- Consistent Chinese format usage
+- Good at following tool calling instructions
+- Reliable JSON argument formatting
+
+### CodeLlama
+- May use Llama format or custom variations
+- Sometimes needs explicit prompting for tool use
+- Works well with function-style requests
+
+### GPT Models (via Ollama)
+- Usually XML format if configured for tools
+- May fall back to JSON format
+- Excellent at understanding tool requirements
+
+## 🚨 Troubleshooting
+
+### Tool Not Detected
+1. Check if model is using a supported format
+2. Verify tool name spelling
+3. Enable debug mode to see parsing attempts
+
+### Invalid Arguments
+1. Ensure JSON syntax is correct
+2. Check argument names match tool requirements
+3. Use empty `{}` for tools with no arguments
+
+### Permission Denied
+1. Check if safe mode is blocking the operation
+2. Use `unsafe` command to disable (carefully)
+3. Confirm tool arguments for dangerous operations
+
+### Model Hallucinating Results
+- Del's two-stage system prevents this
+- If you see fake `<｜tool▁outputs▁begin｜>` blocks, they're filtered out
+- Only real tool execution results are shown
+
+## 📈 Extending Support
+
+To add support for new tool call formats:
+
+1. Add a new parser function following the pattern:
+   ```go
+   func (d *Del) parseNewFormat(response string) []ToolCall
+   ```
+
+2. Add it to the parsing chain in `parseToolCalls()`
+
+3. Test with the target model format
+
+4. Update this documentation
+
+## 🔗 Related Files
+
+- `cmd/del/main.go` - Main implementation with all parsers
+- `README.md` - General Del documentation
+- `CLAUDE.md` - Project-specific instructions
+
+## 💡 Best Practices
+
+1. **Use explicit requests**: "scan for vulnerabilities" vs "check security"
+2. **Specify paths**: Include relative paths for file operations
+3. **Test safety**: Use safe mode for destructive operations
+4. **Verify results**: Del shows real tool execution output
+5. **Model selection**: Choose models that follow instructions well
+
+---
+
+*Del supports universal tool calling across 6+ major AI model formats, ensuring consistent functionality regardless of your chosen model.*
\ No newline at end of file