openclaw - 💡(How to fix) Fix [Feature]: Plugin hook hard routing: forced automatic subagent delegation

Summary

before_prompt_build hook can only inject soft rules (system context), cannot force AI to execute sessions_spawn. Plugin detects complex tasks but AI may ignore the routing suggestion and process in main session, wasting tokens.

Problem to solve

OpenClaw plugins can detect task complexity (via LLM classification or regex heuristics), but the only mechanism to act on that detection is appendSystemContext — a soft rule that AI may ignore. There is no gateway-level API to force a task into a subagent session.

Proposed solution

Add a gateway-level routing API or config option that can force specific tasks to be delegated to subagent sessions without relying on AI compliance. Possible approaches:

1. Hook-level sessions_spawn capability
2. Config-based task routing rules (e.g., regex patterns → target agent)
3. REST API endpoint for creating sub-sessions
4. A dispatch_mode option in agent config ("auto" | "main" | "always_subagent")

Alternatives considered

1. Prompt-based routing rules in AGENTS.md/HEARTBEAT.md (current workaround — unreliable, AI ignores soft rules)
2. External orchestrator script monitoring tasks (complex, fragile)
3. Separate bot instances for different task types (operational overhead)

Impact

All OpenClaw users running multi-agent setups who want automatic task delegation to reduce main session token usage and improve task isolation.

Evidence/examples

Workaround: subsession-router plugin (v1.0.0) using LLM+regex classification to append routing suggestions via appendSystemContext. Works ~70% of the time but AI sometimes ignores the routing directive.

OpenClaw version: 2026.4.21

Additional information

Must be backward-compatible with existing plugin API. Should not break current sessions_spawn behavior. Gateway-level config preferred over code changes.