Orchestrator agents cannot delegate to sub-agents at runtime

[akj]

Category

Improve existing agent

What would you like?

In Claude Code, orchestrator agents (web-accessibility-wizard, document-accessibility-wizard, accessibility-lead, developer-hub, markdown-a11y-assistant) describe detailed sub-agent delegation models in their instructions, but cannot actually delegate at runtime. When spawned as sub-agents via the Agent tool, they only receive filesystem tools (Read, Write, Edit, Bash, Grep, Glob). The Task tool is not available to them regardless of what the tools: frontmatter declares.

This was confirmed through diagnostic testing: even accessibility-lead, which declares Task in its frontmatter, reports only Read, Glob, and Grep at runtime. The orchestrator agents end up doing all work inline rather than delegating to specialists.

Note: This issue is specific to the Claude Code runtime. Other supported platforms (e.g., GitHub Copilot) have different delegation mechanisms and may not be affected.

Use case

Any workflow that requires coordination across multiple accessibility domains is affected. For example:

• /audit (web-accessibility-wizard) is supposed to delegate to aria-specialist, keyboard-navigator, forms-specialist, contrast-master, etc. — but currently does everything inline
• /document (document-accessibility-wizard) is supposed to delegate to word-accessibility, pdf-accessibility, etc. — but currently does everything inline
• accessibility-lead is supposed to coordinate the full specialist team for any UI task — but currently can only read and search files

The result is that orchestrator agents produce lower-quality output than they would if they could actually leverage specialist agents, and the elaborate delegation models in their instructions are never executed.

Examples

Diagnostic test

Spawning document-accessibility-wizard and asking it to list its available tools:

Tools available: Read, Write, Edit, Bash, Grep, Glob
Task tool: No
Agent tool: No

The agent's instructions describe delegating to word-accessibility via Task, but it has no mechanism to do so.

Same result for accessibility-lead (which declares Task in frontmatter):

Tools available: Read, Glob, Grep
Task tool: No

Impact

The tools: frontmatter is read by the agent registry for display purposes, but the Claude Code runtime does not inject Task or Agent into spawned sub-agents. Sub-agents cannot spawn sub-agents — only the top-level conversation has access to the Agent tool.

[akj]

Proposed fix: skills-based orchestration for Claude Code

One approach that would work within Claude Code's runtime constraints:

Convert orchestrator agents to skills. Skills inject instructions into the top-level conversation context, where the Agent tool IS available. A skill-based orchestrator can spawn specialist agents in parallel, compile their results, and coordinate multi-phase workflows.

Keep specialist agents as-is. Agents like aria-specialist, keyboard-navigator, forms-specialist, word-accessibility, etc. are leaf-level workers that don't need to delegate. They work well as agents.

Why this works

• Skills run at the top level → full tool access, including Agent for spawning specialists
• Enables parallel specialist dispatch (e.g., aria-specialist + keyboard-navigator + forms-specialist concurrently)
• Only the top level needs to orchestrate — no nested delegation required
• The existing agent instructions contain valuable domain knowledge and would mostly transfer directly into skill format

Migration scope

1. Convert the ~5 orchestrator agent files into skills
2. Keep the ~55 specialist/helper agent files unchanged
3. Update CLAUDE.md slash commands to invoke skills instead of agents

Expected result

User invokes /audit
  → Skill injects orchestration instructions at top level
  → Top level spawns aria-specialist agent (parallel)
  → Top level spawns keyboard-navigator agent (parallel)
  → Top level spawns forms-specialist agent (parallel)
  → Results compiled into unified audit report

This would be a Claude Code-specific change and wouldn't affect the Copilot or other platform configurations.

[Orinks]

I believe agent teams need to be enabled in Claude Code config in order for this to work. Looks like my Claude Code is spawning agents just fine. I did a full accessibility audit where fixes were made after the report.

[akj]

@Orinks Agent teams spawn fully independent Claude instances with their own context windows. That's a different model from what the orchestrator agents describe — a wizard coordinating focused specialist reviews and compiling results. Agent teams also cost ~7x more tokens than subagents, which is significant for routine audits.

The core issue is narrower: when an orchestrator agent (like document-accessibility-wizard) is spawned as a subagent, it cannot spawn its own subagents. The Task/Agent tool isn't available at that level. If your audits are working, it's likely because the top-level Claude is doing the orchestration — which is exactly what the skills-based approach would formalize.

The architecture doc's concern about skills (low activation rates without intervention) is valid for always-on background guidance. But orchestrator skills invoked explicitly via slash commands (/audit, /document) don't have that problem — the user is directly triggering them.