Crush Agent Architecture Unification Roadmap v2.0

Overview

This is a translation/summary of the Crush Agent system unification evolution roadmap, v2.0 (dated 2026-04-17, updated 2026-04-18 after a comprehensive codebase audit). It covers internal/agent, internal/agent/subagent, internal/agent/multiagent, internal/a2a, tool/UI integration layers, and infrastructure modules.

Key points

Problem statement

• Multiple agent systems evolved in parallel: the agent tool (session delegation via Delegator.DelegateSync()), subagent (async task engine with 6-state machine, 5 middlewares, SQLite/Memory persistence, WorkerPool), multiagent (role registry with 7 roles, MessageBus with 8 message types), and a2a (Google A2A protocol server).
• Audit findings: duplicated delegation logic, dormant features (Worktree isolation fully implemented but not enabled; send_message tool defined but unregistered; TokenUsageMiddleware.RecordTokens() and LoopDetectionMiddleware.CheckState() never called, so CostUSD was always 0), fragmented observability (only 3 counters in internal/metrics), and weak test coverage for multiagent components.

Target architecture (three layers)

1. Execution Core — SessionAgent as the single LLM execution kernel. 2. Task Orchestration — subagent Executor as the unified delegation engine (sync/async, state machine, middleware, rate limiting, cancellation, timeouts, optional Worktree isolation). 3. Organization / Teaming — multiagent Manager for role governance, message bus, and workspace management, reusing the unified delegation API.

Progress status

• Stages 0–4 (complete): baseline observability; unified Delegator abstraction (DelegationRequest/DelegationResult/delegationstatus); agent tool v2 compatibility bridge (AgentParams = AgentToolV2Input); subagent engine hardening (30+ items: SQLite WAL config, idempotency, backpressure, middleware chain, failure attribution, migration registry); multiagent DelegationExecutor interface with grayscale switch and executeDelegationWithSession entry point.
• Stage 5 (complete): multiagent DelegationExecutor now routes through the subagent Executor; concurrency control migrated from execMu.TryLock() to the WorkerPool; middleware (RecordTokens, CheckState) and cost tracking actually wired in; Worktree isolation productized; send_message registration decision made; /subagent unified as the standard delegation entry point; A2A routing by agentType standardized.
• Stage 6 (complete): >= 10 core Prometheus metrics (tool_call_duration_seconds, active_sessions, token_cost_total_usd, etc.); subagent EventMetrics persisted (.crush/subagent_event_metrics.json); PostHog tool/cost events; trace_id propagation session → task → tool_call; HotReloader and RecoveryManager enabled in app.go; Registry consolidation; Store cleanup leak fix.
• Stage 7 (in progress): experimental distributed (leader election, distributed locks), scaling (AutoScaler calling Executor.ResizeMaxWorkers), pool, and market (/market slash command) behind flags like CRUSH_SCALING_EXPERIMENTAL=true; PubSub upgraded toward cross-process persistence.

Risk management

Key risks and mitigations include: behavior drift (replay benchmarks), concurrency/cancellation regressions (fault injection, state machine validation), inconsistent logging (mandatory trace_id/session_id/task_id), worktree leaks (TTL cleanup), middleware dormancy (CI middleware-coverage checks), observability fragmentation (metrics dictionary), and config-runtime mismatch (feature-flag guards in app.go).

Acceptance criteria

• Task success rate >= 99%; cancellation success >= 99.5%; delegation P95 latency no worse than 10% over baseline; middleware chain E2E coverage 100%; >= 10 observable core metrics; multiagent test coverage >= 80%.

Backward compatibility & rollout

Old tool input fields are preserved and mapped internally; behavior changes ship behind feature flags with canary → grayscale → full rollout. Proposed ADRs document key decisions (three-layer architecture, single execution kernel, subagent as unified engine, agent-tool deprecation, middleware wiring spec, send_message disposition).

Conclusion

The audit found the architecture framework (stages 0–4) largely ready, but the "last mile" integration — middleware wiring, observability, config-runtime consistency — had significant gaps, which stages 5–7 address. The guiding principles remain: staged, observable, rollback-able.