How Reasonix Multi-Model Collaboration Works Between Executor and Planner with Separate Cache-Stable Sessions

Reasonix orchestrates a dedicated executor model and planner model inside isolated, append-only prefix-cache sessions, enabling deterministic replay, >90% cache-hit rates, and shared authorized tool access without cache invalidation.

The DeepSeek-Reasonix repository implements a dual-model architecture where an executor and a planner collaborate across separate cache-stable sessions to minimize token costs while maximizing reasoning depth. This design allows each model to maintain its own deterministic conversation prefix that is never rewritten, ensuring that turns can be replayed from cache even during complex multi-step workflows. Understanding how Reasonix multi-model collaboration works between the executor and planner requires examining the turn orchestration, routing logic, and shared MCP runtime state outlined in REASONIX.md and the core Go source files.

Turn Orchestration and Planner Routing

Every user turn begins inside the turn orchestrator, which prepares metadata and delegates routing authority to the planner.

Metadata Preparation in the Turn Orchestrator

When a user sends a turn, turnOrchestrator.runOrchestratedTurn in internal/control/turn_orchestrator.go (lines 71-75) first enriches the context via c.withPlannerTurnMetadata. This injects the raw user text and synthetic flags into the planner's view, ensuring the planner has complete visibility into the incoming request before any routing decision is made.

Planner Route Decisions

The deterministic routing logic lives in internal/control/planner_gate.go (lines 87-95) inside the DecidePlannerRoute function. The policy inspects the metadata alongside the normalized user text and returns a PlannerDecision struct, defined in internal/agent/planner_route.go (lines 30-38). That struct carries:

• The chosen PlannerRoute
• A PlannerDepth value
• A diagnostic reason string
• The maximum number of research rounds

The four possible routes are:

• PlannerRouteExecutorOnly — Forward the turn directly to the executor
• PlannerRoutePlanOnly — Run the planner to generate a plan without immediate execution
• PlannerRoutePlanAndExecute — Run the planner first, then hand the resulting plan to the executor for tool calls or final answer generation
• PlannerRoutePlanForApproval — Generate a plan that awaits explicit approval before execution proceeds

Separate Cache-Stable Sessions

Reasonix instantiates the executor and planner as distinct agent.Agent objects—c.Executor and c.Planner—each bound to its own session ID. The sessions are engineered so that only new messages are appended to a deterministic prefix, leaving the prefix itself untouched.

Deterministic Prefix-Cache Architecture

Because each session only appends messages, the prefix-cache remains stable across millions of turns. The cache is never rewritten, so any identical prefix can be replayed directly from cache storage. This append-only invariant is the foundation of Reasonix's cache-stable session design.

Destructive vs Non-Destructive Agents

The two sessions are split by trust and behavior:

• c.Executor — This is the destructive working model. It may invoke tools that modify external state, and its ledger grows with tool results and side effects.
• c.Planner — This is the non-destructive thinking model. It is trusted for cache reuse because it does not mutate state, making its prefix ideal for repeated reads and plan refinement cycles.

Shared Authorized MCP Runtime State

Although the sessions are isolated, they share the same authorized MCP (Machine Capability Provider) runtime. According to the DeepSeek-Reasonix release notes in release-notes/releases.json (lines 6831-6832), "Planner, review, task, fleet, and dual-model Executor paths share authorized MCP runtime state while keeping per-agent ledgers, exact allowlists, serialized writers, structured image results, and provider-visible schemas stable."

This shared layer means the planner can call MCP tools without re-authorizing, and the executor can consume any tool results the planner produced. Per-agent ledgers and allowlists remain independent, but the underlying runtime state is unified.

Execution Flow and Dispatch Logic

Once the planner returns its decision, the orchestrator dispatches the turn along one of two paths.

If the decision is PlannerRouteExecutorOnly, the turn is sent straight to c.Executor. If the decision is PlannerRoutePlanOnly or PlannerRoutePlanAndExecute, the turn first goes through c.Planner. After the planner emits its plan, the orchestrator forwards that plan to the executor, which performs the actual tool calls or generates the final response. This separation of concerns ensures that planning reasoning stays cheap while execution retains full capability.

Cache Efficiency and Cost Optimization

The cache-friendly behavior stems from the append-only guarantee. When a turn's context is added, the existing prefix is never altered. The planner's session is effectively read-only from the cache perspective, so any planning round that only reads data reuses the cached prefix entirely. When the executor later runs tools, its session may write new messages, but it still reuses the unchanged prefix portion. According to the Reasonix implementation, this separation yields >90% cache-hit rates even for long sessions, dramatically lowering token costs.

Practical Configuration and Code Examples

You can configure and run the dual-model session through the Reasonix CLI and TOML settings, or integrate the controller logic directly in Go.

Configure Dual-Model Agents

# reasonix.toml (excerpt)

[agent]
executor_model = "deepseek-coder:latest"   # the working model

planner_model  = "deepseek-planner:latest" # the thinking model

# Run Reasonix – the CLI will spin up two sessions automatically

reasonix run "write a function that parses CSV and returns JSON"

Manually Invoke Planner Routing

ctx := c.withPlannerTurnMetadata(context.Background(), userText, false, c.messageCount())
decision := control.DecidePlannerRoute(ctx, userText)

switch decision.Route {
case agent.PlannerRouteExecutorOnly:
    // forward directly to executor
case agent.PlannerRoutePlanAndExecute:
    // run planner first, then executor
}

Share the MCP Proxy Between Agents

func (c *Controller) initMCPProxy() {
    // Both executor and planner get the same authorized MCP client
    proxy := mcp.NewAuthorizedProxy(c.mcpServer, c.authToken)
    c.Executor.SetMCP(proxy)
    c.Planner.SetMCP(proxy) // planner is trusted-non-destructive
}

Summary

• Dual-model architecture — Reasonix runs an executor and a planner as separate agent.Agent instances with distinct session IDs.
• Cache-stable sessions — Each session appends messages to a deterministic prefix without rewriting history, enabling deterministic replay and high cache-hit rates.
• Deterministic routing — DecidePlannerRoute in internal/control/planner_gate.go selects among four routes, including direct executor dispatch and plan-then-execute pipelines.
• Shared MCP state — Both agents access the same authorized MCP runtime, so tool results and authorizations flow between planner and executor without duplication.
• Cost efficiency — The non-destructive planner session and append-only prefix design yield >90% cache-hit rates, keeping token costs low during extended sessions.

Frequently Asked Questions

What is a cache-stable session in Reasonix?

A cache-stable session is an append-only conversation context where the prefix is never rewritten. Because the prefix remains deterministic, the system can replay it from cache on subsequent turns, which keeps token costs predictable and cache-hit rates high.

How does the planner decide whether to route a turn to the executor?

The planner's DecidePlannerRoute function in internal/control/planner_gate.go examines turn metadata and normalized user text to produce a PlannerDecision. That decision selects one of four routes, such as PlannerRouteExecutorOnly for direct execution or PlannerRoutePlanAndExecute for collaborative planning.

Why do the executor and planner use separate sessions instead of a single shared session?

Separate sessions prevent the destructive tool calls of the executor from invalidating the planner's prefix cache. The planner's non-destructive, read-oriented session stays stable and reusable, while the executor's session is free to mutate state and grow its ledger without affecting the planner's cache efficiency.

Can both models access the same MCP tools?

Yes. Both agents share the same authorized MCP runtime state, as documented in the Reasonix release notes. They reference identical tool schemas and authorization tokens, though each agent maintains its own ledger and allowlist boundaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}