feat(hierarchy): General-purpose hierarchical behavior system for multi-tier agent orchestration

[aspotton]

Spacebot supports running multiple agents with different roles and responsibilities. But when agents need to work together in a hierarchy — where Agent A delegates to Agent B, which delegates to Agent C — the system broke down. Agents didn't know how to delegate properly, didn't report results back up the chain, and created endless status-check loops.

This PR implements a general-purpose hierarchical behavior system that works for any tiered agent structure, not just specific presets. Whether you have a 2-tier setup (Manager → Worker) or a 5-tier org chart (Director → Manager → Team Lead → Engineer → Intern), the system automatically equips every agent with the right rules based on its position in the hierarchy.

The Problem (Generalized)

When agents are linked hierarchically:

• Superiors (agents with subordinates) didn't know how to delegate without spawning workers directly
• Subordinates (agents with superiors) didn't know how to report findings back
• Middle-tier agents (both superiors and subordinates) got stuck in infinite loops of status-check tasks
• No automatic synthesis — results didn't flow back up the chain in a usable format
• Polling spam — agents would call task_get or task_list 15+ times instead of waiting for notifications

The result: broken delegation chains, missing findings, and agents creating tasks to check on other tasks.

The Solution

A programmatic hierarchical behavior injection system that:

1. Detects hierarchy automatically — Based on link structure, not preset names or ROLE.md content
2. Injects position-appropriate rules — Agents get rules for their specific position (superior, subordinate, or both)
3. Enforces delegation compliance — Anti-bounce rules, mandatory metadata reporting, synthesis requirements
4. Works for any hierarchy depth — From 2-tier to 10-tier org charts

How It Works (Any Hierarchy)

Tier 1: Director (superior only)
    ↓ send_agent_message
Tier 2: Manager (superior + subordinate)
    ↓ send_agent_message
Tier 3: Team Lead (superior + subordinate)
    ↓ send_agent_message
Tier 4: Engineer (subordinate only)
    ↓ completes work → writes metadata → signals outcome
    ↑ cortex notification
Tier 3: Team Lead (receives notification, reads metadata, synthesizes)
    ↑ sends synthesized report via send_agent_message
Tier 2: Manager (receives synthesis, adds context, reports up)
    ↑ sends synthesized report via send_agent_message
Tier 1: Director (receives final synthesis, responds to user)

Key: Every agent in the chain automatically gets:

• Rules for receiving work from superiors
• Rules for delegating to subordinates (if applicable)
• Rules for reporting findings to superiors
• Anti-bounce protections (no status-check tasks, no excessive polling)
• Role awareness (sees who they report to and who reports to them)

Core Features

1. Position-Based Rule Injection

Rules are injected based on link structure, not agent names or presets:

• Agents with superiors get rules for receiving delegated work and reporting findings
• Agents with subordinates get rules for delegating properly and synthesizing results
• Agents with both get both sets of rules (middle-tier agents)
• Agents with no links see zero change (standalone agents unaffected)

2. Universal Anti-Bounce Protection

All hierarchical agents follow these rules:

• No status-check tasks — Forbidden: "Check on task #X", "Any ETA?", "Any blockers?"
• Use wait_for_task() — Block internally instead of polling
• One-time task_list() calls — Call once with broad filters, then wait for notifications
• Trust the cortex — Completion notifications arrive automatically

3. Mandatory Findings Reporting (Critical)

Before signaling completion, agents MUST:

• Call task_update(metadata={...}) with complete findings
• Include: what was accomplished, key findings, files created/modified, blockers
• Only then call set_status(kind: "outcome")

Why this matters: Without metadata, superiors can't see the work and will create follow-up tasks. This prevents the "I can't see your findings" infinite loop.

4. Synthesis Requirements

Agents with subordinates must:

• Wait for ALL subordinate results before reporting up
• Synthesize findings into structured summaries (not raw forwarding)
• Add context and analysis before passing results to superiors
• Only escalate actual blockers, not status requests

5. Role Awareness

Every agent sees:

• Who they report to (superiors with names and roles)
• Who reports to them (subordinates with names and roles)
• Their position in the hierarchy (top-tier, middle-tier, or bottom-tier)

Example org context:

You report to: Director (strategic oversight)
Your subordinates: 
  - Senior Engineer (technical implementation)
  - Data Analyst (research and analysis)

Configuration (Any Hierarchy)

# Example: 4-tier hierarchy
[[agents]]
id = "director"
preset = "custom-agent"
display_name = "Director"

[[agents]]
id = "manager"
preset = "custom-agent"
display_name = "Manager"

[[agents]]
id = "team-lead"
preset = "custom-agent"
display_name = "Team Lead"

[[agents]]
id = "engineer"
preset = "custom-agent"
display_name = "Engineer"

# Link them hierarchically
[[links]]
from = "director"
to = "manager"
direction = "two_way"
kind = "hierarchical"

[[links]]
from = "manager"
to = "team-lead"
direction = "two_way"
kind = "hierarchical"

[[links]]
from = "team-lead"
to = "engineer"
direction = "two_way"
kind = "hierarchical"

Result: Each agent automatically gets rules for its position:

• Director: Rules for delegating to Manager
• Manager: Rules for receiving from Director + delegating to Team Lead
• Team Lead: Rules for receiving from Manager + delegating to Engineer
• Engineer: Rules for receiving from Team Lead + reporting findings

What Changed

New Files:

• prompts/en/fragments/hierarchical_rules.md.j2 — Agent-agnostic hierarchical rules template (works for ANY hierarchy)
• src/tools/wait_for_task.rs — Blocking tool that eliminates polling spam

Modified Files:

• src/prompts/engine.rs — HierarchicalRulesContext, build_hierarchical_rules_for_agent()
• src/prompts/text.rs — Template registration
• prompts/en/channel.md.j2 — {{ hierarchical_rules }} placeholder
• src/agent/channel.rs — Build and pass hierarchical rules
• src/agent/cortex.rs — Inject rules into delegated worker prompts
• presets/boss-agent/ROLE.md — Removed duplicate rules (now injected)
• presets/planning-lead/ROLE.md — Removed duplicate rules (now injected)

Use Cases (Beyond Boss/Planning Lead)

This system enables any hierarchical workflow:

Research Pipeline:

Principal Investigator → Research Lead → Data Analyst → Data Collector

Content Production:

Editor-in-Chief → Section Editor → Writer → Researcher

Customer Support:

Support Manager → Senior Agent → Junior Agent

Software Development:

CTO → Engineering Manager → Tech Lead → Developer → QA Engineer

Media Production:

Executive Producer → Director → Cinematographer → Editor

In every case, the system automatically:

• Injects the right rules for each position
• Ensures proper delegation and reporting
• Prevents polling spam and missing findings
• Synthesizes findings up the chain

Testing Evidence

Before (any hierarchy):

• Superiors spawned workers directly (bypassed delegation)
• Middle-tier agents created 15+ status-check tasks
• Subordinates completed work with no findings in metadata
• Results didn't flow back up the chain

After (any hierarchy):

• Superiors delegate via send_agent_message
• Middle-tier agents wait for notifications, synthesize results
• Subordinates write findings to metadata before signaling completion
• Full results flow back up the chain with proper synthesis
• Zero status-check tasks created

Why This Matters

This isn't a "boss agent fix" — it's a general-purpose orchestration layer for multi-agent systems. Now you can:

• Build arbitrary hierarchy depths (2-tier, 5-tier, 10-tier — doesn't matter)
• Mix and match agent types in any configuration
• Trust that delegation chains will work correctly
• Get synthesized, actionable results at every level
• Avoid task spam and missing findings

Design Decisions

Why prompt-level rules instead of runtime enforcement?

• Flexibility: Different hierarchies may need different behaviors
• Simplicity: No complex validation logic in the core system
• Extensibility: Rules can be customized per hierarchy without code changes

Why metadata-based reporting?

• Persistence: Findings are stored with the task for future reference
• Synthesis: Superiors can read the full context before making decisions
• Audit trail: Complete record of what was done at each level

Why wait_for_task instead of polling?

• Efficiency: One blocking call vs. 15+ polling calls
• Cleanliness: No status-check tasks created
• Reliability: Cortex notifications are guaranteed to arrive

Future Work (Not Included)

• Exponential backoff in wait_for_task (currently fixed 5s interval)
• Hierarchical rules for branch prompts (currently only channels/workers)
• Per-hierarchy configurable rules (currently uniform across all)
• Visual hierarchy builder in the UI

---

Key Message: This is a general-purpose hierarchical system. It works for ANY tiered agent structure, not just the boss/planning-lead/assistant example we tested. If you can link agents hierarchically, they'll automatically get the right rules for their position and work together seamlessly.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fbcaf18c-f497-4f46-899e-066c89298b80

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}