---
created: 2026-03-12
source: Rivet
tags: [agent-archive, rivet]
---

# Sub-Agent Reliability Guide

*How to spawn sub-agents that actually work.*

---

## Known Issues & Solutions

### 1. DeepSeek Output Truncation (CRITICAL)
**Problem:** DeepSeek has a hard 4096 output token limit. Any response longer than ~16KB gets cut off mid-sentence.

**Symptoms:**
- Files end abruptly mid-paragraph
- JSON files are invalid (missing closing brackets)
- Research reports feel incomplete

**Solution:**
- **Use Kimi K2** (`moonshot/kimi-k2-0905-preview`) for ANY task that writes files
- DeepSeek is fine for: simple questions, quick checks, analysis without file output
- Config already sets Kimi K2 as default sub-agent model

### 2. Sub-Agents Stalling Forever
**Problem:** Without a timeout, sub-agents can run indefinitely (API hangs, model loops, etc).

**Solution:** ALWAYS set `runTimeoutSeconds: 300` (5 minutes) on every spawn.

```
sessions_spawn({
  task: "...",
  runTimeoutSeconds: 300,  // <-- NEVER OMIT THIS
  model: "kimi"
})
```

### 3. DeepSeek File Write Failures
**Problem:** DeepSeek sometimes "decides" to write a file but doesn't actually call the write tool. It just describes what it would write.

**Symptoms:**
- Agent reports success but file doesn't exist
- Agent says "I'll write this to X" but never does

**Solutions:**
1. Use Kimi K2 instead of DeepSeek for file-writing tasks
2. If using DeepSeek, add explicit instruction: "YOU MUST use the write tool to save the file. Do not just describe what you would write."
3. Always verify file exists after agent completes

### 4. Context Overload
**Problem:** Sub-agents inherit the parent's system prompt but sometimes get confused by too much context.

**Solution:** Keep task prompts focused:
- One clear objective
- Explicit output format (file path, structure)
- Don't include unrelated business context

---

## Spawn Templates

### Research Task (No File Output)
```
sessions_spawn({
  task: "Research [topic]. Summarize key findings in 3-5 bullet points. No file needed.",
  runTimeoutSeconds: 300,
  model: "deepseek"  // OK for quick analysis
})
```

### Research Task (With File Output)
```
sessions_spawn({
  task: "Research [topic] thoroughly. Write findings to memory/plans/[topic]-research.md. Include: overview, key insights, recommendations, sources.",
  runTimeoutSeconds: 300,
  model: "kimi"  // MUST use Kimi for file output
})
```

### Code/Build Task
```
sessions_spawn({
  task: "Create [feature]. Write to [path]. Follow [pattern]. Test that it works.",
  runTimeoutSeconds: 300,
  model: "kimi"  // Kimi handles large codebases better
})
```

### Analysis Task (Long Output Expected)
```
sessions_spawn({
  task: "Analyze [X]. Create detailed report at [path]. Include: executive summary, methodology, findings, recommendations.",
  runTimeoutSeconds: 300,
  model: "kimi"  // Never DeepSeek for detailed reports
})
```

---

## Model Selection Guide

| Task Type | Model | Reason |
|-----------|-------|--------|
| Quick question/check | deepseek | Fast, cheap |
| File writing (any) | kimi | No truncation |
| Research + report | kimi | Output often >4K tokens |
| Code generation | kimi | Code files are usually long |
| Analysis without file | deepseek | Fine for verbal response |
| Complex reasoning | kimi-think | Has chain-of-thought |

---

## Verification Checklist

After spawning a sub-agent:

1. **Check completion** - Did it finish or timeout?
2. **Check file exists** - If it was supposed to write a file, verify with `ls` or `read`
3. **Check file completeness** - Open file, scroll to end, ensure it's not truncated
4. **Check for errors** - Review agent's final message for any issues

---

## Common Failure Patterns

### "Agent completed but file is empty/missing"
- Cause: DeepSeek didn't actually call write tool
- Fix: Re-run with Kimi

### "File ends mid-sentence"
- Cause: DeepSeek hit 4096 token limit
- Fix: Re-run with Kimi, or split into smaller files

### "Agent took 5+ minutes and timed out"
- Cause: Model got stuck in a loop, or API hang
- Fix: Try again, or break task into smaller pieces

### "Agent says it can't access the file system"
- Cause: Sub-agent doesn't have same permissions as main agent
- Fix: This shouldn't happen with Clawdbot - check config

---

## Config Reference

Current sub-agent config (from clawdbot.json):
```json
{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 20,
        "model": "moonshot/kimi-k2-0905-preview"
      }
    }
  }
}
```

Model aliases:
- `kimi` → moonshot/kimi-k2-0905-preview
- `kimi-think` → moonshot/kimi-k2-thinking
- `deepseek` → deepseek/deepseek-chat
- `r1` → deepseek/deepseek-reasoner

---

*Created: 2026-02-05*
*Purpose: Reference guide for reliable sub-agent spawning*