mocode-ai 1.6.6 → 1.6.8

package/README.md

@@ -39,7 +39,7 @@ See mocode complete real tasks autonomously:
 MoCode keeps code-level control light and leaves task strategy to the agent:
 
 - **Advisory working discipline** — The system prompt asks the agent to make focused changes, avoid redundant retrieval, and decide for itself whether validation is useful. Validation is optional and is never a completion gate.
-- **Transparent tool failures** — Each tool call runs once and returns its raw structured failure to the agent, which decides whether and how to recover.
+- **Bounded tool retries, explicit failures** — The runtime automatically retries only transient errors from tools explicitly marked `idempotent`, at most twice. `TIMEOUT`, permission denial, cancellation, and non-idempotent calls are not automatically retried. The resulting structured outcome is returned to the agent for any further recovery decision; see [Automatic retry](#automatic-retry-the-retryable-contract).
 - **`ask_human` for user-owned decisions** — The agent asks only when repository evidence cannot resolve a high-impact choice; implementation details remain autonomous.
 - **Five-zone context controls + token self-calibration** — Five independent dials (`autoCompact` / `contextOptimize` / `contextRelprune` / `contextLifecycle` / `contextBudget`) manage context pressure. Token estimation self-calibrates against provider usage.
 
@@ -47,29 +47,29 @@ MoCode keeps code-level control light and leaves task strategy to the agent:
 
 MoCode is organized as a layered runtime: the terminal experience drives an autonomous core, the core reaches capabilities through a guarded execution plane, and a persistent intelligence layer keeps long-running work coherent.
 
-<p align="center"><img src="./assets/architecture/system-overview.svg" alt="MoCode layered system architecture" width="100%"></p>
+Implementation entry points: [Agent core](src/agent/core.ts), [tool dispatch](src/agent/stages/tool-dispatcher.ts), and [tool execution](src/tools/tool-runtime.ts).
 
 ### Autonomous execution loop
 
 Each model response is one step in a closed loop. Tool calls are classified by declared capabilities, safe reads can run in parallel, and writes acquire canonical resource locks. Tool evidence returns to history unchanged apart from a hard per-result safety cap. When the agent has no more tools to call, its response completes immediately; the framework does not run hidden validation or force another model turn.
 
-<p align="center"><img src="./assets/architecture/agent-loop.svg" alt="MoCode autonomous agent execution loop" width="100%"></p>
-
 ### Context compression only under real pressure
 
 Normal sessions retain full tool evidence and structured freshness/provenance metadata. At 80% of the model window, one scheduler event runs enabled exact-supersession, stale-artifact, and old-log/search cleanup, then always compacts history. Lifecycle tracking never ages content by tool-call count.
 
-<p align="center"><img src="./assets/architecture/context-engine.svg" alt="MoCode context engineering and durable memory architecture" width="100%"></p>
+The implementation is defined by [budget accounting](src/context/budget.ts) and [pressure scheduling](src/session/scheduler.ts).
+
+### Multi-agent work in a shared workspace
 
-### Multi-agent work without unsafe shared writes
+Sub-agents keep independent history branches, can reuse the parent's conversation prefix, and cannot expand beyond the tool set delegated by the parent step. Consecutive sub-agent calls run in bounded parallel batches (`SUB_AGENT_CONCURRENCY`, default `5`; set `1` for sequential dispatch).
 
-Read-only sub-agents fan out concurrently. Writer agents work inside private filesystem overlays and return structured ChangeSets; the coordinator checks expected hashes, acquires canonical locks, and performs conflict-safe merges. Validation remains an explicit agent choice in the shared workspace.
+**History isolation is not filesystem isolation.** Sub-agents write directly to the shared workspace and inherit the parent's current rollback turn. There is no private filesystem overlay, per-worker worktree, or post-task ChangeSet merge. Nested tools acquire their own resource locks; supported file edits enforce their own expected-hash checks. These guards do not make an entire multi-step sub-task an isolated transaction. The parent receives the final summary, status, usage, and tracked changed files rather than the full worker transcript. Validation remains an explicit agent choice.
 
-<p align="center"><img src="./assets/architecture/multi-agent.svg" alt="MoCode multi-agent overlay and ChangeSet coordination" width="100%"></p>
+See [sub-agent execution](src/agent/spawn.ts), [the sub-agent tool](src/tools/builtins/task.ts), and [capability-based dispatch](src/agent/stages/tool-dispatcher.ts).
 
 ### Controlled execution: permission gates and capability scheduling
 
-Every mutating tool calls into a permission layer before it runs. Tools are classified `safe` / `confirm` / `dangerous`, scopes can be `once` / `session` / `project` / global-tool, fingerprints are stable hashes (command, path, or args), and the persistent record lives in `~/.mocode/permissions.json` (v3 schema, with v2 resource grants still loaded). Piped or CI environments default to deny until you opt in.
+Every mutating tool calls into a permission layer before it runs. Tools are classified `safe` / `confirm` / `dangerous`, scopes can be `once` / `session` / `project` / global-tool, fingerprints are stable hashes (command, path, or args), and the persistent record lives in `~/.mocode/permissions.json` (v3 schema, with v2 resource grants still loaded). In piped or CI environments, unapproved `confirm` / `dangerous` actions are denied by default; safe operations do not require an interactive prompt.
 
 <p align="center"><img src="./assets/architecture/permission-model.svg" alt="MoCode permission model: tool classes, four-tier grants, fingerprinting, durable storage" width="100%"></p>
 
@@ -77,18 +77,16 @@ Every mutating tool calls into a permission layer before it runs. Tools are clas
 
 MoCode does not run a hidden validation cascade when a task ends. The agent can explicitly call `run_command` for a focused test, typecheck, or build when it judges that evidence useful; otherwise it may finish without an extra framework-controlled round trip.
 
-### Rollback timeline: per-mutation snapshots, restore by turn
+### Rollback timeline: tracked file changes, restore by turn
 
-A clean undo point is saved before every mutating tool. `/rollback <turnId>` restores file buffers in reverse-chronological order under canonical resource locks — it does not re-run the model or launch automatic tests. Read tools, network effects, and binary changes are explicitly out of scope, kept honest in the contract.
+Rollback records supported text-file mutations, including tracked changes made by sub-agents in the parent's turn. `/rollback` restores recorded file contents under canonical resource locks; it does not re-run the model or launch automatic tests. It is not a universal undo mechanism: network effects, desktop actions, binary changes, and other untracked effects are outside its scope. Cancelling a turn does not automatically undo completed file writes.
 
-<p align="center"><img src="./assets/architecture/rollback-flow.svg" alt="MoCode rollback timeline and per-turn snapshot flow" width="100%"></p>
+See the [rollback store](src/rollback/store.ts) for capture and restore boundaries.
 
 ### Context controls: one pressure gate, independently optional stages
 
 The controls remain independently configurable, but automatic rewriting has exactly one trigger: corrected or raw request occupancy reaching 80%. That event runs every enabled pressure cleanup and then always compacts history. `contextLifecycle` only tracks provenance metadata, while EWMA calibration keeps the estimate aligned with provider usage.
 
-<p align="center"><img src="./assets/architecture/context-controls.svg" alt="MoCode context controls: five independent toggles, observation lifecycle, token self-calibration" width="100%"></p>
-
 ### Desktop pet: a passive mirror over WebSocket
 
 The optional Electron sub-package (`packages/pet-app`) shows a stateful floating character that mirrors agent activity via a one-way WebSocket stream. Quit with `/pet quit`. The renderer owns no business logic; the agent loop is unchanged regardless of whether the pet is running.
@@ -100,16 +98,16 @@ The optional Electron sub-package (`packages/pet-app`) shows a stateful floating
 MoCode isn't a chat box with a coat of paint — it's an agent that actually gets things done:
 
 - **Autonomous multi-step execution** — In a single conversation, the agent chains multiple steps on its own: read code, edit code, run tests, fix based on errors, and so on. It decides the next step without you nagging it. When it hits a decision point, it calls `ask_human` to pop up a panel and ask you (blocking until you respond).
-- **Parallel read-only tools** — Consecutive read-only operations in a turn (reading files, grep, glob, codegraph, web search/fetch) run concurrently, so total time is roughly the slowest single call instead of the sum of all of them. Operations with side effects (writing/editing files) stay sequential to preserve snapshot ordering and data safety.
-- **Sub-agents divide and conquer** — Complex tasks can spawn independent sub-agents with isolated histories and scoped toolsets. Read-only workers can fan out concurrently; writer workers run in private filesystem overlays and return ChangeSets that are merged under expected-hash checks and canonical resource locks. Only structured findings return to the main thread.
-- **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode permits execution. Tool capabilities are not a static “full” mode: a lightweight LLM router selects the minimum sufficient groups for each real user turn, and the main model may add groups on a later step when needed.
+- **Capability-aware concurrency** — Consecutive tools declared safe to parallelize (such as file reads, grep, glob, and web reads) can run concurrently. Resource-locked file mutations can also be dispatched together: canonical locks coordinate conflicting resources rather than serializing every write globally. Process tools and tools without parallel capabilities retain their declared serial behavior.
+- **Sub-agents divide and conquer** — Workers have independent history branches and inherit the parent step's tool ceiling. They run in bounded parallel batches, write directly to the shared workspace, and share the parent's rollback turn. A final summary and execution metadata return to the parent; there is no per-worker filesystem isolation or merge stage.
+- **Plan / Auto dual mode** — In `plan` mode the agent explores and produces a plan without editing project files, running shell commands, or spawning sub-agents; internal session/plan records may still be persisted. `auto` mode permits execution. Tool capabilities are not a static “full” mode: a lightweight LLM router selects the minimum sufficient groups for each real user turn, and the main model may add groups on a later step when needed.
 - **Pressure-driven context compression** — Normal history keeps full tool evidence. At 80% occupancy, one scheduler event runs all enabled cleanup and always follows with a history summary. `/context` shows live usage and `/compact` remains an explicit manual override.
-- **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
+- **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. Optional background reflection mines conversations for useful memories when `AUTO_REFLECT=true` (off by default). Memories can be created, searched, updated, and forgotten, with recall-based decay.
 - **Project context (`AGENTS.md`)** — A single project-level memory file at `AGENTS.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Auto-injected into the system prompt every turn, but lean by design: the `directory tree` and `extension points` sections stay out of the prompt as one-line pointers (read_file `AGENTS.md` on demand), keeping the always-on payload small. During work, the agent may append stable, non-obvious facts it discovers to `.mocode/agents-draft.md`; `/init` merges and clears that draft.
 - **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It records the execution plan with the dedicated `plan_update` tool — a three-state step machine (`pending`/`in_progress`/`completed`, at most one `in_progress`) that auto-settles to `## Done:` when finished. The active plan is re-injected into the system prompt after compaction and re-synced into context whenever notes.md changes, and a gentle reminder nudges the agent if it goes several tool-steps without updating the plan. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`.
-- **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
+- **Interruptible and reversible** — Ctrl+C propagates cancellation to model requests and supported running tools. History returns to the latest committed tool-batch checkpoint rather than unconditionally discarding the entire turn. Completed file writes remain until explicitly reverted; `/rollback` restores tracked file changes from turn snapshots with a per-file keep/undo choice, without requiring git.
 - **Input safety net** — Long prompts no longer fear a stray Enter: `Ctrl+G` opens an in-TUI composer popup (notepad-style editing — Enter inserts a newline, with soft wrap, selection, copy/cut/paste and undo; Ctrl+S fills the text back into the input box without sending). `Ctrl+R`/`Ctrl+P` fuzzy-search your input history (Enter only fills it back), and the post-send recall window widens to 2 seconds with any-key recall for long inputs.
-- **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
+- **File-path boundaries** — Built-in file reads/writes reject paths outside `SANDBOX_ROOT` (the working directory by default), including traversal and symlink escapes. This is a file-tool path guard, not an OS-level sandbox for shell commands, MCP servers, or desktop input. Memory and skills may intentionally use configured locations outside the project. Review permissions before allowing high-risk tools; see [sandbox policy](src/sandbox/policy.ts).
 - **Computer Use (high-risk, routed only for explicit GUI intent)** — When the request genuinely requires real mouse/keyboard interaction, the router can expose the `computer-control` group and feed each resulting screenshot back to the model. `/cu off` (or `MOCODE_COMPUTER_USE_ENABLED=false`) is a hard veto; `/cu on` merely allows routing and does not keep the tool permanently visible. The blast radius exceeds file tools because OS input bypasses the file sandbox. **Use a VM / sandbox / dedicated test machine**, not a daily driver. Every action still passes the permission gate, and plan mode always blocks it. Windows first; macOS/Linux pending.
 
 ## Features
@@ -142,7 +140,7 @@ npm install -g mocode-ai
 
 This gives you the `mocode` command. Prefer not to install globally? Run it directly with `npx mocode-ai`.
 
-> MoCode does not contact the registry on startup. Use `/upgrade check`, `/upgrade status`, or `/upgrade now` explicitly when you want to check or install an update. Real installation is disabled in source/tsx development mode.
+> MoCode does not contact the registry on startup. Use `/upgrade check`, `/upgrade status`, or `/upgrade now` explicitly when you want to check or install an update. Real installation is disabled in source/tsx development mode; see the [upgrade implementation](src/commands/upgrade.ts).
 
 ### Run from source (development / contributing)
 
@@ -153,7 +151,7 @@ npm install
 npm start
 ```
 
-Source runs directly via tsx, no build step. After changing code, restart `npm start` for changes to take effect (tsx loads modules at startup, no hot reload). Runtime dependencies: `openai`, `dotenv`, `fast-glob`; dev dependencies: `tsx`, `typescript`, `@types/node`.
+Source runs directly via tsx, no build step. After changing code, restart `npm start` for changes to take effect (tsx loads modules at startup, no hot reload). Install from the repository root so npm resolves the workspaces. Dependency lists and development commands are maintained in [package.json](package.json), rather than duplicated here.
 
 ### Repository stacks and contributing
 
@@ -167,6 +165,10 @@ The production path is the TypeScript CLI. `packages/work-app` is incubating, `p
 
 Do not import another package's `src/` or internal `dist/` layout. Applications consume package exports and the public `mocode-agent-host` bin contract.
 
+### Keeping documentation aligned
+
+When changing execution, permissions, concurrency, rollback, or upgrade behavior, update both `README.md` and `README.zh-CN.md` against the implementation links in these sections. Diagrams must describe the same current behavior before being embedded. Use the package manifests and built-in registry for dependency/tool inventories, and the stack-status page for release boundaries; do not treat a design proposal or an old diagram as a shipped guarantee.
+
 ## Configuration
 
 On first use, run the setup wizard to fill in three fields interactively (API base URL / key / model name), written to `~/.mocode/config` (global, works from any directory or terminal):
@@ -221,6 +223,8 @@ Common backend `base_url` values:
 | `MOCODE_LIFECYCLE`              | Provenance metadata tracking; never ages or rewrites content                                  | `true`                      |
 | `MAX_STEPS`                     | Max agent loop steps per turn (infinite-loop safety only)                                     | `1000`                      |
 | `SUB_AGENT_MAX_STEPS`           | Sub-agent loop safety ceiling; defaults to the main-agent value                               | `1000`                      |
+| `SUB_AGENT_CONCURRENCY`         | Concurrent sub-agent calls per dispatch batch; `1` dispatches them sequentially               | `5`                         |
+| `SUB_AGENT_MAX_DEPTH`           | Maximum recursive delegation depth                                                            | `3`                         |
 | `SANDBOX_ROOT`                  | Sandbox root directory (file operation boundary; falls back to cwd if unset)                  | none                        |
 | `MOCODE_SUBAGENT_ENABLED`       | Set `false` to veto the `orchestration` route group; unset/`true` allows on-demand routing    | unset                       |
 | `MOCODE_FRONTEND_TOOLS_ENABLED` | Set `false` to veto `browser-debug` and `desktop-observe` (does not affect `background-exec`); unset/`true` allows routing | unset                       |
@@ -239,7 +243,7 @@ mocode --resume <id>            # resume a specific session
 mocode config                   # edit configuration
 ```
 
-Running from source uses `npm start` (equivalent to `mocode`, but skips the self-update check).
+Running from source uses `npm start`. Neither source nor installed runs automatically check for updates at startup; `/upgrade` is an explicit user action, and real installation is disabled in source/tsx mode.
 
 Once in the REPL, just start chatting. It launches straight into the full-screen TUI, showing a banner (model / backend / working directory / tool list). Responses stream in, with the reasoning section visible in real time before collapsing.
 
@@ -247,7 +251,9 @@ The agent operates in **the working directory it was launched from** — to have
 
 ## Tools
 
-Every real user turn first goes through a constrained LLM router. Nine common tools are always available (`read_file`, `glob`, `grep`, `web_search`, `web_fetch`, `plan_update`, `note_append`, `ask_human`, `use_skill`); additional capabilities are selected as composable groups for writing, shell debugging, browser debugging, desktop observation/control, memory, orchestration, and MCP. If the initial set is insufficient, the main model must call `add_tool_groups` alone; the expanded schemas appear on the next model step. A routing failure reuses the previous turn’s groups (or common-only), never the full toolset.
+Every real user turn first goes through a constrained LLM router. Common tools include `read_file`, `glob`, `grep`, `web_search`, `web_fetch`, `plan_update`, `note_append`, `ask_human`, and `use_skill`; additional capabilities are selected as composable groups for writing, shell debugging, browser debugging, desktop observation/control, memory, orchestration, and MCP. If the initial set is insufficient, the main model requests more groups with `add_tool_groups`; the expanded schemas appear on the next model step. A routing failure reuses the previous turn's groups (or common-only), never the full toolset.
+
+The tables below are selected capabilities, not an exhaustive tool inventory. Current registrations and capability declarations are maintained in the [built-in registry](src/tools/builtins/index.ts); exposure is controlled by [ToolPolicy](src/tools/policy.ts). Codegraph queries use an installed skill/CLI when available, not a standalone built-in `codegraph` tool.
 
 | Tool          | Purpose                                                                                                                                                               |
 | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -256,24 +262,26 @@ Every real user turn first goes through a constrained LLM router. Nine common to
 | `edit_file`   | Precise string replacement (`old_string` must match uniquely)                                                                                                         |
 | `run_command` | Run a foreground shell command, merging stdout+stderr, 120s default timeout; `shell=cmd\|powershell\|bash` picks the interpreter                                       |
 | `glob`        | Find files by glob pattern (excludes node_modules/.git)                                                                                                               |
-| `grep`        | Regex content search, pure JS implementation, no `rg` dependency; `context=N` returns neighbouring lines inline so a hit rarely needs a follow-up read                  |
-| `codegraph`   | With a `.codegraph/` index built, query symbol source and call chains (more accurate and cheaper than read_file/grep)                                                 |
+| `grep`        | Regex content search powered by ripgrep (bundled via `@vscode/ripgrep`; respects `.gitignore`, skips binaries), falling back to a pure-JS scan only when no `rg` binary is available; `context=N` returns neighbouring lines inline so a hit rarely needs a follow-up read                  |
 | `web_search`  | Web search (AnySearch), returns title/URL/snippet/body                                                                                                                |
 | `web_fetch`   | Fetch a URL, cleaning HTML into plain text; browser-like headers, auto-retry on transient failures, optional plaintext-proxy fallback                                 |
 | `use_skill`   | Load the full SKILL.md instructions for a given skill                                                                                                                 |
 | `ask_human`   | Pop up a Q&A panel at decision points; user picks a preset or types freely (blocks until answered)                                                                    |
 | `plan_update` | Record/update the session execution plan (the `## Plan:` block in notes.md); three-state steps, at most one in_progress, auto-settles to `## Done:` when all complete |
-| `sub-agent`   | Spawn a capable isolated worker; read tasks can run concurrently and writes use overlay + ChangeSet safe merge                                                        |
+| `sub-agent`   | Spawn a worker with an independent history and the parent step's tool ceiling; bounded concurrency, shared workspace and rollback turn                                                        |
 
+| Memory tool | Purpose |
+| ----------- | ------- |
 | `memory_save` | Save a piece of cross-session long-term memory (title indexed, body fetched on demand) |
 | `memory_search` | Search memory bodies by keyword; hits boost the recall count (affects forgetting decay) |
 | `memory_list` | List the memory index (id/title/summary, no body) |
 | `memory_update` | Edit a memory in place (id unchanged; correct stale facts / update summary / toggle pin) |
 | `memory_forget` | Forget a memory: archived by default (recoverable), `mode=delete` for a hard delete (pinned memories can't be deleted) |
+| `memory_graph` | Traverse neighbors, find paths, add triples, or inspect graph statistics; keyword search is provided by `memory_search` |
 
 The six `memory_*` tools are split into `memory-read` and `memory-write` route groups. They appear only when the router selects them; `MEMORY_ENABLED=false` vetoes both groups, while `MEMORY_ENABLED=true` also enables the compact Memory Index in the prompt. `/memory_switch` manages that compatibility gate.
 
-Frontend capabilities are also split by purpose: `browser` forms `browser-debug`, whole-desktop `screenshot` is `desktop-observe`, and `dev_server` has its own ungated `background-exec` group — any process that must outlive a single tool call (dev server, inference service, watcher, log tail) belongs there rather than in `run_command`. Selecting `browser-debug` implies `background-exec`, so a weak model that only asks for the browser still gets the ability to start the server it needs to look at. Image reading lives in `read_file` (magic-byte sniffing) and remains a common read tool. The router may combine these groups with `computer-control` when a task genuinely needs both structured web diagnostics and real desktop interaction. `/fe off` is a hard veto, not a manual profile selector — it does not affect `dev_server`.
+Frontend capabilities are also split by purpose: `browser` forms `browser-debug`, whole-desktop `screenshot` is `desktop-observe`, and `dev_server` has its own `background-exec` group (not controlled by `/fe`; execution still goes through permissions) — any process that must outlive a single tool call (dev server, inference service, watcher, log tail) belongs there rather than in `run_command`. Selecting `browser-debug` implies `background-exec`, so a weak model that only asks for the browser still gets the ability to start the server it needs to look at. Image reading lives in `read_file` (magic-byte sniffing) and remains a common read tool. The router may combine these groups with `computer-control` when a task genuinely needs both structured web diagnostics and real desktop interaction. `/fe off` is a hard veto, not a manual profile selector — it does not affect `dev_server`.
 
 ### Shell selection
 
@@ -323,6 +331,7 @@ dev_server stop   id=srv-xxxx
 | `/model`         | Two-level picker (provider → model; scoped search), plus baseURL / apiKey / context-window config; applied immediately + persisted |
 | `/effort`        | Set reasoning effort off/low/medium/high/auto (e.g. `/effort high`); not sent for unrecognized models |
 | `/stats`         | Session usage: cache hit rate / tiered tokens / compaction count |
+| `/upgrade`       | Explicit update check/status/install (`check` / `status` / `now`); no automatic startup update |
 | `/init`          | Scan the project and generate `AGENTS.md` project memory (dispatched to the agent)             |
 | `/theme`         | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)                                   |
 | `/plan`          | Switch to plan mode (read-only exploration + plan output, approve to switch to auto)           |
@@ -374,9 +383,9 @@ MoCode has a **two-tier memory** model distinct from skills:
 ## Type checking
 
 ```bash
-npm run typecheck   # tsc --noEmit
+npm run typecheck   # protocol/runtime + root + tests + evals
 ```
 
 ## Future extensions
 
-MCP tool integration, finer-grained capability locks, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 25 tools, working-notepad planning, cross-session memory, capability-aware tool scheduling, serial workspace-sharing sub-agents, and an optional desktop pet.
+MCP tool integration is already supported; see the [MCP configuration guide](src/mcp/README.md). Finer-grained capability coordination and optional per-worker worktree isolation are extension directions, not guarantees of the current shared-workspace sub-agent implementation. Current tool registrations are maintained in the [built-in registry](src/tools/builtins/index.ts), and production, optional, incubating, and experimental stacks are distinguished in [stack status](docs/architecture/stack-status.md).

package/README.zh-CN.md

@@ -38,25 +38,25 @@ mocode 自己探索代码、读写改文件、执行命令、联网查资料,以
 
 MoCode 是一个分层的自治运行时：终端交互层驱动 Agent 内核，内核通过受控能力平面执行真实操作，持久化认知层则让长任务和跨会话工作保持连贯。
 
-<p align="center"><img src="./assets/architecture/system-overview-zh-CN.svg" alt="MoCode 分层系统架构" width="100%"></p>
+实现入口：[Agent 内核](src/agent/core.ts)、[工具派发](src/agent/stages/tool-dispatcher.ts)、[工具执行](src/tools/tool-runtime.ts)。
 
 ### 自治执行循环
 
 每次模型响应都是闭环中的一步。工具调用按能力声明分类，安全读取可以并行，写操作获取规范化资源锁。工具证据除单条 hard cap 外原样进入 history，用户与模型看到同一事实。agent 没有更多工具调用时立即完成；框架不会暗中运行验证，也不会强迫追加一轮模型调用。
 
-<p align="center"><img src="./assets/architecture/agent-loop-zh-CN.svg" alt="MoCode 自治 Agent 执行循环" width="100%"></p>
-
 ### 只在真实 Context Pressure 下压缩
 
 正常会话保留完整工具证据，只维护 freshness / provenance 元数据。总上下文达到 80% 时，统一调度事件会执行已启用的 superseded、stale artifact、旧日志/搜索清理，然后始终继续 history compact；Lifecycle 不再按工具调用次数老化正文。
 
-<p align="center"><img src="./assets/architecture/context-engine-zh-CN.svg" alt="MoCode 上下文工程与持久化记忆架构" width="100%"></p>
+具体行为以[预算计算](src/context/budget.ts)和[压力调度](src/session/scheduler.ts)实现为准。
+
+### 多 Agent 协作：共享工作区，有界并发
 
-### 多 Agent 并行，但不冒险共享写入
+子 agent 维护独立历史分支，可以复用父级对话前缀，工具能力不能超出父 step 委派的范围。连续的子 agent 调用按并发上限分批执行（`SUB_AGENT_CONCURRENCY` 默认 `5`，设为 `1` 时逐个派发）。
 
-只读子 Agent 可以并行扇出；写任务在私有文件系统 overlay 中完成并返回结构化 ChangeSet。协调器校验 expected hash、获取规范化资源锁并安全合并冲突；是否验证以及验证范围由 agent 在主工作区自行决定。
+**历史隔离不等于文件系统隔离。** 子 agent 直接写入共享工作区，并继承父级当前轮次的回滚记录；没有私有文件系统 overlay、每个 worker 独立的 worktree，也没有任务结束后的 ChangeSet 合并阶段。嵌套工具各自获取资源锁，支持的文件编辑各自执行 expected hash 校验；这些保护不意味着整个多步子任务具备事务隔离。主线接收最终摘要、状态、用量和已追踪的改动文件，而不是完整的子任务过程记录。是否验证及验证范围仍由 agent 自主决定。
 
-<p align="center"><img src="./assets/architecture/multi-agent-zh-CN.svg" alt="MoCode 多 Agent overlay 与 ChangeSet 协调" width="100%"></p>
+对应实现：[子 agent 执行](src/agent/spawn.ts)、[sub-agent 工具](src/tools/builtins/task.ts)、[能力感知派发](src/agent/stages/tool-dispatcher.ts)。
 
 ### 受控执行:权限门 + 能力调度
 
@@ -68,18 +68,16 @@ MoCode 是一个分层的自治运行时：终端交互层驱动 Agent 内核，
 
 mocode 不会在任务结束时暗中启动验证瀑布。agent 可以根据任务风险自行调用 `run_command` 跑聚焦测试、typecheck 或 build；也可以在无需额外证据时直接结束，不产生框架强制的额外轮次。
 
-### 回滚时间线:每次写入都留干净撤销点
+### 回滚时间线：追踪文件改动，按轮次恢复
 
-每次写入工具执行前先存一份 undo 快照。`/rollback <turnId>` 按时间逆序在 canonical 资源锁下恢复文件缓冲，不重跑模型，也不自动启动测试。读取类工具、网络副作用、二进制改动明确不在截图范围，契约里写死。
+回滚记录支持范围内的文本文件改动，包括子 agent 在父级轮次中产生的已追踪改动。`/rollback` 在规范化资源锁下恢复已记录的文件内容，不重跑模型，也不自动启动测试。它不是通用撤销机制：网络副作用、桌面操作、二进制改动及其他未追踪的副作用不在恢复范围内。中断当前轮次不会自动撤销已经完成的文件写入。
 
-<p align="center"><img src="./assets/architecture/rollback-flow-zh-CN.svg" alt="MoCode 回滚时间线和每轮快照流" width="100%"></p>
+快照捕获与恢复边界见[回滚存储实现](src/rollback/store.ts)。
 
 ### 上下文控制：一个真实压力线，阶段独立可选
 
 这些控制项仍可独立配置，但自动改写只有一个触发条件：校正后或原始请求占用达到 80%。该事件会运行所有已启用的 pressure 清理，然后始终继续压缩历史。`contextLifecycle` 只维护 provenance 元数据，EWMA 则让估算持续对齐 provider 实测用量。
 
-<p align="center"><img src="./assets/architecture/context-controls-zh-CN.svg" alt="MoCode 上下文控制:五个独立开关、观察生命周期、token 自校准" width="100%"></p>
-
 ### 桌宠:WebSocket 上的被动镜像
 
 可选 Electron 子包(`packages/pet-app`)用一个悬浮小角色镜像 agent 状态:单向 WebSocket 推送事件帧,`/pet quit` 完全关闭。渲染层零业务逻辑,无论桌宠是否在跑,主 agent 循环一字不改。
@@ -91,7 +89,7 @@ mocode 不会在任务结束时暗中启动验证瀑布。agent 可以根据任
 mocode 把代码层控制保持得尽量轻，把任务策略交给 agent：
 
 - **建议式工作纪律** — system prompt 只要求聚焦改动、避免重复检索、诚实报告不确定性；是否验证及验证范围由 agent 自主决定，不是完成硬门。
-- **透明工具失败** — 每个工具调用只执行一次，原始结构化错误直接交给 agent，由 agent 自主决定是否以及如何恢复。
+- **有界重试，明确报告失败** — runtime 仅对显式声明 `idempotent` 的工具瞬时错误自动重试，最多两次；`TIMEOUT`、权限拒绝、中断和非幂等调用不自动重试。最终结构化结果交给 agent，由其决定后续恢复方式，详见[自动重试](#自动重试retryable-契约)。
 - **ask_human 卡点降级** — 仅高影响且属于用户所有权的选择才询问，其余实现细节由 agent 自主推进。
 - **五区上下文控制 + token 自校准** — 独立旋钮管理上下文压力，token 估算根据真实 provider 用量校准。
 
@@ -100,15 +98,15 @@ mocode 把代码层控制保持得尽量轻，把任务策略交给 agent：
 mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 
 - **自主多步推进** — 一次对话里连续多步:读代码、改代码、跑测试、根据报错再改……agent 自己决定下一步,中途不用你反复催。遇到卡点会调 `ask_human` 弹面板问你(阻塞到回应)。
-- **只读工具并行执行** — 一轮里连续的只读操作(读文件、grep、glob、codegraph、联网搜索/抓取)自动并发跑,总耗时 ≈ 最慢一个,而不是逐个排队。写文件 / 改文件这类有副作用的操作仍串行,保快照顺序与数据安全。
-- **子 agent 分而治之** — 复杂任务可派生拥有独立历史与受限工具集的子 agent。只读 worker 可并行扇出；写 worker 在私有文件系统 overlay 中运行，返回的 ChangeSet 经过 expected hash 校验与规范化资源锁后才合并。主线只接收结构化发现，不接收过程噪声。
-- **计划 / 执行双模式** — `plan` 模式下只读探查(读代码、查索引、搜索,绝不写盘、不跑命令、不派生子 agent),产出计划；`auto` 模式允许执行，但不是静态“全工具”模式：每个真实用户轮先由轻量 LLM router 选择最小充分工具簇，主模型需要时可在后续 step 追加能力。
+- **能力感知并发** — 连续且声明支持并行的工具（如读文件、grep、glob、联网读取）可并发执行。按资源加锁的文件改动也可同时派发，由规范化资源锁协调冲突资源，而不是把所有写入全局串行化。进程类及未声明并行能力的工具保持各自的串行执行约束。
+- **子 agent 分而治之** — 子任务拥有独立历史分支，工具权限不超过父 step 的能力上限；按并发上限分批运行，直接写入共享工作区并共用父级回滚轮次。主线接收最终摘要及执行元数据；没有每个 worker 独立的文件系统隔离或合并阶段。
+- **计划 / 执行双模式** — `plan` 模式下探查并产出计划，不修改项目文件、不跑 shell 命令、不派生子 agent；内部会话和计划记录仍可持久化。`auto` 模式允许执行，但不是静态“全工具”模式：每个真实用户轮先由轻量 LLM router 选择最小充分工具簇，主模型需要时可在后续 step 追加能力。
 - **统一压力驱动压缩** — 正常 history 保留完整工具证据；达到 80% 后由一次调度事件运行所有已启用的清理，并始终继续 history 摘要。`/context` 显示实时用量，`/compact` 仍是用户显式覆盖。
-- **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;后台还会定期从对话里反思挖掘值得记住的事。记忆可增删改、带召回衰减。
+- **跨会话长期记忆** — agent 能把项目架构、约定、踩过的坑存成长期记忆,下次会话自动加载;可通过 `AUTO_REFLECT=true` 开启后台反思，从对话中挖掘值得记住的事实（默认关闭）。记忆可增删改、带召回衰减。
 - **会话记事本(notes.md)** — 复杂多步任务(≥3 处文件改动 / ≥5 步工具调用)时,agent 在 `.mocode/sessions/<sessionId>/notes.md` 维护一个工作记事本(落盘抗压缩),可记录中间发现、设计决策、待验证问题和结构化计划。执行计划由专用 `plan_update` 工具维护——三态步骤机(`pending`/`in_progress`/`completed`,同一时刻至多一个 `in_progress`),全部完成自动结算为 `## Done:`。活跃 plan 在压缩后重注入系统提示、notes.md 一变就重同步进上下文,若连续多步未更新还会有温和提醒。TUI 状态栏实时显示进度 chip:`plan: [标题] (3/7) ▸ [当前步]`。
-- **可中断、可回滚** — Ctrl+C 随时打断当前轮次(树杀子进程,历史还原到本轮开始前,不留残半的工具调用);`/rollback` 按轮次快照恢复文件改动,逐个文件「保留/撤销」,不依赖 git。
+- **可中断、可回滚** — Ctrl+C 将中断信号传给模型请求及支持取消的运行中工具；历史恢复到最近已提交工具批次的检查点，而不是无条件丢弃整轮。已经完成的文件写入仍保留，需显式撤销；`/rollback` 可从轮次快照恢复已追踪文件，逐个选择「保留/撤销」，不依赖 git。
 - **输入安全网** — 长 prompt 不再怕误按 Enter:`Ctrl+G` 弹出 TUI 内「输入面板」(记事本式编辑,Enter=换行、软换行、选区、复制/剪切/粘贴、撤销,Ctrl+S 填回输入框不自动发送);`Ctrl+R`/`Ctrl+P` 模糊搜索历史输入(Enter 只回填不发送);长文本误发后撤回窗口自动放宽到 2 秒且任意键可撤回。
-- **沙箱防护** — 文件读写经沙箱拦截,挡掉越界路径(`../../`、绝对外圈、软链出圈等),不碰工作目录之外的文件。
+- **文件路径边界** — 内置文件读写拒绝越出 `SANDBOX_ROOT`（默认工作目录）的路径，包括路径穿越和软链出圈。这是文件工具的路径保护，不是针对 shell 命令、MCP server 或桌面输入的操作系统级沙箱；记忆与 skills 可以按设计访问项目外的配置位置。允许高风险工具前应审查权限，详见[沙箱策略](src/sandbox/policy.ts)。
 - **Computer Use(高危，仅明确 GUI 意图时路由)** — 请求确实需要真实鼠标/键盘交互时，router 才可暴露 `computer-control`，并把每次动作后的截图回灌模型。`/cu off`（或 `MOCODE_COMPUTER_USE_ENABLED=false`）是硬否决；`/cu on` 仅允许按需路由，不会让工具常驻。它会绕过文件沙箱，**强烈建议只在 VM / 沙箱 / 专用测试机里使用**。每个动作仍走权限门，plan 模式永远屏蔽。Windows 首发，macOS/Linux 待接入。
 
 ## 特性
@@ -141,7 +139,7 @@ npm install -g mocode-ai
 
 装完即得 `mocode` 命令。不想全局装也可免装直跑:`npx mocode-ai`。
 
-> mocode 启动时自动检测新版本,后台 `npm i -g mocode-ai@latest` 自更新——下次启动生效,零启动延迟、断网 / 失败静默。开发态 `npm start`(tsx 跑 `.ts`)不触发。
+> mocode 启动时不查询 registry，也不自动安装更新。需要时显式使用 `/upgrade check`、`/upgrade status` 或 `/upgrade now` 检查、查看状态或升级；源码/tsx 开发模式禁止真正执行安装。实现见[升级命令](src/commands/upgrade.ts)。
 
 ### 从源码运行(开发 / 贡献)
 
@@ -152,7 +150,23 @@ npm install
 npm start
 ```
 
-源码经 tsx 直接跑,无构建步骤。改完代码需重启 `npm start` 生效(tsx 启动时加载模块,不热更新)。依赖:`openai`、`dotenv`、`fast-glob`(运行时);`tsx`、`typescript`、`@types/node`(开发)。
+源码经 tsx 直接运行，无需先构建。修改代码后需重启 `npm start` 生效（tsx 启动时加载模块，不热更新）。请在仓库根目录安装依赖，让 npm 处理 workspaces；完整依赖和开发命令以 [package.json](package.json) 为准，不在此重复维护清单。
+
+### 技术栈状态与贡献边界
+
+生产主路径是 TypeScript CLI；`packages/work-app` 处于孵化阶段，`packages/pet-app` 是可选组件，`rust/` 是非关键路径的实验性 TUI，设有晋升或归档期限。参见：
+
+- [技术栈状态与责任人](docs/architecture/stack-status.md)
+- [架构决策](docs/adr/README.md)
+- [贡献指南](CONTRIBUTING.md)
+- [维护与排障手册](docs/runbooks/README.md)
+- [Rust 实验状态](rust/README.md)
+
+不要导入其他 package 的 `src/` 或内部 `dist/` 布局；应用通过 package exports 和公开的 `mocode-agent-host` bin 契约消费能力。
+
+### 文档与实现同步
+
+修改执行、权限、并发、回滚或升级行为时，应按本页对应的源码入口同步更新 `README.md` 和 `README.zh-CN.md`；架构图与当前行为一致后才嵌入。依赖与工具清单分别以 package manifests 和内置工具注册表为准，发布边界以技术栈状态页为准，不把设计提案或旧架构图当作已交付保证。
 
 ## 配置
 
@@ -208,6 +222,8 @@ LLM_MODEL=glm-4.6                              # 换成你的模型名
 | `MOCODE_LIFECYCLE`              | 只维护 provenance 元数据，不按次数改写正文                                   | `true`                      |
 | `MAX_STEPS`                     | 每轮 Agent 循环最大步数（仅防无限循环）                                      | `1000`                      |
 | `SUB_AGENT_MAX_STEPS`           | 子 Agent 循环安全上限，默认与主 Agent 一致                                   | `1000`                      |
+| `SUB_AGENT_CONCURRENCY`         | 每批子 agent 调用的并发上限；设为 `1` 时逐个派发                             | `5`                         |
+| `SUB_AGENT_MAX_DEPTH`           | 递归委派深度上限                                                              | `3`                         |
 | `SANDBOX_ROOT`                  | 沙箱根目录(文件操作边界;未配则用 cwd 兜底)                                   | 无                          |
 | `MOCODE_SUBAGENT_ENABLED`       | 设 `false` 硬禁用 `orchestration`；unset/`true` 允许按需路由                 | 未设置                      |
 | `MOCODE_FRONTEND_TOOLS_ENABLED` | 设 `false` 硬禁用 `browser-debug` / `desktop-observe`（不影响 `background-exec`）；unset/`true` 允许路由 | 未设置                      |
@@ -226,7 +242,7 @@ mocode --resume <id>            # 续接指定会话
 mocode config                   # 改配置
 ```
 
-从源码跑则用 `npm start`(等价于 `mocode`,但不触发自更新)。
+从源码运行使用 `npm start`。源码和安装版启动时都不会自动检查更新；`/upgrade` 由用户显式触发，源码/tsx 模式禁止真正执行安装。
 
 进入 REPL 后直接对话。启动即进全屏 TUI,显示横幅(模型 / 后端 / 工作目录 / 工具列表)。回复流式打印,思考段实时可见后折叠。
 
@@ -234,7 +250,9 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 
 ## 工具
 
-每个真实用户轮都会先经过受约束的 LLM router。九个公共工具始终可用（`read_file`、`glob`、`grep`、`web_search`、`web_fetch`、`plan_update`、`note_append`、`ask_human`、`use_skill`）；写文件、shell 调试、浏览器调试、桌面观察/控制、记忆、编排和 MCP 作为可组合工具簇按需选择。初始能力不足时，主模型必须单独调用 `add_tool_groups`，新增 schema 从下一 step 生效。路由失败只继承上一轮工具簇（或仅公共工具），绝不回退到全工具。
+每个真实用户轮都会先经过受约束的 LLM router。公共工具包括 `read_file`、`glob`、`grep`、`web_search`、`web_fetch`、`plan_update`、`note_append`、`ask_human`、`use_skill`；写文件、shell 调试、浏览器调试、桌面观察/控制、记忆、编排和 MCP 作为可组合工具簇按需选择。初始能力不足时，主模型通过 `add_tool_groups` 请求追加能力，新增 schema 从下一 step 生效。路由失败只继承上一轮工具簇（或仅公共工具），绝不回退到全工具。
+
+以下表格列举部分能力，不是完整工具清单。当前注册及能力声明见[内置工具注册表](src/tools/builtins/index.ts)，实际暴露由 [ToolPolicy](src/tools/policy.ts) 控制。Codegraph 查询在安装了对应 skill/CLI 时使用，不是独立的内置 `codegraph` 工具。
 
 | 工具          | 作用                                                                                                                   |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -246,20 +264,22 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `dev_server`  | 启动/查看/读日志/停止**任意需跨调用存活的后台进程**(dev server、推理服务、watcher、日志尾随)                            |
 | `browser`     | Playwright 驱动真实 Chromium:导航 / 点击 / 填表 / 取文本 / 截图 / 控制台诊断                                           |
 | `glob`        | 按 glob 模式找文件(排除 node_modules/.git)                                                                             |
-| `grep`        | 内容正则搜索,纯 JS 实现,不依赖 `rg`;`context=N` 内联返回邻居行并保留原始缩进,命中后基本不用再 read_file 一次            |
-| `codegraph`   | 已建 `.codegraph/` 索引时,查代码符号源码与调用链(比 read_file/grep 更准更省)                                           |
+| `grep`        | 内容正则搜索,以 ripgrep 为快速路径(随 `@vscode/ripgrep` 分发,尊重 `.gitignore`、跳过二进制),找不到 `rg` 时才回退纯 JS 扫描;`context=N` 内联返回邻居行并保留原始缩进,命中后基本不用再 read_file 一次            |
 | `web_search`  | 联网搜索(AnySearch),返回标题/URL/摘要/正文                                                                             |
 | `web_fetch`   | 抓取指定 URL,HTML 清洗成纯文本;带全套浏览器拟真头,瞬时失败(429/5xx/网络抖动)自动退避重试,可选纯文本代理回退              |
 | `use_skill`   | 加载某 skill 的完整 SKILL.md 指令                                                                                      |
 | `ask_human`   | 决策点弹终端问答面板,用户选预设项或自由输入(阻塞至回应)                                                                |
 | `plan_update` | 记录/更新会话执行计划(notes.md 的 `## Plan:` 段);三态步骤机,同一时刻至多一个 in_progress,全部完成自动结算为 `## Done:` |
-| `sub-agent`   | 派生工具权限不超过父级 snapshot 的隔离子 Agent；只读任务可并发，写任务通过 overlay + ChangeSet 安全合并                |
+| `sub-agent`   | 派生独立历史、工具权限不超过父 step 的子 agent；有界并发，共享工作区和回滚轮次                |
 
+| 记忆工具 | 作用 |
+| -------- | ---- |
 | `memory_save` | 存一条跨会话长期记忆(标题进索引,正文按需取) |
 | `memory_search` | 按关键词搜记忆正文,命中即提升召回计数(影响遗忘衰减) |
 | `memory_list` | 列记忆索引(id/标题/摘要,无正文) |
 | `memory_update` | 原地改一条记忆(id 不变;纠正过时事实 / 改摘要 / 改 pin) |
 | `memory_forget` | 遗忘记忆:默认归档(可复活),`mode=delete` 硬删(pinned 拒删) |
+| `memory_graph` | 遍历邻居、查找路径、添加三元组或查看图谱统计；关键词搜索由 `memory_search` 提供 |
 
 ### 前端 / UI 闭环
 
@@ -277,7 +297,7 @@ dev_server stop   id=srv-xxxx
 - 两者在 plan 模式下均被禁用;mocode 退出时会树杀后台进程并关闭浏览器。
 - 浏览器二进制不随 npm 包分发,首次使用前需 `npx playwright install chromium`。
 
-前端能力按用途拆分：`browser` 属于 `browser-debug`，整桌面截图 `screenshot` 属于 `desktop-observe`，而 `dev_server` 独立成**无 gate 的 `background-exec` 簇** —— 任何需要跨工具调用存活的进程（dev server、推理/模型服务、watcher、日志尾随）都归它，而不是塞进 `run_command`。选中 `browser-debug` 会**蕴含**激活 `background-exec`：弱模型只想到要浏览器时，也能拿到「先把服务起起来」的能力（半套能力比多一套能力更糟）。图片读取（`read_file` 魔数分流）则始终是公共只读能力。任务同时需要结构化网页诊断与真实桌面交互时，router 可再组合 `computer-control`。`/fe off` 是硬否决，不是手动 profile 选择器——它不影响 `dev_server`。
+前端能力按用途拆分：`browser` 属于 `browser-debug`，整桌面截图 `screenshot` 属于 `desktop-observe`，而 `dev_server` 独立成 **`background-exec` 簇**（不受 `/fe` 开关控制，但执行仍需经过权限检查） —— 任何需要跨工具调用存活的进程（dev server、推理/模型服务、watcher、日志尾随）都归它，而不是塞进 `run_command`。选中 `browser-debug` 会**蕴含**激活 `background-exec`：弱模型只想到要浏览器时，也能拿到「先把服务起起来」的能力（半套能力比多一套能力更糟）。图片读取（`read_file` 魔数分流）则始终是公共只读能力。任务同时需要结构化网页诊断与真实桌面交互时，router 可再组合 `computer-control`。`/fe off` 是硬否决，不是手动 profile 选择器——它不影响 `dev_server`。
 
 ### Shell 选择器
 
@@ -313,6 +333,7 @@ dev_server stop   id=srv-xxxx
 | `/model`         | 两级面板切换模型(先选厂商再选模型;顶层按厂商名、厂商内按模型名过滤);也可配置 baseURL / apiKey / 上下文窗口,即时生效 + 持久化 |
 | `/effort`        | 设置思考强度 off/low/medium/high/auto(如 `/effort high`);未识别模型不下发参数 |
 | `/stats`         | 本会话用量:缓存命中率 / 分层 token / 压缩次数 |
+| `/upgrade`       | 显式检查更新、查看状态或安装（`check` / `status` / `now`）；启动时不自动更新 |
 | `/init`          | 扫描项目生成 `AGENTS.md` 项目记忆(发给 agent 执行)                  |
 | `/theme`         | 切换颜色主题(↑↓ · Enter,或 `/theme <name>` 直切)                    |
 | `/plan`          | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |
@@ -364,9 +385,9 @@ mocode 的**双层记忆**模型,跟 Skills 是两件事:
 ## 类型检查
 
 ```bash
-npm run typecheck   # tsc --noEmit
+npm run typecheck   # protocol/runtime + 根项目 + tests + evals
 ```
 
 ## 可后续扩展
 
-MCP 工具集成、更细粒度的 capability 资源锁、真·worktree 隔离的子 agent 模式。当前版本已是流式、思考可见、可回滚的终端编码 agent:内置文本与视觉工具集、工作记事本规划、跨会话记忆、能力感知工具调度、共享工作区串行子 agent、可选桌宠。
+MCP 工具集成已经支持，配置见 [MCP 指南](src/mcp/README.md)。更细粒度的能力协调、可选的每 worker 独立 worktree 是后续扩展方向，不是当前共享工作区子 agent 已具备的保证。现有工具以[内置工具注册表](src/tools/builtins/index.ts)为准，生产、可选、孵化和实验技术栈的区别见[技术栈状态](docs/architecture/stack-status.md)。

package/dist/agent/stages/history-manager.js

@@ -10,10 +10,13 @@ function assistantMessage(turn) {
         content: turn.content,
     };
     if (turn.toolCalls.length > 0) {
+        // thoughtSignature 不是 OpenAI 字段，是 mocode 给 Gemini/Vertex 透传用的；
+        // 挂在 tool_call 上随 history 落盘/回灌，Vertex encoder 会读回它。
         message.tool_calls = turn.toolCalls.map((call) => ({
             id: call.id,
             type: 'function',
             function: { name: call.name, arguments: call.arguments },
+            ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
         }));
     }
     return message;

package/dist/config/index.js

@@ -83,7 +83,15 @@ const __activePreset = (() => {
 })();
 setLanguage(detectLanguage(process.env.MOCODE_LANGUAGE));
 export function normalizeLlmProvider(value) {
-    return typeof value === 'string' && value.toLowerCase() === 'anthropic' ? 'anthropic' : 'openai';
+    if (typeof value !== 'string')
+        return 'openai';
+    const provider = value.toLowerCase();
+    if (provider === 'anthropic')
+        return 'anthropic';
+    // Vertex 与 Gemini Developer API 共用 Gemini Contents 协议，统一注册为 google。
+    if (provider === 'google' || provider === 'gemini' || provider === 'vertex')
+        return 'google';
+    return 'openai';
 }
 /**
  * 取环境变量;缺则返回空字符串(不退出)。
@@ -462,6 +470,7 @@ Complete programming tasks through an "analyze → call tool → observe result
 ## Workflow
 - Understand: use existing conversation and tool evidence before gathering more.
 - Plan: for tasks with 3+ steps or context-loss risk, record the plan with the \`plan_update\` tool (see Session state).
+- Delegate: when the \`sub-agent\` tool is exposed, prefer it for exploration-heavy work (unfamiliar subsystems, multi-file audits, open-ended "how does X work here" investigation) and for independent sub-tasks — emit several \`sub-agent\` calls in ONE message and they run concurrently. A worker returns only its summary, so its tool noise never floods the main context. Keep single known-path reads and trivial lookups inline.
 - Implement: edit against a fresh read (see Tool policy); change scope follows Engineering principles.
 - Verify: whether and what to run follows Engineering principles; use Validation commands for exact commands.
 - Report: stop when done and give honest conclusions with path:line references (see Reporting).
@@ -495,7 +504,7 @@ ${buildVoiceSection()}
 - Stop immediately when no more tools are needed; give conclusions directly.
 - **Do not stop prematurely during exploration**: if you started investigating but haven't gathered enough information to answer the user's question, keep calling tools. Only stop when you have sufficient evidence or hit a dead end.
 - **No flattery / no preamble in conclusions**: skip "Sure", "好的", "我已经完成了" and similar no-information prefixes — jump straight to substance.
-- Report honestly: say success when successful, say where you're stuck when failing, and mention anything skipped. Reference code in "path:line" format (e.g., src/index.ts:42). Keep it concise.
+- Close with a brief explanation of what you did and why, not just a verdict, so the user doesn't have to re-read the tool trace: when files changed, group them by file or logical change — what changed and the behavior/fix it delivers, one or two lines each with "path:line" references, noting renames/deletions and skipping purely mechanical edits; for investigation or analysis, state the conclusion and the key evidence. Say success when successful, where you're stuck when failing, and anything skipped. Keep it concise.
 - Definition of done: never declare a multi-feature request finished just because the code exists. Each distinct user request listed in the plan must be actually verified (the relevant check run / observed result), not merely implemented; mark plan steps \`[x]\` only after that verification. If the user supplied an acceptance list, every item on it must pass. Leave unverified items explicitly listed as pending instead of collapsing them into "done".`;
     // 动态段(置于末尾):AGENTS.md 项目记忆 + notepad 索引/说明。工具簇特定指导由
     // ToolPolicyController.reminder() 按当前 turn 的 route 注入，避免旧全局 profile 与真实 schema 分裂。

package/dist/config/presets.js

@@ -47,6 +47,17 @@ export function setActivePresetName(name) {
     fs.renameSync(tmp, ACTIVE_PRESET_PATH);
 }
 const NAME_RE = /^[a-zA-Z0-9_-]{1,32}$/;
+/** Vertex 与 Gemini Developer API 共用 Contents 协议；旧文件/别名统一规范化为 google。 */
+export function normalizePresetProvider(value) {
+    if (typeof value !== 'string')
+        return 'openai';
+    const provider = value.toLowerCase();
+    if (provider === 'anthropic')
+        return 'anthropic';
+    if (provider === 'google' || provider === 'gemini' || provider === 'vertex')
+        return 'google';
+    return 'openai';
+}
 /** 名字是否合法(调用方复用,避免在多处重复同一正则)。 */
 export function isValidPresetName(name) {
     return NAME_RE.test(name);
@@ -77,7 +88,7 @@ export function parsePreset(raw) {
     if (typeof contextWindow !== 'number' || !Number.isFinite(contextWindow) || contextWindow <= 0) {
         throw new Error(`预设 ${name}: contextWindow 必须为正数`);
     }
-    const provider = obj.provider === 'anthropic' ? 'anthropic' : 'openai';
+    const provider = normalizePresetProvider(obj.provider);
     const anthropicPromptCache = provider === 'anthropic' && obj.anthropicPromptCache !== false;
     // reasoningEffort 缺省 = auto;显式写了非法值按现有校验风格报错(坏文件由 listPresets 跳过)。
     let reasoningEffort;
@@ -147,7 +158,7 @@ export function savePreset(preset) {
     if (!isValidPresetName(preset.name)) {
         throw new Error(`非法预设名: ${JSON.stringify(preset.name)}`);
     }
-    const provider = preset.provider ?? 'openai';
+    const provider = normalizePresetProvider(preset.provider);
     const normalized = {
         ...preset,
         provider,

package/dist/config/profiles.js

@@ -99,7 +99,7 @@ export const TOOL_ROUTE_GROUPS = {
     },
     orchestration: {
         tools: ['sub-agent', 'run_skill'],
-        description: 'Delegate genuinely independent work or execute a packaged fork skill in an isolated worker.',
+        description: 'Delegate exploration-heavy or parallelizable work to isolated workers: codebase investigation, multi-file research, audits, independent sub-tasks, or a packaged fork skill. Keeps exploration noise out of the main context.',
         gateEnv: 'MOCODE_SUBAGENT_ENABLED',
     },
     mcp: {