Document subagent model selection and troubleshooting based on discovered workflow

system/subagent_usage_guide.md

@@ -0,0 +1,91 @@
+---
+description: Guide for running subagents effectively - model selection and troubleshooting
+limit: 2000
+---
+# Subagent Usage Guide
+
+## Model Selection
+
+When running subagents via the Task tool, always specify a valid model from the available list.
+
+### Available Models (as of current system)
+- `kimi-k2.5-nvfp4` - Fast, reliable
+- `kimi-k2.5` - Standard option, works well
+- `glm-4.7-flash` - Lightweight
+- `glm-4.7` - Standard GLM
+- `kimi-k2-thinking` - For reasoning tasks
+- `minimax-m2.5` - Alternative option
+- `qwen3.5` - Qwen series
+- `deepseek-v3.2` - DeepSeek
+- `deepseek-r1` - Reasoning-focused
+- `qwen3-coder` - Code-specific
+- `llama-3.3-70b` - Llama series
+- `sonnet` - Anthropic proxy (uses kimi-k2.5-nvfp4)
+- `haiku` - Lightweight proxy
+- `opus` - Heavy proxy (uses kimi-k2.5-nvfp4)
+- `nemotron-3-super` - NVIDIA model
+- `gpt-oss-120b` - OpenAI OSS
+
+### Preferred Models
+- **For exploration/research**: `kimi-k2.5` or `kimi-k2.5-nvfp4`
+- **For coding tasks**: `qwen3-coder` or `glm-4.7-flash`
+- **For complex reasoning**: `kimi-k2-thinking` or `deepseek-r1`
+
+## Common Errors
+
+### 500 Internal Server Error
+```
+InternalServerError2: 500 {"detail":"An unknown error occurred"}
+```
+
+**Causes:**
+- Letta server resource issue
+- Subagent creation endpoint failure
+- Transient server error
+
+**Resolution:**
+- Retry the same request
+- Try a different model
+- Use direct shell search as fallback
+
+### Unknown Model Error
+```
+Error: Unknown model "claude-sonnet-4"
+Available models: ...
+```
+
+**Resolution:**
+- Check available models list
+- Use a valid model name from the list
+- Do NOT use "claude" models (user preference)
+
+## Best Practices
+
+1. **Always specify model explicitly** to avoid ambiguity
+2. **Use kimi-k2.5 or kimi-k2.5-nvfp4** as safe defaults
+3. **Prefer lighter models** for simple exploration tasks
+4. **Retry on 500 errors** - often transient
+5. **Fall back to direct shell/Bash** if subagents fail repeatedly
+
+## Example Usage
+
+```typescript
+Task({
+  description: "Explore codebase",
+  prompt: "Find all files that...",
+  subagent_type: "explore",
+  model: "kimi-k2.5"  // Always specify
+})
+```
+
+## Troubleshooting Workflow
+
+1. Subagent fails with 500? → Retry with same model
+2. Still failing? → Try different model (glm-4.7-flash, qwen3.5)
+3. Still failing? → Use Bash/Grep/Glob directly
+4. Document what worked for future reference
+
+---
+
+Last updated: 2026-03-21
+Discovered during: Matrix bridge formatting investigation