Agent descriptions from .md files not available at task tool context generation time

[rysweet]

Agent Descriptions Not Available at Task Tool Context Generation Time

Summary

Agent descriptions defined in .md files are not visible to the task tool because they are populated after context generation. This creates a timing issue where the task tool shows "No description" for all agents that use file-based descriptions instead of inline bundle configuration.

Problem Description

Current Behavior

When agents are registered in a bundle with only a path:

# bundle.md
agents:
  my-bundle:my-agent: { path: agents/my-agent.md }

And the agent .md file contains frontmatter:

# agents/my-agent.md
---
name: my-agent
description: "This agent does X, Y, Z"
role: "Specialist in X"
---

The description is not available to the task tool at context generation time, resulting in "No description" being shown to the LLM.

Root Cause: Initialization Sequence

1. Bundle loads from bundle.md
   → Agents registered with { path: "..." } only
   → No descriptions in coordinator.config

2. Task tool context is generated
   → Reads agent metadata from bundle snapshot
   → Shows "No description" for file-based agents

3. Session starts
   → session:start hook runs
   → Populates descriptions from .md files into coordinator.config

4. Too late - context already generated

Why This Matters

• DRY Violation: Currently requires duplicating descriptions in both bundle.md AND .md files
• Maintenance burden: Keeping two sources in sync
• Poor UX: LLM sees incomplete agent metadata, can't make informed delegation decisions
• Scalability: Becomes worse as agent count grows

Expected Behavior

Agent descriptions should be available at context generation time, regardless of whether they're:

1. Inline in bundle configuration, OR
2. Defined in external .md files

Reproduction

1. Create a bundle with file-based agent:

   agents:
     test:file-agent: { path: agents/test-agent.md }

2. Create agents/test-agent.md:

   ---
   name: test-agent
   description: "Test agent description"
   ---

3. Load the bundle and query task tool agent metadata

4. Observe: description is empty/missing

Current Workarounds

Workaround 1: Inline Descriptions (What works today)

agents:
  my-bundle:my-agent:
    path: agents/my-agent.md
    description: "Duplicate description here"  # ← Duplication required

Problem: Violates DRY, maintenance burden

Workaround 2: Hook-Based Context Injection

Modify session-start hook to inject agent descriptions into context after loading from files.

Problem: Band-aid solution, doesn't fix root cause

Workaround 3: Build-Time Generation (automation)

Script extracts descriptions from .md files and auto-updates bundle.md.

Problem: Still duplication, just automated

Proposed Solution

Option A: Lazy Agent Metadata Resolution (Preferred)

Make the task tool query agent metadata from runtime coordinator state instead of the bundle configuration snapshot:

# Current (broken)
agents = bundle_config["agents"]  # Snapshot at load time

# Proposed (fixed)
agents = coordinator.config["agents"]  # Runtime state after hooks

Benefits:

• No duplication required
• Descriptions loaded once, used everywhere
• Supports dynamic agent registration
• Aligns with hook-based extension pattern

Implementation points:

1. Task tool should defer agent metadata queries until after session initialization
2. OR: Task tool should refresh agent metadata from coordinator on each invocation
3. OR: Add a hook point specifically for context generation that runs after session:start

Option B: Eager Agent Loading

Load agent .md files during bundle initialization, before context generation:

# During bundle load
for agent_key, agent_config in bundle["agents"].items():
    if "path" in agent_config:
        # Load .md file immediately
        loaded = load_agent_from_file(agent_config["path"])
        agent_config.update(loaded)  # Merge descriptions into config

Benefits:

• Fixes timing issue at the source
• No changes to task tool needed
• Descriptions available everywhere immediately

Trade-offs:

• Adds I/O during bundle load
• Makes bundle loading dependent on file availability

Technical Context

Relevant Files

amplifier-core:

• Where bundle configs are loaded
• Where task tool context is generated
• Where coordinator.config is managed

amplifier-foundation (if relevant):

• Session initialization sequence
• Hook execution order

Related Issues

• Bug: Agent instructions from .md files are never loaded in spawn pipeline #174 - Agent instructions from .md files not loaded in spawn pipeline
• feat(bundle): Add agent instruction loading from .md files amplifier-foundation#30 - Agent path resolution in spawn

Impact

Without fix:

• Every bundle author must choose: DRY violation OR incomplete metadata
• Agent descriptions duplicated in 2+ places
• Risk of desync between bundle.md and .md files

With fix:

• Single source of truth for agent metadata
• Cleaner bundle configurations
• Better LLM context with complete agent information

Environment

• Amplifier version: Latest (observed in amplihack bundle)
• Platform: Linux, but affects all platforms
• Bundle format: Standard Amplifier bundle with agent files

Additional Notes

This issue was discovered while investigating why the task tool showed "No description" for 20+ agents in the amplihack bundle, despite all agent .md files containing proper description: frontmatter fields.

The session-start hook successfully loads descriptions from .md files, but this happens after the task tool has already generated its context snapshot, making the timing problem the core issue.

---

Proposed Priority: Medium-High

• Affects all bundles using file-based agent definitions
• Currently requires workarounds that violate best practices
• Clear architectural improvement with measurable benefits