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:

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