Describe the goal, not the graph.
- Multi-agent orchestration that runs in your own environment.
+ A self-organizing team of agents that runs in your environment, pauses for approval on consequential actions, and leaves a verifiable record of every run.
+
+
@@ -127,11 +124,11 @@ Set `OPENAI_API_KEY` to run this example. [Providers](docs/providers.md) covers
OMA combines dynamic orchestration with the control, evidence, and recovery paths needed to move multi-agent systems from prototype to production.
- **Dynamic orchestration.** Describe the goal and let the coordinator build the task DAG, assign work, and synthesize the result at runtime. There is no hand-wired graph to maintain.
-- **Controlled execution.** Preview, approve, or durably suspend plans, task dispatches, and tool calls; freeze approved plans for replay. Declare required roles and order when topology cannot drift, and verify outputs with multi-agent consensus.
+- **Controlled execution.** Preview, approve, or durably suspend plans, task dispatches, and tool calls; the framework ships the approval API and durable records, and the review surface and transport are yours to build. Freeze approved plans for replay. Declare required roles and order when topology cannot drift, and verify outputs with multi-agent consensus.
- **Reliability.** Resume interrupted runs from checkpoints, or opt into append-only plan repair at task outcome barriers. Retries, timeouts, loop detection, and token and cost budgets keep execution bounded.
-- **Observability and evaluation.** Follow each run through stable identity, execution receipts, and traces. Replay the task DAG and span waterfall in the offline Run Viewer, or export through the optional OpenTelemetry adapter. The same records feed versioned EvalSets, offline reports, CI gates, and production sampling.
+- **Observability and evaluation.** Follow each run through stable identity, execution receipts, and traces; the record is verifiable for order and lineage, not tamper-evident. Replay the task DAG and span waterfall in the offline Run Viewer, or export through the optional OpenTelemetry adapter. The same records feed versioned EvalSets, offline reports, CI gates, and production sampling.
- **Safety and privacy.** Tools are default-deny, individual calls are gated, and explicit privacy controls apply to telemetry and persisted state.
-- **Open runtime.** Process and ACP backends put Claude Code, Gemini CLI, and Codex on the same task DAG, shared memory, and budgets as LLM agents. Mix cloud and local models, natively integrated Chinese providers, OpenAI-compatible endpoints, and AI SDK providers, with a fallback parser for local models that emit tool calls as text. Run on your own infrastructure and credentials, locally, offline, or air-gapped.
+- **Open runtime.** Process and ACP backends put Claude Code, Gemini CLI, and Codex on the same task DAG, shared memory, and budgets as LLM agents, though those backends run outside the per-call tool gate, filesystem sandbox, and LLM egress policy. Mix cloud and local models, natively integrated Chinese providers, OpenAI-compatible endpoints, and AI SDK providers, with a fallback parser for local models that emit tool calls as text. Run on your own infrastructure and credentials, locally, offline, or air-gapped; see [Self-hosting and data residency](docs/self-hosting.md).
## Built with OMA
diff --git a/README_zh.md b/README_zh.md
index 496cd93..a3e7465 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -1,25 +1,22 @@
-
-
-
@@ -126,11 +123,11 @@ console.log(result.totalTokenUsage)
OMA 将动态编排与生产所需的控制、证据和恢复能力结合起来，帮助多智能体系统从原型走向生产环境。
- **动态编排。** 只需描述目标，Coordinator 就会在运行时生成任务 DAG、分配工作并合成结果，无需手工维护工作流图。
-- **受控执行。** 可预览、审批或持久化挂起计划、任务派发与工具调用，并固化已审批计划以供重放；当拓扑不容漂移时可声明必需的角色与执行顺序，并通过多 Agent 共识验证结果。
+- **受控执行。** 可预览、审批或持久化挂起计划、任务派发与工具调用，并固化已审批计划以供重放；框架提供审批 API 与持久化审批记录，审批界面与传递通道由接入方自行实现。当拓扑不容漂移时可声明必需的角色与执行顺序，并通过多 Agent 共识验证结果。
- **可靠性。** 通过 Checkpoint 从断点恢复中断的运行，或选择在任务结果屏障处启用仅追加式计划修复；重试、超时、循环检测与 token、成本双预算让执行始终有明确边界。
-- **可观测与评测。** 通过稳定的运行标识、执行回执与 Trace 跟踪每次运行，在离线 Run Viewer 中回放任务 DAG 与 span 瀑布，或通过可选的 OpenTelemetry 适配器导出；同一套运行记录可直接支撑版本化 EvalSet、离线报告、CI gate 与线上采样。
+- **可观测与评测。** 通过稳定的运行标识、执行回执与 Trace 跟踪每次运行，在离线 Run Viewer 中回放任务 DAG 与 span 瀑布，或通过可选的 OpenTelemetry 适配器导出；同一套运行记录可直接支撑版本化 EvalSet、离线报告、CI gate 与线上采样。这套记录可核验执行顺序与血缘，但不提供防篡改保证。
- **安全与隐私。** 内置工具默认拒绝，支持逐次调用 gate，并对遥测与持久化状态应用显式的隐私控制。
-- **开放运行时。** Process 与 ACP backend 让 Claude Code、Gemini CLI、Codex 和 LLM Agent 同处一个任务 DAG，并共享记忆与预算；可混用云端模型、本地开源模型、原生接入的国产模型、OpenAI 兼容端点与 AI SDK provider，并通过容错解析支持以文本形式返回工具调用的本地模型；支持使用自有基础设施与凭证，本地、离线或气隙部署。
+- **开放运行时。** Process 与 ACP backend 让 Claude Code、Gemini CLI、Codex 和 LLM Agent 同处一个任务 DAG，并共享记忆与预算，但这类外部 backend 不在逐次工具 gate、文件沙箱与 LLM 出网策略的覆盖范围内；可混用云端模型、本地开源模型、原生接入的国产模型、OpenAI 兼容端点与 AI SDK provider，并通过容错解析支持以文本形式返回工具调用的本地模型；支持使用自有基础设施与凭证，本地、离线或气隙部署，详见[自托管与数据驻留](docs/self-hosting.md)。
## 基于 OMA 构建
diff --git a/packages/core/README.md b/packages/core/README.md
index d953557..c9c898f 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,25 +1,22 @@
-
-
-
+
-
+
-
-
-
-
-
Open Multi-Agent
+ Open Multi-Agent
+
Describe the goal, not the graph.
- Multi-agent orchestration that runs in your own environment.
+ A self-organizing team of agents that runs in your environment, pauses for approval on consequential actions, and leaves a verifiable record of every run.
+
+
@@ -171,7 +168,7 @@ Agents may declare `description`, `capabilities`, `costTier`, and `latencyClass`
| **Evaluation** | Version EvalSets, run reference scorers, gate CI with offline reports, persist results, or sample production runs on a best-effort path. |
| **Memory and recovery** | Shared memory is pluggable; checkpoints resume interrupted runs without repeating completed tasks. |
| **Observability** | Stable run identity, traces, execution receipts, redaction, TraceStore, and the offline DAG/Waterfall Viewer are available without a hosted service. |
-| **External agents** | ACP and process backends let coding CLIs participate while OMA keeps scheduling, memory, and budgets. |
+| **External agents** | ACP and process backends let coding CLIs participate while OMA keeps scheduling, memory, and budgets; the per-call tool gate, filesystem sandbox, and LLM egress policy do not cover them. |
## Architecture
@@ -222,7 +219,7 @@ Change `provider`, `model`, and credentials; the agent shape stays the same.
Optional integrations load only when used: core directly installs only `@anthropic-ai/sdk`, `openai`, and `zod`; other SDKs are lazy-loading opt-in peers, and OpenTelemetry lives entirely in `@open-multi-agent/otel`. Dependency changes are weighed on demonstrated value plus security, size, maintenance, and compatibility cost, not a fixed count.
-See [Providers](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/providers.md), [framework-owned LLM egress policy](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/egress-policy.md), and [Tool configuration](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/tool-configuration.md) for credentials, models, the AI SDK bridge, reasoning settings, MCP, local endpoints, and the exact network-enforcement boundary.
+See [Providers](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/providers.md), [framework-owned LLM egress policy](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/egress-policy.md), [Self-hosting and data residency](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/self-hosting.md), and [Tool configuration](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/tool-configuration.md) for credentials, models, the AI SDK bridge, reasoning settings, MCP, local endpoints, self-hosted deployment, and the exact network-enforcement boundary.
**Provider sponsors**
@@ -238,7 +235,7 @@ Paid sponsors supporting `open-multi-agent`. Sponsorship does not affect technic
| Control spend | `maxTokenBudget`; `maxCostBudget` + application-owned `estimateCost` |
| Limit tools | `tools` / `toolPreset`, `cwd` / `defaultCwd`, tool-output caps |
| Recover | Task retries, checkpointing, `restore()`, and opt-in adaptive plan repair |
-| Review work | `planOnly`, inline approval callbacks, or [durable approval gates](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/durable-approvals.md) |
+| Review work | `planOnly`, inline approval callbacks, or [durable approval gates](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/durable-approvals.md); your application owns the approval surface and transport |
| Observe | Trace sinks, TraceStore, execution receipts, Run Viewer, or the optional OTel adapter |
Budget checks run at turn and task boundaries, so a run can overshoot by up to one model turn; they are not a cent-exact stop. `estimateCost` receives each call's token usage plus the agent, effective `model`, `provider`, phase, and `taskId`, and your application owns the price table.
@@ -265,7 +262,7 @@ See the [observability guide](https://github.com/open-multi-agent/open-multi-age
### Run journal
-When a long run goes wrong, the record usually missing is what each agent actually saw at the moment it was asked. The opt-in run journal keeps it: every message and tool result as an appended event, plus the exact block a context strategy put in place of the turns it dropped, so a finished run can be read back instead of reconstructed by guesswork. `verifyRun()` then checks offline that every block the model saw is reproducible from the log rather than trusting the log's own account of itself, and `restore()` can resume from the last appended event instead of the last snapshot. It is off by default, costs nothing when off, and is documented in the [run journal guide](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/run-journal.md).
+When a long run goes wrong, the record usually missing is what each agent actually saw at the moment it was asked. The opt-in run journal keeps it: every message and tool result as an appended event, plus the exact block a context strategy put in place of the turns it dropped, so a finished run can be read back instead of reconstructed by guesswork. `verifyRun()` then checks offline that every block the model saw is reproducible from the log rather than trusting the log's own account of itself, which establishes order and lineage rather than tamper-evidence, and `restore()` can resume from the last appended event instead of the last snapshot. It is off by default, costs nothing when off, and is documented in the [run journal guide](https://github.com/open-multi-agent/open-multi-agent/blob/main/docs/run-journal.md).
## Documentation
diff --git a/packages/core/README_zh.md b/packages/core/README_zh.md
index df90e1c..7ca6655 100644
--- a/packages/core/README_zh.md
+++ b/packages/core/README_zh.md
@@ -1,25 +1,22 @@
-
-
-
+ 
+ 
