Add documentation for agent model delegation fix

Document the solution to OpenCode/Claude Code issue where LLMs cannot properly delegate to specific model tiers when using subagents.
2026-02-07 15:06:48 -08:00
parent c062f687d2
commit c1e2f1e86c
1 changed files with 161 additions and 0 deletions
@@ -0,0 +1,161 @@
+# Agent Model Delegation Issue - Solution
+
+## Problem
+
+LLMs cannot delegate to specific models for subagents in a way that ensures the right model tier is used according to task requirements.
+
+### Symptoms
+
+- LLMs default to most expensive models when delegating
+- LLMs don't know which model tier each agent type uses
+- No automatic visibility into agent definitions before delegation
+- Cost inefficiency from using higher-tier models than necessary
+
+## Root Cause
+
+When an LLM wants to delegate work via the Task tool, it needs to:
+1. Know which agent types exist
+2. Know which model tier each agent type uses
+3. Select appropriate agent based on task complexity
+
+But agent definitions (with `model` field in YAML frontmatter) are stored in `~/.claude/agents/*.md` files that are not automatically loaded into LLM's context.
+
+## Solution
+
+Three-part approach to make agent information visible to LLMs:
+
+### 1. Enhanced System Instructions
+
+**File:** `state/system-instructions.json`
+
+Updated `model-selection` process to include:
+- Pre-flight check requirement: "Before using Task tool, MUST check agent model"
+- Explicit model tier definitions
+- Decision flow for model selection
+- Agent lookup command reference
+
+### 2. Enhanced CLAUDE.md Documentation
+
+**File:** `CLAUDE.md`
+
+Added to "Model Selection (MANDATORY)" section:
+- **CRITICAL** checklist before delegating
+- Steps to verify agent model tier
+- Alternative strategies when agent uses higher-tier model
+- References to state files for lookup
+
+### 3. Quick Reference Guide
+
+**File:** `state/model-selection-guide.md`
+
+New standalone guide with:
+- Model tier decision table
+- Available agents grouped by model tier
+- Decision flow diagram
+- How to use `/agent-info` command
+- Escalation rules
+
+## How It Works
+
+### Before Delegation (Pre-Flight Check)
+
+LLM is now instructed to:
+
+```markdown
+Before delegating to a specific agent, you MUST:
+1. Read state/model-policy.json to verify which model tier that agent uses
+2. Read state/component-registry.json to check agent triggers and descriptions
+3. Match task complexity to agent's model tier (not just agent name)
+```
+
+### Agent Registry Sources
+
+Two sources provide agent information:
+
+**state/model-policy.json**
+- Full model tier mappings
+- Use cases for each tier
+- Which agents use which model
+- Escalation rules between tiers
+
+**state/component-registry.json**
+- All registered agents, skills, commands
+- Agent triggers and descriptions
+- Hierarchical relationships
+- Auto-generated from agent files
+
+**/agent-info command**
+- Interactive listing of all agents
+- Show hierarchy tree
+- Get details for specific agent
+
+### Model Selection Flow
+
+```
+Task comes in
+    │
+    ├─ Check state/model-policy.json
+    │   └─ Find agent name → Look up model tier
+    │
+    ├─ Evaluate task complexity
+    │   ├─ Mechanical with clear instructions? → haiku
+    │   ├─ Needs code understanding? → sonnet
+    │   └─ Complex reasoning/coordination? → opus
+    │
+    └─ Match task to agent with appropriate tier
+        ├─ Agent uses matching tier? ✓ Use it
+        ├─ Agent uses higher tier? → Find alternative or escalate
+        └─ Agent uses lower tier? → Escalate if needed
+```
+
+## Files Modified
+
+1. `~/.claude/state/system-instructions.json` - Enhanced model-selection process
+2. `~/.claude/CLAUDE.md` - Added CRITICAL pre-delegation checklist
+3. `~/.claude/state/model-selection-guide.md` - New quick reference guide
+
+## Testing
+
+To verify the fix works:
+
+1. **Test model selection awareness:**
+   ```
+   Ask LLM to delegate a simple grep task
+   Expected: LLM checks agent models, selects haiku-tier agent
+   ```
+
+2. **Test escalation flow:**
+   ```
+   Ask LLM to design a complex system
+   Expected: LLM checks agent models, uses opus-tier agent
+   ```
+
+3. **Test cost optimization:**
+   ```
+   Ask LLM to review a PR
+   Expected: LLM verifies code-reviewer uses sonnet (not opus)
+   ```
+
+4. **Test agent-info usage:**
+   ```
+   Ask LLM which agents are available
+   Expected: LLM runs /agent-info or reads component registry
+   ```
+
+## Future Improvements
+
+1. **Tool-based agent lookup:** Add a tool that exposes agent info to LLM programmatically (like Flynn's `agents.list` tool)
+
+2. **Automatic context injection:** Automatically load agent registry into LLM's initial context rather than requiring explicit read
+
+3. **Model tier parameter in Task tool:** Allow specifying model tier directly when delegating, not just agent type
+
+4. **Cost-aware delegation:** Track actual cost per agent delegation and provide feedback
+
+## Related Files
+
+- `~/.claude/agents/*.md` - Agent definitions with model field
+- `~/.claude/state/model-policy.json` - Full model selection policy
+- `~/.claude/state/component-registry.json` - Generated agent registry
+- `~/.claude/automation/agent-info.py` - Agent info script
+- `~/.claude/commands/agent-info.md` - Agent info command