agestra 4.13.2 → 4.13.4

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/agestra.svg)](https://www.npmjs.com/package/agestra)
 [![license](https://img.shields.io/npm/l/agestra.svg)](LICENSE)
 
-**Agent + Orchestra** — A multi-host orchestration toolkit for Claude Code, Codex CLI, and Gemini CLI.
+**Agent + Orchestra** — Multi-host MCP orchestration for Claude Code, Codex CLI, Gemini CLI, and local models.
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra connects the Claude host, Ollama (local), Gemini CLI, and Codex CLI as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, and quality-based provider routing — all through 44 MCP tools.
+Agestra connects the Claude host/CLI, Ollama (local), Gemini CLI, and Codex CLI as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, and capability-based provider routing with optional trace evidence — all through 45 MCP tools.
 
 ## Quick Start
 
@@ -46,10 +46,13 @@ At least one AI provider must be installed:
 
 | Provider | Install | Type |
 |----------|---------|------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `npm install -g @anthropic-ai/claude-code` | Cloud |
 | [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | Local LLM |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud |
 | [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | Cloud |
 
+Each CLI manages its own authentication. Sign in through each CLI's own login flow before using Agestra — Agestra spawns these CLIs as child processes and does not handle their credentials.
+
 Optional but recommended:
 - **tmux** — enables visible CLI worker panes during autonomous execution
 - **ripgrep (`rg`)** on Windows — if Codex resolves `rg` to its bundled Store-app path and fails with an "Access is denied" error, install ripgrep separately so a normal `rg.exe` is found first in `PATH`:
@@ -70,6 +73,52 @@ winget install BurntSushi.ripgrep.MSVC
 
 **Multi-AI is for verification, not token savings.** The review, design exploration, and idea generation workflows are structured as validation processes — getting independent opinions from multiple AI providers to catch blind spots, not to parallelize for speed.
 
+## How It Works
+
+```mermaid
+flowchart TD
+    Start([User invokes /agestra command]) --> Preflight[Setup status / environment / provider check]
+    Preflight --> Domain{Workflow type}
+
+    Domain -->|Idea / design / review / security| TextLead[Leader assembles specialist and external AIs]
+    Domain -->|QA| QaLead[Leader forms QA Brigade]
+    Domain -->|Implementation| ImplLead[Leader decomposes implementation work]
+
+    ImplLead --> ImplRoute{Task shape}
+    ImplRoute -->|Clear parallel implementation| CliWorkers[Codex / Gemini CLI workers<br/>isolated worktrees]
+    ImplRoute -->|Capability-matched scoped work| Ollama[Local/tool models<br/>read / write if policy allows]
+    ImplRoute -->|Risky or core change| HostImpl[Host implementer<br/>close leader supervision]
+    CliWorkers --> ReviewDiff[Leader monitors status / quota / diff]
+    Ollama --> ReviewDiff
+    HostImpl --> ReviewDiff
+    ReviewDiff --> Merge{Acceptable?}
+    Merge -->|No| Reassign[Correction prompt or reassignment]
+    Reassign --> ImplRoute
+    Merge -->|Yes| QaEvidence
+
+    QaLead --> QaEvidence[Host QA collects executable evidence<br/>build / tests / E2E / screenshots]
+    TextLead --> Providers{External AIs available?}
+    QaEvidence --> Providers
+
+    Providers -->|No| LocalOut[Host specialist writes<br/>domain report or document]
+    Providers -->|Yes| Individual[Each AI writes independent source material]
+    LocalOut --> Final([Report back to user])
+
+    Individual --> Ledger[ITEM-* JSON consensus ledger]
+    Ledger --> Round[Sequential rounds<br/>agree / disagree / revise / opinion]
+    Round --> Gate{Ledger state}
+    Gate -->|Needs more discussion| Round
+    Gate -->|Leader judgment needed| LeaderDecision[Leader chooses continue / approve / reject]
+    Gate -->|Resolved| LeaderDecision
+    LeaderDecision -->|Continue| Round
+    LeaderDecision -->|Approve| Approved[Approved synthesis document]
+    LeaderDecision -->|Reject| Rejected[Rejected / unresolved synthesis document]
+    Approved --> Final
+    Rejected --> Final
+```
+
+When no external provider is configured, Agestra skips consensus rounds and the host specialist writes the domain artifact: review or QA report, design plan, idea record, and so on. When a structured debate runs, leader finalization always leaves a synthesis document: approval produces an approved synthesis, while rejection produces a rejected/unresolved synthesis that lists accepted, excluded, and still-open items.
+
 ## Host Workflows
 
 | Host | Natural entrypoint |
@@ -98,7 +147,7 @@ When external providers are available, review, QA, security, design, and idea wo
 
 | Agent | Model | Role |
 |-------|-------|------|
-| `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop |
+| `agestra-team-lead` | Sonnet | Full orchestrator — environment check, capability-based provider routing, work mode selection, CLI worker supervision, QA loop |
 | `agestra-implementer` | Sonnet | Scoped implementation executor — code edits, test updates, local verification |
 | `agestra-e2e-writer` | Sonnet | Persistent E2E test writer — creates approved browser-flow tests without changing product behavior |
 | `agestra-reviewer` | Opus | Strict quality verifier — security, orphans, spec drift, test gaps |
@@ -134,13 +183,14 @@ Turborepo monorepo with 8 packages:
 
 | Package | Description |
 |---------|-------------|
-| `@agestra/core` | `AIProvider` interface, registry with difficulty-based routing, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager |
+| `@agestra/core` | `AIProvider` interface, provider descriptors with capability/difficulty metadata, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager |
+| `@agestra/provider-claude` | Anthropic Claude CLI adapter |
 | `@agestra/provider-ollama` | Ollama HTTP adapter with model detection |
 | `@agestra/provider-gemini` | Google Gemini CLI adapter |
 | `@agestra/provider-codex` | OpenAI Codex CLI adapter |
 | `@agestra/agents` | Debate engine with consensus detection, turn quality evaluator, task dispatcher, cross-validator, task chain, auto-QA, file change tracker, session manager |
 | `@agestra/workspace` | Workspace document manager for reviews, analysis notes, and aggregated reports |
-| `@agestra/mcp-server` | MCP protocol layer, 44 tools, environment-aware tool filtering, dispatch |
+| `@agestra/mcp-server` | MCP protocol layer, 45 tools, environment-aware tool filtering, dispatch |
 
 ### Design Principles
 
@@ -154,25 +204,27 @@ Turborepo monorepo with 8 packages:
 
 ### Work Modes
 
+In multi-provider modes (consensus debate, cross-validation, review rounds), one provider's output may become part of the prompt the next provider receives.
+
 **Text work** (review, QA, security, design, idea): providers available → consensus debate mode; no providers → Leader-host only. For QA, the team lead runs a QA Brigade by default while E2E/runtime checks stay host-owned.
 
 **Implementation work** (team-lead orchestration):
 - **Leader-host only** — `agestra-implementer` applies scoped code changes; the team lead still routes QA through the QA Brigade by default, with host-only review/QA available on request.
-- **Suggested AI distribution** — the team lead proposes a routing table, asks for approval, then dispatches Codex/Gemini CLI workers for suitable code edits and Ollama for simple/repetitive proposal work.
+- **Suggested AI distribution** — the team lead proposes a routing table, asks for approval, then distributes work according to the capabilities of detected models, including frontier and local models. Codex/Gemini CLI workers handle suitable autonomous code edits, and local/tool models may receive read-only or read/write AgentLoop tools according to their `executionPolicy`.
 
 ---
 
-## Tools (44)
+## Tools (45)
 
 ### AI Chat (3)
 
 | Tool | Description |
 |------|-------------|
-| `ai_chat` | Chat with a specific provider (use `"auto"` for quality-based routing); optionally persist replies with `save_as_document` |
+| `ai_chat` | Chat with a specific provider (use `"auto"` for trace-assisted routing when observations exist); optionally persist replies with `save_as_document` |
 | `ai_analyze_files` | Read files from disk and send contents with a question to a provider |
 | `ai_compare` | Send the same prompt to multiple providers, compare responses |
 
-### Agent Orchestration (14)
+### Agent Orchestration (15)
 
 | Tool | Description |
 |------|-------------|
@@ -181,10 +233,11 @@ Turborepo monorepo with 8 packages:
 | `agent_debate_create` | Create a turn-based debate session (returns debate ID) |
 | `agent_debate_turn` | Execute one provider's turn; supports `provider: "claude"` for Claude's independent participation |
 | `agent_debate_conclude` | End a debate and generate final transcript |
-| `agent_debate_structured` | Start an approval-gated structured debate in the background — individual reviews, optional alias clarification, JSON consensus rounds, status polling, and no synthesis until approved |
-| `agent_debate_approve` | Leader-approve a ready-for-approval structured debate; writes the synthesis document and closes the session |
+| `agent_debate_structured` | Start an approval-gated structured debate in the background — individual reviews, optional alias clarification, JSON consensus rounds, status polling, and no synthesis until the leader approves or rejects |
+| `agent_debate_approve` | Leader-approve a ready-for-approval structured debate; writes the approved synthesis document and closes the session |
 | `agent_debate_continue` | Start additional background rounds on a ready-for-approval or escalated structured-debate session (3/5/10), then poll status |
-| `agent_debate_reject` | Reject a structured-debate session without writing synthesis |
+| `agent_debate_reject` | Reject a structured-debate session; writes a rejected synthesis document and optionally an issue document |
+| `agent_debate_submit_turn` | Submit a native host-specialist turn when structured debate status reports `phase: awaiting-host-turn`; the workflow resumes after all pending host turns arrive |
 | `agent_debate_review` | Send a document to multiple providers for independent review |
 | `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) |
 | `agent_changes_review` | Review file changes from an isolated task |
@@ -204,7 +257,7 @@ Turborepo monorepo with 8 packages:
 
 | Tool | Description |
 |------|-------------|
-| `environment_check` | Detect CLI tools, Ollama models with tiers, tmux, git worktree support, available modes |
+| `environment_check` | Detect CLI tools, local model tiers, tmux, git worktree support, available modes |
 
 ### Workspace (7)
 
@@ -265,7 +318,7 @@ Turborepo monorepo with 8 packages:
 | Tool | Description |
 |------|-------------|
 | `trace_query` | Query trace records with filtering (provider, task, time range) |
-| `trace_summary` | Get quality stats, performance metrics, and difficulty qualification per provider |
+| `trace_summary` | Get optional prior quality observations and performance metrics per provider |
 | `trace_visualize` | Generate a Mermaid diagram of a traced operation's flow |
 
 ---
@@ -283,7 +336,7 @@ Created by `/agestra setup`. The default location is the host-shared `~/.agestra
 | `providers[].id` | Unique identifier |
 | `providers[].type` | `ollama`, `gemini-cli`, `codex-cli`, or `claude-cli` |
 | `providers[].enabled` | Whether to register this provider at startup — hard opt-out when `false` |
-| `providers[].executionPolicy` | `read-only` or `workspace-write` |
+| `providers[].executionPolicy` | `read-only`, `workspace-write`, or `full-auto`; Ollama uses this to choose read-only vs read/write AgentLoop tools |
 | `providers[].config` | Type-specific settings (host, timeout, etc.) |
 
 ### Runtime Data
@@ -374,12 +427,13 @@ agestra/
 │   └── uninstall-host-mcp.mjs # Remove host registrations and managed assets
 ├── packages/
 │   ├── core/                # AIProvider interface, registry, security, workers
+│   ├── provider-claude/     # Anthropic Claude CLI adapter
 │   ├── provider-ollama/     # Ollama HTTP adapter
 │   ├── provider-gemini/     # Gemini CLI adapter
 │   ├── provider-codex/      # Codex CLI adapter
 │   ├── agents/              # Debate engine, dispatcher, cross-validator
 │   ├── workspace/           # Workspace document manager
-│   └── mcp-server/          # MCP server, 44 tools, environment-aware filtering, dispatch
+│   └── mcp-server/          # MCP server, 45 tools, environment-aware filtering, dispatch
 ├── package.json             # Workspace root
 └── turbo.json               # Turborepo pipeline
 ```

package/README.zh.md

@@ -3,56 +3,34 @@
 [![npm version](https://img.shields.io/npm/v/agestra.svg)](https://www.npmjs.com/package/agestra)
 [![license](https://img.shields.io/npm/l/agestra.svg)](LICENSE)
 
-**Agent + Orchestra** — 一个可在 Claude Code、Codex CLI 与 Gemini CLI 中共用的多宿主编排工具包。
+**Agent + Orchestra** — 面向 Claude Code、Codex CLI、Gemini CLI 和本地模型的多宿主 MCP 编排工具包。
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra 将 Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入 Claude Code，通过 44 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证和基于质量的提供方路由。
+Agestra 将 Claude host/CLI、Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入，通过 45 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证，以及可选参考 trace 证据的能力型提供方路由。
 
 ## 快速开始
 
-### Claude Code
+先选择你要使用的宿主。需要安装宿主原生命令/代理时使用 `--assets` 路径；只需要服务器连接时使用 MCP-only 注册。
 
-```
-/plugin marketplace add mua-vtuber/Agestra
-/plugin install agestra@agestra
-```
-
-Claude 保持现有插件安装体验不变。Agestra 会在首次使用时通过 `environment_check` 自动检测可用的提供方（Claude host、Ollama、Gemini CLI、Codex CLI）。
+| 宿主 | 从本仓库安装 | 从全局 npm 安装 | `--assets` 会添加 |
+|------|--------------|----------------|-------------------|
+| Claude Code | `/plugin marketplace add mua-vtuber/Agestra` 后执行 `/plugin install agestra@agestra` | 同样的插件流程 | 插件包、命令、代理、hooks 和 MCP server |
+| Codex CLI | `npm run bundle` 后执行 `npm run install:codex:assets` | `npm install -g agestra` 后执行 `agestra-install codex --assets` | `.codex/agents/` 下的生成 custom agents |
+| Gemini CLI | `npm run bundle` 后执行 `npm run install:gemini:assets` | `npm install -g agestra` 后执行 `agestra-install gemini --assets --scope user` | project scope 的受管文件，或 user scope 的 native `agestra` Gemini extension |
 
-### Codex CLI
+也可以只注册 MCP:
 
-```
-npm run bundle
-npm run install:codex:assets
-```
-
-使用全局 npm 包时：
-
-```
-npm install -g agestra
-agestra-install codex --assets
-```
+| 宿主 | 仓库包 | 从 checkout 注册全局包 |
+|------|--------|------------------------|
+| Codex CLI | `npm run install:codex` | `npm run install:codex:global` |
+| Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` |
 
-Codex 会结合仓库根目录下的 [AGENTS.md](AGENTS.md) 与已注册的 `agestra` MCP 服务一起工作。生成 Codex custom agent 需要使用 `--assets` 路径，它会在 `.codex/agents/` 下安装 agent，并写入 Agestra host-asset manifest。不安装 custom agent、只注册 MCP 时，请使用 `npm run install:codex` 或 `agestra-install codex`。
-
-### Gemini CLI
-
-```
-npm run bundle
-npm run install:gemini:assets
-```
-
-使用全局 npm 包时：
-
-```
-npm install -g agestra
-agestra-install gemini --assets --scope user
-```
+Claude 保持原生插件 UX。Codex 会结合 [AGENTS.md](AGENTS.md)、生成的 custom agents 和已注册的 `agestra` MCP server。Gemini 会结合 [GEMINI.md](GEMINI.md)、`.gemini/commands/agestra/`、生成的 skills，以及 project-scope 受管文件或 user-scope native extension。
 
-Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/commands/agestra/`](.gemini/commands/agestra) 和生成的 skills 一起工作。project scope 的 `--assets` 会写入受管文件，user scope 的 `--assets` 会安装 Agestra Gemini native extension。只注册 MCP 时，请使用 `npm run install:gemini` 或 `agestra-install gemini`。`npm run install:gemini:assets` 默认使用 user scope；如果要从 checkout 安装 project-scope 受管文件，请运行 `node scripts/install-host-mcp.mjs gemini --assets --scope project`。
+注意：`npm run install:gemini:assets` 默认使用 user scope。如果要从 checkout 安装 project-scope Gemini 受管文件，请运行 `node scripts/install-host-mcp.mjs gemini --assets --scope project`。
 
-安装后可用的 Gemini 命令：
+Assets 安装后可用的 Gemini 命令：
 
 - `/agestra:setup`
 - `/agestra:review`
@@ -68,12 +46,26 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 | 提供方 | 安装 | 类型 |
 |--------|------|------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `npm install -g @anthropic-ai/claude-code` | Cloud |
 | [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | Local LLM |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud |
 | [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | Cloud |
 
+每个 CLI 都自行管理其认证。请在使用前通过对应 CLI 自身的登录流程完成认证 — Agestra 仅作为子进程启动这些 CLI，不会处理其认证信息。
+
 可选但推荐：
 - **tmux** — 让你在自主执行期间可视化查看 CLI Worker 面板
+- **Windows 上的 ripgrep (`rg`)** — 如果 Codex 解析到 Store app bundled path 的 `rg` 并出现 "Access is denied"，请单独安装 ripgrep，让正常的 `rg.exe` 在 `PATH` 中优先被找到：
+
+```
+cargo install ripgrep
+```
+
+替代方式：
+
+```
+winget install BurntSushi.ripgrep.MSVC
+```
 
 ---
 
@@ -81,6 +73,52 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 **Multi-AI 的目标是验证，而不是节省 token。** 代码审查、设计探索和想法生成工作流都被设计成验证流程，核心不是为了更快并行，而是让多个 AI 提供方独立给出意见，从而发现盲点。
 
+## 工作方式
+
+```mermaid
+flowchart TD
+    Start([用户调用 /agestra 命令]) --> Preflight[设置状态 / 环境 / 提供方检查]
+    Preflight --> Domain{工作流类型}
+
+    Domain -->|想法 / 设计 / 审查 / 安全| TextLead[负责人组建专家代理和外部 AI]
+    Domain -->|QA| QaLead[负责人组建 QA Brigade]
+    Domain -->|实现| ImplLead[负责人拆分实现任务]
+
+    ImplLead --> ImplRoute{任务形态}
+    ImplRoute -->|清晰可并行的实现| CliWorkers[Codex / Gemini CLI Worker<br/>隔离 worktree 中实现]
+    ImplRoute -->|能力匹配的有范围任务| Ollama[本地 / 工具模型<br/>策略允许时可读 / 写]
+    ImplRoute -->|高风险或核心改动| HostImpl[宿主实现代理<br/>负责人近距离监督]
+    CliWorkers --> ReviewDiff[负责人监控状态 / 用量 / diff]
+    Ollama --> ReviewDiff
+    HostImpl --> ReviewDiff
+    ReviewDiff --> Merge{可接受?}
+    Merge -->|否| Reassign[修正指令或重新分配]
+    Reassign --> ImplRoute
+    Merge -->|是| QaEvidence
+
+    QaLead --> QaEvidence[宿主 QA 收集可执行证据<br/>构建 / 测试 / E2E / 截图]
+    TextLead --> Providers{有外部 AI?}
+    QaEvidence --> Providers
+
+    Providers -->|无| LocalOut[宿主专家代理生成<br/>领域报告或文档]
+    Providers -->|有| Individual[各 AI 编写独立意见]
+    LocalOut --> Final([向用户报告结果])
+
+    Individual --> Ledger[ITEM-* JSON 共识台账]
+    Ledger --> Round[顺序轮次<br/>同意 / 反对 / 修订 / 意见]
+    Round --> Gate{台账状态}
+    Gate -->|需要继续讨论| Round
+    Gate -->|需要负责人判断| LeaderDecision[负责人选择继续 / 批准 / 拒绝]
+    Gate -->|已整理| LeaderDecision
+    LeaderDecision -->|继续| Round
+    LeaderDecision -->|批准| Approved[批准版综合文档]
+    LeaderDecision -->|拒绝| Rejected[拒绝 / 未解决综合文档]
+    Approved --> Final
+    Rejected --> Final
+```
+
+当未配置任何外部提供方时，Agestra 会跳过共识轮次，由宿主专家代理生成对应领域产物，例如 review/QA 报告、设计文档或想法记录。只要进入结构化辩论，负责人无论批准还是拒绝都会留下综合文档；拒绝文档会整理已接受、已排除以及仍未解决/需要意见的项目。
+
 ## 各宿主的自然入口
 
 | 宿主 | 自然入口 |
@@ -101,15 +139,15 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 | `/agestra security [target]` | 执行专门的安全审查 |
 | `/agestra idea [topic]` | 通过与相似项目对比发掘改进点 |
 | `/agestra design [subject]` | 在实现前探索架构与设计取舍 |
-| `/agestra implement [task]` | 以 Claude only 或 Multi-AI 模式执行实现 |
+| `/agestra implement [task]` | 以领导者宿主单独模式或 Multi-AI 分发模式执行实现 |
 
-当外部提供方可用时，review、QA、security、design、idea 工作流会经由 team-lead 进入多 AI 交叉验证。当未检测到提供方时，当前宿主的本地 specialist agent 会自动处理。
+当外部提供方可用时，review、QA、security、design、idea 工作流会经由 team-lead 进入多 AI 交叉验证。对于 QA，team-lead 默认会从已配置的提供方集合中组建 QA Brigade，然后交给 moderator engine 现有的 `ITEM-*` / JSON stance ledger：宿主 QA 收集可执行证据，提供方承担不同验证视角，候选 finding 在纳入前会被挑战，综合文档会保留共识与异议。E2E/browser/runtime 执行仍归宿主所有，外部提供方会审查这些证据。当未检测到提供方时，当前宿主的本地 specialist agent 会自动处理。实现请求会先分类任务，并可询问是否提出 AI 任务分配方案。
 
 ## 代理
 
 | 代理 | 模型 | 角色 |
 |------|------|------|
-| `agestra-team-lead` | Sonnet | 全局编排者：环境检查、按质量路由提供方、选择工作模式、监督 CLI Worker、驱动 QA 循环 |
+| `agestra-team-lead` | Sonnet | 全局编排者：环境检查、能力型提供方路由、选择工作模式、监督 CLI Worker、驱动 QA 循环 |
 | `agestra-implementer` | Sonnet | 有范围的实现执行者：代码修改、测试更新、本地验证 |
 | `agestra-e2e-writer` | Sonnet | 持久 E2E 测试作者：只编写已批准的浏览器流程测试 |
 | `agestra-reviewer` | Opus | 严格质量审查者：关注安全、孤立实现、规格漂移、测试缺口 |
@@ -145,13 +183,14 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 | 包 | 说明 |
 |----|------|
-| `@agestra/core` | `AIProvider` 接口、基于难度的路由注册表、配置加载、CLI runner、原子写入、任务队列、密钥扫描、worktree 管理、任务清单、CLI Worker 管理器 |
+| `@agestra/core` | `AIProvider` 接口、带能力/难度元数据的 provider descriptor、配置加载、CLI runner、原子写入、任务队列、密钥扫描、worktree 管理、任务清单、CLI Worker 管理器 |
+| `@agestra/provider-claude` | Anthropic Claude CLI 适配器 |
 | `@agestra/provider-ollama` | 带模型检测的 Ollama HTTP 适配器 |
 | `@agestra/provider-gemini` | Google Gemini CLI 适配器 |
 | `@agestra/provider-codex` | OpenAI Codex CLI 适配器 |
 | `@agestra/agents` | 带共识检测的辩论引擎、轮次质量评估、任务分发、交叉验证、任务链、自动 QA、文件变更跟踪、会话管理 |
 | `@agestra/workspace` | 用于评审、分析笔记和汇总报告的工作区文档管理器 |
-| `@agestra/mcp-server` | MCP 协议层，44 个工具，按环境过滤工具并动态分发 |
+| `@agestra/mcp-server` | MCP 协议层，45 个工具，按环境过滤工具并动态分发 |
 
 ### 设计原则
 
@@ -165,37 +204,40 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 ### 工作模式
 
-**文本工作**（review、QA、security、design、idea）：有提供方 → 终极辩论模式；无提供方 → Claude only
+在多提供方模式（终极辩论、交叉验证、复审轮次）中，一个提供方的输出可能成为下一个提供方所收到提示词的一部分。
+
+**文本工作**（review、QA、security、design、idea）：有提供方 → 结构化辩论；无提供方 → 负责人宿主的专家代理
 
 **实现工作**（team-lead orchestration）：
-- **仅 Claude** — Claude 直接结合项目/全局代理完成实现。
-- **与其他 AI 一起** — CLI Worker（Codex/Gemini）在隔离的 git worktree 中自主编码，Ollama 处理简单任务，Claude 负责监督与合并。
+- **仅负责人宿主** — 当前宿主的 `agestra-implementer` 执行有范围的代码修改。除非明确要求 host-only，QA 仍可根据已配置提供方使用 QA Brigade。
+- **建议式 AI 分工** — 负责人先提出任务分配表并取得批准，然后根据检测到的模型能力分配工作，包括 frontier 模型和本地模型。Codex/Gemini CLI Worker 处理适合的自主代码修改，本地/工具模型可根据 `executionPolicy` 获得只读或读写 AgentLoop 工具。负责人持续监督状态、用量和 diff，并负责合并。
 
 ---
 
-## 工具（44）
+## 工具（45）
 
 ### AI Chat（3）
 
 | 工具 | 说明 |
 |------|------|
-| `ai_chat` | 与指定提供方对话（使用 `"auto"` 可启用基于质量的路由）；如有需要，可通过 `save_as_document` 将回复保存为文档 |
+| `ai_chat` | 与指定提供方对话（有观测记录时可用 `"auto"` 启用 trace 辅助路由）；如有需要，可通过 `save_as_document` 将回复保存为文档 |
 | `ai_analyze_files` | 从磁盘读取文件并连同问题一起发送给提供方 |
 | `ai_compare` | 将同一提示发送给多个提供方并比较结果 |
 
-### Agent Orchestration（14）
+### Agent Orchestration（15）
 
 | 工具 | 说明 |
 |------|------|
 | `agent_debate_start` | 启动多提供方辩论（非阻塞，可选质量循环 + 验证者） |
-| `agent_debate_status` | 查看辩论状态与转录 |
+| `agent_debate_status` | 查看 legacy 辩论或结构化会话的进度、phase、参与者活动和文档路径 |
 | `agent_debate_create` | 创建回合制辩论会话（返回 debate ID） |
 | `agent_debate_turn` | 执行某个提供方的一回合；支持 `provider: "claude"` 让 Claude 独立参与 |
 | `agent_debate_conclude` | 结束辩论并生成最终转录 |
-| `agent_debate_structured` | 启动带审批闸门的结构化辩论：进行独立审查、可选别名整理、带投票聚合的多轮推进，合成在批准前不写入，会话停留在 `ready-for-approval` |
-| `agent_debate_approve` | 领导者批准 `ready-for-approval` 会话；写入合成文档并结束会话 |
+| `agent_debate_structured` | 启动带审批闸门的结构化辩论：进行独立审查、可选别名整理和 JSON 共识轮次；负责人批准或拒绝前不会写入综合文档 |
+| `agent_debate_approve` | 负责人批准 `ready-for-approval` 会话；写入批准版综合文档并结束会话 |
 | `agent_debate_continue` | 对 `ready-for-approval`（或 `escalated`）会话追加轮次（3/5/10） |
-| `agent_debate_reject` | 拒绝结构化辩论会话，不写入合成 |
+| `agent_debate_reject` | 拒绝结构化辩论会话；写入拒绝版综合文档，并可按需写入 issue 文档 |
+| `agent_debate_submit_turn` | 当结构化辩论状态报告 `phase: awaiting-host-turn` 时提交原生宿主专家 turn；所有待处理宿主 turn 到齐后工作流会自动继续 |
 | `agent_debate_review` | 将文档发送给多个提供方进行独立审查 |
 | `agent_cross_validate` | 对输出进行交叉验证（仅限 agent-tier validators） |
 | `agent_changes_review` | 审查隔离任务中的文件变更 |
@@ -215,7 +257,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 | 工具 | 说明 |
 |------|------|
-| `environment_check` | 检测 CLI 工具、带分层信息的 Ollama 模型、tmux、git worktree 支持与可用模式 |
+| `environment_check` | 检测 CLI 工具、本地模型分层、tmux、git worktree 支持与可用模式 |
 
 ### Workspace（7）
 
@@ -267,16 +309,16 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 ### QA（1）
 
-| Tool | Description |
-|------|-------------|
+| 工具 | 说明 |
+|------|------|
 | `qa_run` | 自动检测 build/test 命令并运行 QA，输出 PASS/FAIL 摘要 |
 
 ### Trace / Observability（3）
 
-| Tool | Description |
-|------|-------------|
+| 工具 | 说明 |
+|------|------|
 | `trace_query` | 按条件查询 trace 记录（提供方、任务、时间范围） |
-| `trace_summary` | 获取各提供方的质量统计、性能指标和难度资格 |
+| `trace_summary` | 获取各提供方可选的历史质量观测值和性能指标 |
 | `trace_visualize` | 生成某次追踪操作流程的 Mermaid 图 |
 
 ---
@@ -285,7 +327,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 ### providers.config.json
 
-由 `/agestra setup` 生成。文件存放于单一的插件范围位置（解析顺序：`AGESTRA_CONFIG_PATH` 环境变量 → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`）。不随仓库一起提交，已加入 gitignore。
+由 `/agestra setup` 生成。默认保存位置是宿主共享的 `~/.agestra/providers.config.json`。解析顺序为 `AGESTRA_CONFIG_PATH` 环境变量 → 已存在的 `~/.agestra/providers.config.json` → 已存在的 legacy `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 用于新写入的 `~/.agestra/providers.config.json`。它不应放在项目仓库中，并已加入 gitignore。
 
 | 字段 | 说明 |
 |------|------|
@@ -294,7 +336,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 | `providers[].id` | 唯一标识符 |
 | `providers[].type` | `ollama`、`gemini-cli`、`codex-cli`、`claude-cli` |
 | `providers[].enabled` | 启动时是否注册 — `false` 为强制跳过 |
-| `providers[].executionPolicy` | `read-only` 或 `workspace-write` |
+| `providers[].executionPolicy` | `read-only`、`workspace-write` 或 `full-auto`；Ollama 根据该值选择只读或读写 AgentLoop 工具 |
 | `providers[].config` | 类型相关配置（host、timeout 等） |
 
 ### 运行时数据
@@ -385,12 +427,13 @@ agestra/
 │   └── uninstall-host-mcp.mjs # 移除宿主注册和受管理资产
 ├── packages/
 │   ├── core/                # AIProvider 接口、注册表、安全、worker
+│   ├── provider-claude/     # Anthropic Claude CLI 适配器
 │   ├── provider-ollama/     # Ollama HTTP 适配器
 │   ├── provider-gemini/     # Gemini CLI 适配器
 │   ├── provider-codex/      # Codex CLI 适配器
 │   ├── agents/              # 辩论引擎、分发器、交叉验证器
 │   ├── workspace/           # 工作区文档管理器
-│   └── mcp-server/          # MCP Server，44 个工具，按环境过滤并分发
+│   └── mcp-server/          # MCP Server，45 个工具，按环境过滤并分发
 ├── package.json             # 工作区根目录
 └── turbo.json               # Turborepo pipeline
 ```

package/agents/agestra-moderator.md

@@ -97,7 +97,7 @@ Do not ask `agestra-e2e-writer` to change product behavior. Product fixes belong
 
 ### Mode: Structured Debate
 
-**Preferred entry point:** Call `agent_debate_structured` with `mode`, topic, scope, participants, optional `source_documents`, and leader. Use `mode: "review"` for code/document review and `mode: "idea"` for idea/design option discovery. `source_documents` is optional and must use `{ "document_id": "...", "provider": "..." }` entries when independent documents already exist. The tool creates a structured session record immediately and returns `status: running`; use `agent_debate_status` to monitor phase, provider progress, item summary, and document paths. The moderator engine owns the full lifecycle: individual/source material loading, JSON consensus ledger creation, optional alias clarification, sequential provider turns, strict JSON response validation, generated debate markdown, structured session record, and final synthesis after leader approval.
+**Preferred entry point:** Call `agent_debate_structured` with `mode`, topic, scope, participants, optional `source_documents`, and leader. Use `mode: "review"` for code/document review and `mode: "idea"` for idea/design option discovery. `source_documents` is optional and must use `{ "document_id": "...", "provider": "..." }` entries when independent documents already exist. The tool creates a structured session record immediately and returns `status: running`; use `agent_debate_status` to monitor phase, provider progress, item summary, and document paths. The moderator engine owns the full lifecycle: individual/source material loading, JSON consensus ledger creation, optional alias clarification, sequential provider turns, strict JSON response validation, generated debate markdown, structured session record, and final synthesis after leader approval or rejection.
 
 The JSON consensus ledger is the source of truth. Debate markdown and synthesis markdown are generated human-readable artifacts. The moderator may inspect and report their paths, but must not edit markdown to change item status, provider stance, or consensus state.
 
@@ -161,9 +161,9 @@ The engine persists the JSON ledger atomically, then regenerates:
 
 The moderator does not write the final synthesis file on its own. Three dedicated MCP tools close out the flow:
 
-- `agent_debate_approve`: writes the synthesis markdown, updates ledger document paths, and transitions to `approved`.
+- `agent_debate_approve`: writes the approved synthesis markdown, updates ledger document paths, and transitions to `approved`.
 - `agent_debate_continue`: loads the persisted ledger/session record, starts additional consensus rounds in the background, and returns `running`.
-- `agent_debate_reject`: closes without synthesis. With `spawn_issue = true`, an issue document can be written under `individual/` listing non-accepted items.
+- `agent_debate_reject`: writes the rejected synthesis markdown, updates ledger document paths, and transitions to `rejected`. With `spawn_issue = true`, an additional issue document can be written under `individual/` listing non-accepted items.
 
 Idempotency: a second call on a terminal state (`approved`, `rejected`, `leader-timeout`) returns the cached outcome. Calling approval-gate tools on a `running` or `error` session returns `isError: true` with a descriptive state message.
 
@@ -206,7 +206,7 @@ All paths relative to `workspaceBaseDir` (`.agestra/workspace/` under the projec
 .agestra/workspace/
   individual/   — each participant's initial independent review (pre-debate; no votes)
   debates/      — generated debate markdown + {sessionId}.consensus.json + {sessionId}.session.json
-  synthesis/    — leader-approved final synthesis document (written only on _approve)
+  synthesis/    — leader-finalized synthesis document (written on _approve or _reject)
   reviews/      — legacy, read-only; no new writes
 ```
 
@@ -224,7 +224,7 @@ The moderator's terminal report and the synthesis document are derived from the
 - **Excluded items** - items where all active participants disagreed.
 - **Open items** - items that need opinion, have no response, or remain unresolved.
 - **AI Contribution Summary** - per participant: proposed items, accepted items, revisions, opinions, and non-responses.
-- **Footer** - debate markdown path, consensus JSON path, and synthesis path when approved.
+- **Footer** - debate markdown path, consensus JSON path, and synthesis path when finalized.
 
 Severity labels are lifted from the proposer's individual review verbatim. The moderator does **not** translate participant-authored item titles, comments, or individual-review bodies.
 
@@ -503,10 +503,10 @@ If `max_rounds` is hit with open proposals, the moderator surfaces the choice to
 
 <Tool_Usage>
 - `provider_list` — check available providers at the start.
-- `agent_debate_structured` — **recommended entry point for Structured Debate**: accepts `mode: "review" | "idea"` and optional `source_documents`, starts or loads individual source material, runs optional alias clarification, JSON consensus turns, ledger persistence, generated debate markdown, and the approval gate in the background. Returns `running`; poll `agent_debate_status`. Does NOT write synthesis.
-- `agent_debate_approve` — write synthesis markdown, mark the snapshot `approved`, close the session.
+- `agent_debate_structured` — **recommended entry point for Structured Debate**: accepts `mode: "review" | "idea"` and optional `source_documents`, starts or loads individual source material, runs optional alias clarification, JSON consensus turns, ledger persistence, generated debate markdown, and the approval gate in the background. Returns `running`; poll `agent_debate_status`. Does NOT write synthesis until the leader approves or rejects.
+- `agent_debate_approve` — write approved synthesis markdown, mark the snapshot `approved`, close the session.
 - `agent_debate_continue` — force additional rounds on a `ready-for-approval` or `escalated` session; returns `running`, then poll status.
-- `agent_debate_reject` — close without synthesis; optionally spawn an issue branch listing non-accepted proposals.
+- `agent_debate_reject` — write rejected synthesis markdown, mark the snapshot `rejected`, close the session; optionally spawn an issue branch listing non-accepted proposals.
 - Legacy manual debate primitives — diagnostic use only; do not use them for review, idea, or design consensus workflows.
 - `agent_debate_review` — send a document to providers for structured review (Document Review mode).
 - `ai_chat` — query individual providers for feedback (Independent Aggregation mode).