diff options
Diffstat (limited to 'packages/multillm-claude/README.md')
| -rw-r--r-- | packages/multillm-claude/README.md | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/packages/multillm-claude/README.md b/packages/multillm-claude/README.md index a2e242b..e5a47ad 100644 --- a/packages/multillm-claude/README.md +++ b/packages/multillm-claude/README.md @@ -112,6 +112,128 @@ Specify the model after the provider prefix: - `claude/claude-sonnet-4-20250514` - Claude Sonnet - `claude/claude-opus-4-20250514` - Claude Opus +## Tool Support + +### Supported Tools + +These tools work correctly with the Claude Agent SDK provider: + +| Tool | Description | Permission Required | +|------|-------------|---------------------| +| `Bash` | Execute bash commands | Yes | +| `Read` | Read files from filesystem | No | +| `Write` | Create or overwrite files | Yes | +| `Edit` | Edit existing files | Yes | +| `Glob` | Find files by pattern | No | +| `Grep` | Search file contents | No | +| `Task` | Launch sub-agents | Varies | +| `WebFetch` | Fetch web content | No | +| `WebSearch` | Search the web | No | +| `NotebookEdit` | Edit Jupyter notebooks | Yes | +| `KillShell` | Kill background shells | Yes | +| `EnterPlanMode` | Enter planning mode | No | +| `ExitPlanMode` | Exit planning mode | No | + +### Interactive Tools + +| Tool | CLI Support | Notes | +|------|-------------|-------| +| `AskUserQuestion` | ✅ **Auto-converts** | CLI automatically uses custom `ask_user` tool | +| Custom tools | ✅ Full support | Provide Tool objects with interactive handlers | + +**About Interactive Tools with Claude:** + +The Claude Agent SDK's built-in `AskUserQuestion` runs in a subprocess and can't access our terminal's stdin/stdout for interactive prompting. To solve this, **multillm-cli automatically provides a custom interactive tool** when you request `AskUserQuestion`. + +**What happens:** + +When you use `--allowed-tools AskUserQuestion`, the CLI: +1. Removes the built-in AskUserQuestion (which doesn't work interactively) +2. Adds a custom `ask_user` tool with an interactive handler +3. The agent uses this tool instead, with full interactive support + +**Usage:** + +```bash +# Request AskUserQuestion - CLI auto-provides working alternative +multillm -m claude/default \ + -p "Ask me about my preferences and create a summary" \ + --allowed-tools AskUserQuestion \ + --permission-mode acceptEdits +``` + +**What you'll see:** +``` +ℹ️ Using custom 'ask_user' tool instead of AskUserQuestion for interactive prompting + +====================================================================== +❓ QUESTION FROM ASSISTANT +====================================================================== + +What is your favorite programming language? + +Suggested options: + 1. Python + 2. JavaScript + 3. Rust + +Your answer: 1 +====================================================================== +``` + +**Programmatic usage:** + +For programmatic use, provide your own `ask_user` tool with an interactive handler: + +```python +import multillm + +# Define interactive ask_user tool +ask_user_tool = multillm.Tool( + name="ask_user", + description="Ask the user a question", + parameters={ + "type": "object", + "properties": { + "question": {"type": "string"}, + "options": {"type": "array", "items": {"type": "string"}} + }, + "required": ["question"] + }, + handler=lambda args: { + "answer": input(f"\n{args['question']}\nYour answer: ") + } +) + +# Use with Claude +async for msg in client.run( + "claude/default", + "Ask me questions", + options=multillm.AgentOptions(max_turns=10), + tools=[ask_user_tool] # Provide custom tool +): + if msg.type == "text": + print(msg.content) +``` + +**Why not use the built-in AskUserQuestion?** + +The SDK's built-in `AskUserQuestion` is designed for Claude Code CLI's interactive mode where the subprocess has special stdin/stdout handling. In multillm, this doesn't work because: +- The SDK subprocess can't access our terminal +- We can't intercept and respond to built-in tool calls +- The tool returns an error instead of prompting + +**Solution:** Use custom tools (which the CLI provides automatically!) + +**Comparison:** + +| Approach | Works? | How | +|----------|--------|-----| +| `--allowed-tools AskUserQuestion` | ✅ Yes | CLI auto-converts to custom tool | +| Custom `ask_user` Tool | ✅ Yes | Provide Tool object with handler | +| SDK built-in (direct) | ❌ No | Subprocess can't access stdin/stdout | +| Chat provider `ask_user` | ✅ Yes | Via agentwrap | + ## Agent Options ```python @@ -135,3 +257,69 @@ When streaming with `client.run()`: | `tool_result` | Result from a tool | | `result` | Final result | | `system` | System messages | + +## Debugging + +### Enable Debug Mode + +Set the `MULTILLM_DEBUG` environment variable to see detailed error information and SDK options: + +```bash +export MULTILLM_DEBUG=1 +python your_script.py +``` + +This will show: +- Detailed error messages with full stderr/stdout +- SDK configuration options +- Full Python tracebacks + +### Common Issues + +**Error: "Command failed with exit code 1"** + +The provider now captures and displays all available error information to stderr. Look for: + +``` +====================================================================== +CLAUDE AGENT SDK ERROR +====================================================================== +Error: <detailed error message> + +Error Details: + stderr: <actual error from subprocess> + stdout: <subprocess output> + exit_code: 1 +====================================================================== +``` + +**Authentication Errors:** +```bash +# Check authentication status +claude login --check + +# Re-authenticate if needed +claude login +``` + +**Permission Errors:** + +Always specify `permission_mode` when using tools: + +```python +result = await client.single( + "claude/default", + "List files", + allowed_tools=["Bash"], + permission_mode="acceptEdits" # Required! +) +``` + +### Full Debugging Guide + +See [DEBUGGING.md](./DEBUGGING.md) for comprehensive debugging information, including: +- How to read error messages +- Common issues and solutions +- Debug mode usage +- Testing error handling +- Reporting bugs |