flynn/AGENT-MODEL-DELEGATION-FIX.md

# 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