Crush Agent System Unified Evolution Roadmap (v2.0)

Version: v2.0 · Date: 2026-04-17 (updated from a full codebase audit) · Last updated: 2026-04-18

Scope: internal/agent, internal/agent/subagent, internal/agent/multiagent, internal/a2a, tool & UI coordination layers, and infrastructure modules.

This is a structured summary of a long roadmap post; original details, checklists, and Chinese documentation are preserved in the source.

Key points

• Problem: Multiple agent systems evolved in parallel — the agent tool (session-level delegation), subagent (async task engine), multiagent (role-based teaming), and a2a (Google A2A protocol server). This caused overlapping capabilities, duplicated concurrency/timeout/cancel logic, orphaned features (Worktree isolation fully implemented but disabled; send_message tool defined but unregistered; TokenUsage/LoopDetection middleware never invoked), fragmented observability, and unbalanced test coverage.
• Target architecture (three layers):
1. Execution Core — SessionAgent as the single LLM execution kernel. 2. Task Orchestration — subagent Executor as the unified delegation engine (state machine with 6 states, 5 middleware types, WorkerPool, SQLite/memory store, optional Worktree isolation). 3. Organization/Teaming — multiagent Manager (role registry with 7 roles, MessageBus with 8 message types, workspace isolation, persistence/recovery/hot-reload).
• Key finding from the audit: all three delegation paths converge on SessionAgent.Run(), but governance layers (concurrency, timeouts, state machines) were duplicated per path.

Stage progress

Stages 0–4 ✅ Complete

• Stage 0: Baseline observability (PubSub 13+ brokers, PostHog session events, subagent EventMetrics).
• Stage 1: Unified delegation abstraction (Delegator, DelegationRequest/Result, delegationstatus package).
• Stage 2: agent tool compatibility bridge (AgentParams = AgentToolV2Input alias, v2 via Delegator.DelegateSync()).
• Stage 3: Subagent production hardening — 30+ items: SQLite/memory backends, idempotency, backpressure, middleware chain with failure attribution, migration registry, configurable WAL/busy_timeout.
• Stage 4: Multiagent orchestration reuse — DelegationExecutor interface + gray-release flag, unified executeDelegationWithSession entry, task_state metadata mapping.

Stage 5: Execution Fusion & Productization ✅

• multiagent DelegationExecutor now truly routes through the subagent Executor (gray flag retained).
• Concurrency unified: multiagent migrated from execMu.TryLock() to the subagent WorkerPool semaphore model.
• TokenUsageMiddleware.RecordTokens() wired into AgentRunner.Execute() step callbacks; LoopDetectionMiddleware.CheckState() invoked per conversation turn; subagent cost tracking via CostTracker.
• Worktree config passed from coordinator; WorktreeManager persistence added. Auto-enable per task type still pending.
• send_message decision finalized; /subagent is the standard delegation entry point; unified UI display of task_id / status / results / cost; A2A routing by agentType standardized.

Stage 6: Observability & Cleanup ✅

• internal/metrics registered 10+ business metrics (tool call duration, active sessions, token cost, subagent task totals, delegation latency, middleware failures).
• Subagent EventMetrics made persistent/reportable; PostHog extended with tool/subagent/cost events; trace_id propagated session → task → tool_call.
• HotReloader and RecoveryManager enabled in app.go with a multi_agent.enabled guard; persistence store used in the normal flow.
• Tests added for multiagent Manager/CoordinatorAdapter/MessageBus/HotReloader/Recovery, PubSub brokers, middleware integration, E2E flows, and performance benchmarks (cancel storms, high concurrency).
• Cleanup: two registries merged into one; deprecated agent v1 behind a configurable switch; store cleanup leak fixed.

Stage 7: Distributed & Ecosystem 🔮 In Progress

• internal/distributed (leader election, distributed locks), internal/scaling (AutoScaler → Executor.ResizeMaxWorkers), internal/pool, and internal/market (/market slash command) all behind experimental env flags (CRUSH_*_EXPERIMENTAL).
• PubSub extended toward persistent/cross-node operation.
• Planned: strategy-based routing (auto subagent type/model selection), QoS with priority concurrency slots and token budgets, DAG task dependencies, cross-session teaming topologies.

Risks and mitigations

• Behavior drift during migration — replay benchmarks with fixed samples; diff reports on turns/tools/cost.
• Concurrency/cancellation regressions — failure-injection tests; state-machine validation alarms.
• Log inconsistency — enforced trace_id/session_id/task_id propagation.
• Worktree leaks — TTL cleanup, startup cleanup, capacity alerts.
• Middleware dead code (audit finding) — integration call sites plus a CI middleware-coverage check.
• Observability fragmentation — unified metric dictionary; persistent EventMetrics.
• Config/runtime mismatch — enabled-flag guards; gray flags wired to real behavior differences.

Acceptance criteria (highlights)

• Task success rate ≥ 99%; cancel success ≥ 99.5%; delegation P95 latency no worse than baseline by more than 10%.
• Zero critical faults (hangs/state corruption).
• 100% middleware end-to-end coverage (each middleware has at least one integration test).
• ≥ 10 core metrics observable in dashboards; multiagent core test coverage ≥ 80%.

Compatibility & rollout

Old input/output fields preserved with new standard fields (task_id, status) added; behavior differences behind feature flags; rollout via canary → gray → full cutover. Milestones M1–M6 are complete; M7 (distributed/ecosystem) is underway. Evolution principle: staged, observable, rollback-safe.