1.1 Answer “why” first

Before reading Reasonix’s source, read its README. The Chinese README does not open with “how smart our Agent is”; it pins the product position on cost (README.zh-CN.md:42-43):

A DeepSeek-native AI coding agent for the terminal. A config- and plugin-driven extremely thin harness—a single static Go binary, tuned around DeepSeek’s prefix cache, so even long sessions keep token cost down.

This is not marketing copy. It is the starting point of the whole architecture:

1. Pain: in a long session, token cost grows linearly with turns; DeepSeek’s pricing makes “keep chatting” expensive.
2. Already-there mechanism: DeepSeek automatically prefix-caches—as long as the request-prefix bytes stay stable, the hit portion is discounted.
3. Insight: the key to saving money is not “call the model less,” but “keep hitting the prefix.” Cache is thereby promoted from an “optimization” to an “architectural constraint.”

flowchart LR
    P["Pain: long-session token cost is high"] --> I["Insight: DeepSeek auto prefix cache
stable prefix = hit = save money"]
    I --> C["Constraint: system prefix must be byte-stable"]
    C --> D["Corollary: volatile content out to turn tail
stable tool schema · compaction priced in the open · miss diagnosable"]

1.2 Three verifiable engineering claims

1.3 This constraint was written as a “constitution,” not a comment

The repo’s own standing instructions (REASONIX.md:14-16):

- Cache-first: the system-prompt prefix (base prompt + tools + memory) must stay
  byte-stable across turns so DeepSeek's automatic prefix cache stays warm. Never
  mutate it mid-session — ride the turn tail instead (see `control.Compose`).

Even the PR template forces Cache-impact / Cache-guard metadata (REASONIX.md:64-71). In this series only Hermes’s “prefix cache is sacred” is in the same family; Reasonix’s difference is welding it into Go runtime diagnostics + CI scripts, so “do not break the cache” becomes an executable collaboration discipline.

2.1 Motive-evidence table

2.2 Product-manager view: what experience it is selling

🧠 One sentence: others are optimizing “how smart the tool call is”; Reasonix is optimizing “in this same session, can the prefix keep hitting cache”—and treating that as a product contract that cannot be breached.

3.1 Digitized project shape (baseline 627b051)

Layout contract given by docs/SPEC.md:

cmd/reasonix/main.go          # entry; blank-import providers + builtin tools
internal/
  cli/                        # subcommands, assembly, exit codes
  control/                    # transport-agnostic Controller (behind every frontend)
  agent/                      # Session + harness loop + compact + cache shape
  provider/                   # Provider interface + openai/anthropic/responses
  tool/ + tool/builtin/       # Tool interface + init() self-registration
  permission/                 # allow / ask / deny + bash decompose
  sandbox/                    # OS sandbox wrap
  memory/ · instruction/      # background facts vs standing instructions
  plugin/ · mcp* / capability # MCP / capability proxy
  checkpoint/ · evidence/     # change rewind and delivery evidence
  acp/ · bot/ · desktop*      # editor protocol, bots, desktop

Dependency direction (docs/SPEC.md:54-56): cli → {agent, plugin, config} → {tool, provider}; parent packages do not import self-registering child packages.

3.2 Stack

Entry is extremely thin (cmd/reasonix/main.go):

// Blank imports wire compile-time built-ins into their registries.
_ "reasonix/internal/provider/anthropic"
_ "reasonix/internal/provider/openai"
_ "reasonix/internal/provider/responses"
_ "reasonix/internal/tool/builtin"

3.3 Relation to Claude Code / Hermes / Codex

If you remember only one sentence: Reasonix = Hermes’s cache philosophy × Codex’s engineering hardness × Claude Code’s terminal-coding category, welded onto DeepSeek’s automatic prefix cache.

Part II · Mind map: how one constraint yields ten designs

5.1 Two tracks

Controller.Compose (control/input.go:137-212) writes this into a comment (input.go:181-183):

Memory added mid-session rides the turn (never the cached system prefix),
so it takes effect now without invalidating the prompt cache. It folds into
the system prefix on the next session, where it costs nothing per turn.

Assembly order (conceptually):

flowchart TB
    IN["user text"] --> G{"running goal?"}
    G -->|yes| GB["activeGoalBlock + autoResearch"]
    G -->|no| P
    GB --> P{"planMode?"}
    P -->|yes| PM["PlanModeMarker"]
    P -->|no| L
    PM --> L["response/reasoning language wrap"]
    L --> M["drainPending → memory-update"]
    M --> J["background-jobs note"]
    J --> H["hook context"]
    H --> R["memory.recall Block (real user turn)"]
    R --> OUT["hand to Agent.Run"]

This is the same philosophy family as Open Design’s “assemble the system prompt in bands by cache frequency” and Hermes’s “memory writes to disk take effect immediately, enter the prompt only next session.” Reasonix’s distinctive move: diagnose a miss as a structured event, rather than only warning in docs.

5.2 PrefixShape: why a miss?

```13:48:参考项目/DeepSeek-Reasonix/internal/agent/cache_shape.go // PrefixShape hashes the portions of the request prefix that influence // provider-side prompt-cache reuse. Comparing snapshots across turns // lets us explain why a cache miss happened. type PrefixShape struct { SystemHash string ToolsHash string PrefixHash string LogRewriteVersion int ToolSchemaTokens int }

`CaptureShape` **sorts then hashes** tool schema (`normalizeToolSchemas`), avoiding “order jitter” false misses. `CompareShape` gives a `system` / `tools` / `log_rewrite` reason list, plus cache hit/miss tokens from usage.

Before sending to the provider it also strips UI metadata that would cold the cache: `LocalOnly` display records do not enter `ModelMessages` (`LocalOnly` mark in `provider.go`); wall-clock and cancelled half-streams never pollute the prefix.

### 5.3 Tension with dynamic MCP tools

Once dynamic `mcp__*` tools enter the main Registry, they change the tools hash → cold cache. Reasonix’s answer (`docs/TOOL_CONTRACT.md:45-96`):

- Delivery / Planner / most sub-agents: expose a **fixed-name** proxy tool `use_capability` (list / inspect / call / decline);
- **Connecting MCP on demand does not change** that proxy’s provider-visible schema;
- Balanced’s Executor **deliberately keeps** direct `mcp__*` (accepting possible prefix change)—this is a conscious product trade-off, not an omission.

> 🧠 **Load-bearing wall**: Cache-first is not “change the prompt as little as possible.” It is “**which changes are allowed to pay the cache-miss tax**” classified in the open: steer pays the tax, memory-update does not touch the prefix, MCP inventory change is isolated by a proxy.

---

<h2 id="ch6">Chapter 6 · Why dual models must split session</h2>

### 6.1 Motive

Want plan-then-execute cost/quality balance, but switching models would break the prefix.

### 6.2 Constraint and choice

`docs/SPEC.md:238-240` says it plainly:

> switching models inside one shared conversation would break the prefix and tank cache hits, so we don't.

When `planner_model` is configured, **Planner and Executor each have an independent session** (`agent/coordinator.go`): two prefixes each cache-stable; the sessions never mix-write. This is not the same layer as UI Plan Mode (a turn-tail marker).

### 6.3 Cost

- Two prefixes, two tool surfaces, first-round cost higher;
- Capabilities discovered in the planning phase must still be directly callable after handoff (`use_capability`’s fixed proxy exactly carries this);
- Routing more complex: `executor_only` | `plan_and_execute` | `plan_for_approval` | `plan_only` (`planner_route.go`).

---

# Part III · Implementation: from constraint to code

<h2 id="ch7">Chapter 7 · Main loop: Agent.Run → runToolLoop</h2>

### 7.1 Lifecycle entry

`Agent.Run` says it clearly itself (comment starts at `agent.go:1310`, function body `1319-1378`):

1. Resolve this turn’s `maxSteps` (overridable by context);
2. Open workspace lease / steer queue / background evidence submit defer;
3. `interceptAgentStart` (extension may abort);
4. `beginRunTurn` initializes state;
5. **`return a.runToolLoop(ctx, state)`**.

No mysterious “framework base class”—an explicit state machine; policy is split across `beginRunTurn` / `handleFinalResponse` / `handleToolRound`.

### 7.2 `runToolLoop`: what happens in one round

The core loop is at `run_loop.go:274-355`:

```mermaid
sequenceDiagram
    participant U as User / Controller
    participant A as Agent.runToolLoop
    participant P as Provider.Stream
    participant T as executeOne(s)

    U->>A: Run(input)
    loop step = 0..maxSteps
        A->>A: consumeSteer? (write into session, may accept one cache miss)
        A->>A: CaptureShape(system+tools)
        A->>P: streamWithMissingReasoningRecovery
        P-->>A: text + reasoning + tool_calls + usage
        A->>A: CompareShape → cache diagnostics
        alt no tool_calls
            A->>A: handleFinalResponse (incl. maybeCompact)
        else has tool_calls
            A->>T: handleToolRound → parallel read-only / serial write
            T-->>A: tool results written into session
        end
    end
    A-->>U: maxStepsPause or error or nil

A few heavily flavored details:

7.3 Assembly entry: boot.Build → the same Runner

boot.Build (internal/boot) freezes the system prefix in one shot (output style, environment-probe snapshot, memory, skill index), then wraps an optional planner_model into a Coordinator.

7.4 Single-tool execution pipeline

executeOne (execute_one.go:65-101) is a fixed five beats:

1. parseToolCall — Resolve, ambiguous MCP names, duplicate success/fail loop guard, stale-anchor edit intercept; bash may degrade to read-only by args (permission.BashCommandIsReadOnly);
2. interceptToolBefore — extension may rewrite the call;
3. resolveToolPolicy — permission gate;
4. prepareToolExecution — preview, mutation bookkeeping, parent write lock;
5. finishToolExecution — actually execute + receipt.

Read-only tools may run in parallel; writes are serial—same family as Claude Code / OpenAI4S “read-only waves,” but landing on Go’s mutation observer / evidence ledger.

8.1 Motive

The system prefix must stay byte-stable, but goal, plan, language preference, memory updates, retrieval results may change every turn.

8.2 Constraint

Anything unstable, or that need not appear, cannot enter the cache-stable prefix.

8.3 Rejected alternatives

• “Paste all dynamic content into the system prompt”: convenient but colds cache every turn, directly against the constitution;
• “Dynamic content never enters context”: goal/plan/memory updates cannot take effect immediately.

8.4 Choice

control.Compose (control/input.go:137-212) assembles in a fixed order before the real user turn: activeGoalBlock → PlanModeMarker → language wrap → <memory-update> → background-jobs → hook context → memory.recall Block.

8.5 Cost

• One extra assemble-and-strip per turn (StripComposePrefixes);
• If a frontend/extension bypasses Compose and sends a message directly, the cache constitution is broken—so every frontend goes through the same Controller.

10.1 Compile-time builtins (contract table)

docs/TOOL_CONTRACT.md is guarded by tests (TestBuiltinToolContractDocumentation), same-source as the runtime registry. Core surface:

Implementation side is all init() { tool.RegisterBuiltin(...) } (e.g. builtin/readfile.go:27).

10.2 Full boot surface vs Economy

Default full-token boot also hangs session / memory / skill / subagent / LSP / install / slash etc.: ask, task/fleet/parallel_tasks, memory/remember/forget, run_skill, LSP four-piece, explore/research/review/security_review, etc. (docs/TOOL_CONTRACT.md).

Delivery additionally:

• use_capability: stable MCP proxy;
• review_report: structured review of medium/high-risk changes;
• Host-side evidence: verification / diff / files / manual; a complete_step with no evidence is refused outright.

Economy deliberately exposes only a thin surface (about ask/bash/read_file/write_file/edit_file/background three-piece + connect_tool_source); the rest mount on demand—trading “cannot see all tools at once” for tokens and prefix stability.

10.3 Tool-interface flavor

Tools carry capability bits such as ReadOnly, preview (Previewer), images, PlanMode classification—permissions and parallel scheduling read these bits, rather than relying on the model to “behave.” Checkpoint only tracks editing tools that carry Previewer (see Chapter 12).

11.1 Permission Policy + Ask / Auto / Yolo

permission.Policy (permission.go):

• Rule shape aligned with Claude Code: Tool / Tool(glob) / legacy Tool=literal (ParseRule);
• Decide(toolName, readOnly, args); bash takes segmented decompose (DecomposeBashCommand);
• BashCommandIsReadOnly: degrade “schema-writable bash” to read-only on the concrete argv (affects parallel, mutation, evidence);
• BashSubjectRequiresExplicitApproval: indirect execution, dangerous git, etc. force explicit approval.

Product approval modes (docs/TOOL_APPROVAL_MODES.md) are orthogonal to collaboration mode (normal/plan/goal):

There is also internal/guardian: an independent security-review sub-session (with a denial circuit breaker)—cannot replace user confirmation of memory writes. Hooks (internal/hook) provide PreToolUse/PostToolUse/PostToolUseFailure, plus Claude tool-name compatibility mapping.

11.2 Sandbox + confine

builtin/bash.go wraps the command in sandbox.Command:

On enforce with no backend, fail closed (do not run naked). Escape goes through sandbox.EscapeApprover. MCP stdio by default does not inherit the Bash sandbox (product default in internal/plugin/plugin.go is the host process; comments state the reason).

SECURITY.md writes the boundary clearly: workspace fence, permissions, sandbox, secrets, HTTP serve’s localhost/CORS, desktop/bot isolation, updater verification—and what does not count as a vulnerability.

11.3 Checkpoint / Rewind

Aligned with Claude Code’s Esc-Esc / /rewind narrative (docs/CHECKPOINTS.md):

• Mechanism: file snapshots (not git); sidecar <session-id>.ckpt/;
• Tracked range: editing tools that carry Previewer (write_file / edit_file / multi_edit);
• Not tracked: bash side effects; move_file has not yet implemented Previewer;
• API: Controller.Checkpoints / Rewind / PrepareRewind+CommitRewind (including coverage confirmation);
• Explicitly not done: git-backed rollback (docs mark out of scope).

12.1 Three orthogonal axes

docs/GOAL_ENFORCEMENT.zh-CN.md opens:

Goal is the only cross-turn scheduler; Delivery is a pure quality gate; tool permissions and sandbox are unaffected by the Goal switch.

The model declares intent via update_goal(continue|complete|blocked); the host uses a structured ReadinessResult (agent.go:1497+) to decide whether it is truly complete. Declaring complete without evidence → open the next round, rather than believing the model’s mouth.

12.2 complete_step

The builtin tool description is fierce (TOOL_CONTRACT.md): completion must carry evidence; the host advances the todo on its behalf. Same spectrum as grok-build Goal Mode and MiMo “do not trust self-report”—Reasonix lands it with host-observed receipts.

12.3 Collaboration Profile

(docs/COLLABORATION_MODES.zh-CN.md)

13.1 Design iron law

REASONIX.md:11-13:

One transport-agnostic control.Controller sits behind every frontend (chat TUI, HTTP/SSE serve, Wails desktop). Add behavior to the controller, not a frontend, so all three inherit it.

In practice there are also ACP / bot entries. Unified assembly: boot.Build → Controller → agent.Runner (or Coordinator).

13.2 Path of one user message

flowchart LR
    TUI["chat_tui"] --> SUB["Submit / Send"]
    HTTP["serve HTTP/SSE"] --> SUB
    DESK["Wails desktop"] --> SUB
    ACP["ACP"] --> SUB
    SUB --> ADM["admitGuardedTurn
anti-reentry / park"]
    ADM --> COMP["Compose(turn tail)"]
    COMP --> RUN["Coordinator? → Agent.Run"]
    RUN --> EVT["event.Sink
reasoning/text/tool/notice"]
    EVT --> TUI
    EVT --> HTTP
    EVT --> DESK

Key API family (controller.go): Send / Submit / SubmitHTTP / SubmitDisplay / RunTurn / Goal-loop variants; runGuarded does turn admission so a double-open cannot run away.

13.3 Why did Controller become a 6k-line giant file?

Because it swallowed: session restore, checkpoint, memory slash, MCP lifecycle, capability, steer fallback, yolo/plan, attachments, goal usage……all product behavior shared by every frontend. The cost is a giant file; the gain is “fix one place, TUI/desktop/HTTP all correct.” In this series OpenAI4S’s gateway.py and Codex’s turn.rs are the same “giant heart” shape.

14.1 Context Engine v2: instructions ≠ memory

Central law of docs/SESSION_MEMORY_RETRIEVAL.md:

• Standing instructions (REASONIX.md / AGENTS.md / CLAUDE.md + .local + ancestor directories + global): must appear on relevant turns; enter the cache-stable prefix;
• Background memory: facts that can go stale; BM25 auto-recall (defaults defaultAutoRecallLimit=4, defaultAutoRecallChars=2400) enters the turn tail; the index merges into the prefix only next session;
• #note / /remember write instruction files; the remember tool writes background facts—do not mix;
• Safe writes: some scopes create-only; the rest need confirmation—Auto/Yolo/Guardian cannot bypass;
• Instruction parse: deeper directories override broader; same directory .local wins; @path import limited to 5 layers and forbidden to escape.

14.2 Three extension layers: MCP · Plugin Package · Extension Protocol v1

MCP and Extension are different layers: the former attaches tools/resources; the latter attaches host-lifecycle intercepts. Full-trust Extension is an independent attack surface, and also the hardest landing of an “Open Design-style public contract” inside Reasonix (docs/EXTENSION_PROTOCOL.md).

14.3 Subagent profiles

Skill frontmatter runAs: subagent (docs/SUBAGENT_PROFILES.md): builtins explore / research / review / security_review; CLI reasonix subagent …; invocation via /<profile> or task/fleet + write_paths parallel-write isolation. Default concurrency max_subagent_concurrency=6, max_parallel_writers=3. Claude plugin agents/*.md can map to /<plugin>:agent:<name>.

14.4 Desktop and ACP

• Desktop (desktop/): nested Wails module (keep parent module CGO_ENABLED=0); React+TS webview ↔ the same Controller (no HTTP hop);
• ACP (internal/acp, docs/ACP.md): reasonix acp [--profile …]; NDJSON JSON-RPC; loadSession + embeddedContext; capability advertisement no image/audio; MCP http: true, sse: false; vendor extensions include _reasonix.io/session/steer;
• VS Code extension SivanLiu.reasonix-agent brings up local reasonix acp;
• Remote-SSH / workbench: baseline PR #7368 reconnect hardening—the product has grown from a local TUI to a remote workbench.

Part IV · Taste and bounds