agestra 4.13.3 → 4.13.4

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）。
-
-### Codex CLI
-
-```
-npm run bundle
-npm run install:codex:assets
-```
+| 宿主 | 从本仓库安装 | 从全局 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 |
 
-使用全局 npm 包时：
-
-```
-npm install -g agestra
-agestra-install codex --assets
-```
-
-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
-```
+也可以只注册 MCP:
 
-使用全局 npm 包时：
+| 宿主 | 仓库包 | 从 checkout 注册全局包 |
+|------|--------|------------------------|
+| Codex CLI | `npm run install:codex` | `npm run install:codex:global` |
+| Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` |
 
-```
-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,6 +46,7 @@ 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 |
@@ -76,6 +55,17 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 可选但推荐：
 - **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
+```
 
 ---
 
@@ -96,7 +86,7 @@ flowchart TD
 
     ImplLead --> ImplRoute{任务形态}
     ImplRoute -->|清晰可并行的实现| CliWorkers[Codex / Gemini CLI Worker<br/>隔离 worktree 中实现]
-    ImplRoute -->|简单或重复的辅助任务| Ollama[Ollama 等本地 AI<br/>草稿 / 补丁候选 / 重复建议]
+    ImplRoute -->|能力匹配的有范围任务| Ollama[本地 / 工具模型<br/>策略允许时可读 / 写]
     ImplRoute -->|高风险或核心改动| HostImpl[宿主实现代理<br/>负责人近距离监督]
     CliWorkers --> ReviewDiff[负责人监控状态 / 用量 / diff]
     Ollama --> ReviewDiff
@@ -149,15 +139,15 @@ flowchart TD
 | `/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 | 严格质量审查者：关注安全、孤立实现、规格漂移、测试缺口 |
@@ -193,13 +183,14 @@ flowchart TD
 
 | 包 | 说明 |
 |----|------|
-| `@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 个工具，按环境过滤工具并动态分发 |
 
 ### 设计原则
 
@@ -219,26 +210,26 @@ flowchart TD
 
 **实现工作**（team-lead orchestration）：
 - **仅负责人宿主** — 当前宿主的 `agestra-implementer` 执行有范围的代码修改。除非明确要求 host-only，QA 仍可根据已配置提供方使用 QA Brigade。
-- **建议式 AI 分工** — 负责人先提出任务分配表并取得批准，然后让 Codex/Gemini CLI Worker 在隔离 worktree 中处理清晰的实现任务；Ollama 用于简单、重复任务的草稿或补丁候选。负责人持续监督状态、用量和 diff，并负责合并。
+- **建议式 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` | 结束辩论并生成最终转录 |
@@ -246,6 +237,7 @@ flowchart TD
 | `agent_debate_approve` | 负责人批准 `ready-for-approval` 会话；写入批准版综合文档并结束会话 |
 | `agent_debate_continue` | 对 `ready-for-approval`（或 `escalated`）会话追加轮次（3/5/10） |
 | `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` | 审查隔离任务中的文件变更 |
@@ -265,7 +257,7 @@ flowchart TD
 
 | 工具 | 说明 |
 |------|------|
-| `environment_check` | 检测 CLI 工具、带分层信息的 Ollama 模型、tmux、git worktree 支持与可用模式 |
+| `environment_check` | 检测 CLI 工具、本地模型分层、tmux、git worktree 支持与可用模式 |
 
 ### Workspace（7）
 
@@ -317,16 +309,16 @@ flowchart TD
 
 ### 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 图 |
 
 ---
@@ -335,7 +327,7 @@ flowchart TD
 
 ### 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。
 
 | 字段 | 说明 |
 |------|------|
@@ -344,7 +336,7 @@ flowchart TD
 | `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 等） |
 
 ### 运行时数据
@@ -435,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-team-lead.md

@@ -130,19 +130,19 @@ Before executing, gather context:
 
 1. Call `environment_check` to get the full capability map:
    - Which CLI tools are installed (codex, gemini, tmux)
-   - Which Ollama models are available and their tier classifications
+   - Which frontier and local models are available, including Ollama model tiers when present
    - Whether autonomous work is possible (CLI workers + git worktree)
    - Available modes: leader-host-only (`claude_only` or `leader_only` from legacy environment output), independent, debate, team
 2. Call `provider_list` for provider availability.
-3. Call `trace_summary` to get provider quality scores and difficulty qualifications.
-   - Review each provider's overall average quality score
-   - Note which difficulty levels each provider qualifies for (low/medium/high)
-   - Providers with no quality data are treated as new (low difficulty only)
+3. Call `trace_summary` to check whether prior provider quality observations exist.
+   - Treat trace quality as optional evidence, not guaranteed knowledge.
+   - If present, use it as a tie-breaker between otherwise suitable providers.
+   - If absent, do not invent quality history; route by detected model capability, task risk, and execution policy.
 4. Read existing design documents in `docs/plans/`.
 5. Store environment capabilities for later mode selection:
    - `can_autonomous_work`: CLI workers available?
    - `available_providers`: which are online?
-   - `ollama_tiers`: model size classifications
+   - `model_capabilities`: detected frontier/local model capability and tier classifications
 6. In autonomous mode: show the design document to the user but do NOT wait for approval.
 
 ### Phase 2: Task Design
@@ -156,7 +156,7 @@ Decompose the work into independent, assignable tasks:
    | Option | Description |
    |--------|-------------|
    | **Leader-host only** | The current host uses `agestra-implementer` and specialist agents/prompts; no external coding workers. QA routing still follows the configured-provider default unless host-only QA is requested |
-   | **Multi-AI** | CLI AIs work autonomously when suitable, Ollama handles simple proposal work, host-local agents handle scoped implementation/review/QA |
+   | **Multi-AI** | Work is distributed according to detected model capability, including frontier and local models. CLI AIs work autonomously when suitable, local/tool models may handle scoped read/write work when their execution policy allows it, and host-local agents handle implementation/review/QA that should stay on the leader host |
 
    If no external providers available: skip selection, proceed with Leader-host only.
    In autonomous mode: auto-select based on task complexity:
@@ -195,14 +195,14 @@ Decompose the work into independent, assignable tasks:
 
    | Task Characteristics | Route To |
    |---------------------|----------|
-   | Complex implementation, multi-step reasoning | MCP: `cli_worker_spawn` (Codex/Gemini) |
-   | Simple transforms, formatting, repeated pattern application | MCP: `ai_chat` (Ollama, tier-matched model) for a patch plan or candidate diff; `agestra-implementer` applies it unless an edit-capable safe worker exists |
+   | Complex implementation, multi-step reasoning | High-capability detected model, usually MCP: `cli_worker_spawn` (Codex/Gemini) or host-local `agestra-implementer` |
+   | Simple transforms, formatting, repeated pattern application | Capability-matched local/tool model through MCP: `ai_chat` when available. With `workspace-write` / `full-auto`, it may apply scoped file edits through AgentLoop tools; with `read-only`, it returns a patch plan or candidate diff for `agestra-implementer` to apply |
    | Core implementation, design-sensitive changes | `agestra-implementer` or a high-capability CLI worker |
    | Product/unit/integration test writing | `agestra-implementer` or a high-capability CLI worker |
    | Persistent E2E test writing | `agestra-e2e-writer` after user approval |
    | Review and QA | `agestra-reviewer` or `agestra-qa` |
 
-   **Quality-Based Provider Selection:**
+   **Capability-First Provider Selection:**
 
    Before assigning any task, determine its difficulty level:
    - **low**: Simple chat, basic formatting, straightforward review
@@ -210,11 +210,11 @@ Decompose the work into independent, assignable tasks:
    - **high**: Complex architecture, cross-validation, multi-component refactoring
 
    Then filter providers by qualification:
-   1. Check `trace_summary` output for each provider's difficulty qualification
-   2. Only assign a task to a provider that qualifies for its difficulty level
-   3. Among qualified providers, prefer the one with the highest task-specific quality score
-   4. If no provider qualifies, fall back to `agestra-implementer` for the task
-   5. New providers (no quality data) start at low difficulty — assign simple tasks first to build their track record
+   1. Check detected model capability, provider type, execution policy, and task risk.
+   2. Only assign a task to a provider whose detected capability qualifies for its difficulty level.
+   3. If `trace_summary` has relevant quality data, use it as a tie-breaker between otherwise qualified providers.
+   4. If no provider qualifies, fall back to `agestra-implementer` for the task.
+   5. Providers with no trace data are unknown, not bad; start them on lower-risk, tightly scoped assignments until evidence accumulates.
 
 4. Define dependency relationships between tasks.
 
@@ -247,9 +247,12 @@ Execute approved tasks across available execution paths:
    - Otherwise → re-route to a different provider or complete the task through `agestra-implementer`.
 5. On worker TIMEOUT: worker transitions to FAILED, follow failure handling above.
 
-**Ollama tasks (MCP):**
-- Call `ai_chat` with tier-matched model for simple tasks.
-- Apply the result manually through `agestra-implementer` after inspection.
+**Local/tool-model tasks (MCP `ai_chat`, currently Ollama-backed):**
+- Distribute work according to detected model capability, including frontier and local models. Call `ai_chat` with a capability-matched local/tool model for scoped tasks when available.
+- Respect the provider's `executionPolicy` from `provider_list` / setup config:
+  - `read-only` → the model receives read/search tools only and must return analysis, a patch plan, or a candidate diff.
+  - `workspace-write` / `full-auto` → the model may receive read/write AgentLoop tools and can make scoped workspace edits.
+- After any write-enabled local/tool-model task, inspect the git diff before proceeding. If the diff exceeds the assigned files, touches risky surfaces, or looks incomplete, route correction to `agestra-implementer` or a higher-capability CLI worker.
 
 **Result Integration:**
 - Leader-host implementation: changes are already applied on the main branch (no merge needed).
@@ -351,12 +354,59 @@ Build the QA Brigade handoff before starting the moderator debate:
 | `agestra-e2e-writer` | Not a brigade reviewer. Use only after an approved `E2E_TEST_WORK_REQUEST` for persistent E2E test work |
 
 Default participant policy:
-- Include every configured and available review-capable provider by default, not only the "best" one. Use `trace_summary` to assign lenses and order attention, not to shrink the brigade unless a provider is unavailable, explicitly excluded, or clearly unqualified for the requested lens.
-- Exclude `ollama` by default unless the user explicitly requested it for lightweight cross-checking.
+- Include every configured and available review-capable provider by default, not only the "best" one. Use `trace_summary`, when populated, to assign lenses and order attention, not to shrink the brigade unless a provider is unavailable, explicitly excluded, or clearly unqualified for the requested lens.
+- Include configured providers when their detected model capability qualifies for the assigned QA lens; use trace quality only as optional supporting evidence, and use read-only debate tools for QA/review so they do not modify source files during verification.
 - Keep the host QA participant in the flow even when external providers are present, because executable evidence, E2E/runtime observation, and local command output are host-owned. In structured debate, this is the `claude-qa` compatibility participant when auto-injected or explicitly listed.
 - Assign distinct lenses so the output is not three copies of the same review. Suggested lenses: spec-to-code compliance, progress-table truthfulness, integration/regression risk, edge/error states, test adequacy, safety hygiene, and E2E artifact interpretation.
 - Each brigade member must issue an independent PASS / CONDITIONAL PASS / FAIL recommendation with evidence and confidence in its individual source material. Disagreement is useful; preserve minority reports in the final synthesis.
 
+Scale and reliability controls:
+- For whole-project, large-directory, or deep review/QA requests, create a bounded evidence packet before provider fan-out. Include changed files, key entry points, build/test evidence, relevant configs/docs, and explicit out-of-scope areas; do not expect every external CLI provider to discover a large repository from scratch inside one turn.
+- Use `participant_timeout_ms` of at least `600000` for broad or deep structured debates, and raise it further only when the user accepts the wait. If participants still time out, split the task by subsystem and run multiple narrower debates.
+- If Gemini reports a workspace trust issue, treat it as provider unavailable for that run, tell the user the project must be trusted in Gemini CLI, and continue with the remaining participants or retry after trust is fixed. Do not count trust failures as review disagreement.
+
+#### 5M.0b Host specialist pre-injection (REQUIRED on Claude-Code host)
+
+> Why this exists: the structured-debate engine cannot ask the Claude-Code host to call its own native subagents back through MCP — that would invert the dependency direction. Instead, when the leader host wants Claude specialist input (`claude-reviewer` / `claude-qa` / `claude-security`) inside a multi-AI debate, the leader runs the native subagent **before** starting the debate and supplies the result as a `source_documents` entry. The moderator engine then loads that document as the specialist's individual review and excludes the specialist from subsequent consensus rounds. External providers still fan out and debate normally. This is the Phase B routing contract; do not bypass it.
+>
+> When this applies: ANY structured debate (QA Brigade, multi-AI review, multi-AI security) on Claude-Code host that wants Claude specialist participation. If you only have external providers and no Claude specialist lens, skip this subsection entirely.
+
+Procedure (run before `agent_debate_structured`):
+
+1. Decide which Claude specialists belong in the brigade — typically `agestra-qa` for QA Brigade, `agestra-reviewer` for multi-AI review, `agestra-security` for multi-AI security. You may include more than one (e.g., QA Brigade may also pull in `agestra-reviewer` as a supporting lens).
+2. For each chosen specialist, invoke it via the `Agent` tool with the same scope/files/design references the external providers will see. Wait for the result.
+3. Persist each specialist result as a workspace document via `workspace_create_document` (kind: `individual`). Capture the returned `document_id`.
+4. Build the `agent_debate_structured` arguments so they self-describe the pre-injection:
+   - `participants`: include the matching Claude specialist IDs (`claude-reviewer`, `claude-qa`, `claude-security`) alongside the external providers. The schema requires the `provider` field of every `source_documents` entry to be present in `participants`.
+   - `source_documents`: one entry per specialist — `{ "document_id": "<id from workspace_create_document>", "provider": "claude-reviewer" | "claude-qa" | "claude-security" }`.
+   - `auto_inject_specialists`: `false`. You already added the specialists manually; auto-inject would duplicate.
+5. Start the debate. The moderator will load each pre-injected document as the specialist's individual review, parse its `<proposals>` block into ledger items, and skip that specialist in every consensus round. External providers fan out and debate as usual; they may vote on specialist-proposed items.
+
+Round-loop note (Phase C — host-turn handoff): pre-injected specialists still skip consensus rounds. Specialists that were NOT pre-injected (e.g. you let `auto_inject_specialists: true` add a Claude reviewer mid-debate, or you intentionally listed `claude-reviewer` in `participants` *without* a matching `source_documents` entry) now participate every round through the host-turn handoff protocol described in 5M.0c. Use 5M.0b when you only need a single up-front specialist read; use 5M.0c on top of it when you also want round-by-round specialist stances.
+
+Multi-host note: on hosts that do not have a Claude specialist surface (Codex, Gemini, Ollama-only configurations), do not synthesize fake specialist documents. Either run the debate without Claude specialists or ask the user to add a host that exposes them.
+
+#### 5M.0c Round-time specialist host-turn handoff (Phase C)
+
+> Why this exists: when a Claude specialist participates in consensus rounds (rather than only contributing an upfront review), the moderator engine cannot call back into the host's native subagent. The engine instead parks the round, advertises the pending request through the persisted snapshot, and waits for the leader to dispatch the subagent and post the result. This keeps the dependency direction MCP-compliant on every host.
+
+When this engages: any structured debate where a Claude specialist (`claude-reviewer` / `claude-qa` / `claude-security`) is in `participants`, the leader host is Claude-Code, and the participant is NOT covered by a `source_documents` entry. The engine activates the handoff per round — independently of 5M.0b pre-injection.
+
+Polling loop (run alongside the existing 5M.2 polling):
+
+1. Call `agent_debate_status` until the snapshot reports `phase: awaiting-host-turn`. The structured response then carries a `pending_host_turns[]` array with one entry per specialist that owes a turn this round. Each entry exposes `participant_id`, `agent_name` (e.g. `agestra-reviewer`), `round`, `prompt`, optional `system_prompt`, optional `files`, and `requested_at`.
+2. For every entry, invoke the matching native subagent via the `Agent` tool with `subagent_type: <agent_name>`. Pass the entry's `prompt` verbatim — do not paraphrase, do not strip the JSON contract. Forward `files` if listed. The subagent must return its `<consensus_turn>` JSON exactly the way an external provider would.
+3. Post the verbatim subagent text back via `agent_debate_submit_turn` with `{ session_id, participant_id, content: <subagent text>, round }`. The tool acknowledges with the count of remaining pending turns.
+4. After every pending entry is submitted, the moderator round resumes automatically. The next `agent_debate_status` poll will report `phase: consensus-round` (or the next gate), and the round transcript will list the specialist's stance just like an external provider's.
+
+Failure handling:
+- Submit each specialist's response separately. If the subagent fails or refuses, do NOT submit a fabricated turn; let the gate time out so the moderator records the missing vote with `failureReason: "host-turn timeout"`. Re-running the specialist and submitting the next round is allowed.
+- Round-mismatched submissions (`round` not equal to the pending entry's round) are rejected; align on the latest snapshot before re-trying.
+- Duplicate submissions for the same participant in the same gate are rejected. If you need to revise a stance, wait for the next round.
+- The handoff timeout defaults to `STRUCTURED_DEBATE_HOST_TURN_TIMEOUT_MS` (20 minutes). Tests override it through engine deps; production debates inherit the default.
+
+Multi-host note: this handoff path is only meaningful when the leader host can natively invoke the specialist subagents (Claude-Code today). Other hosts continue to rely on 5M.0b pre-injection or omit the specialists entirely.
+
 #### 5M.0a QA mapping onto the existing JSON ledger
 
 Do not invent a separate QA adjudication schema. Use the moderator's existing structured-debate contract.
@@ -388,12 +438,13 @@ Call `agent_debate_structured` with:
 - `topic` — short slug (used in file names under `.agestra/workspace/`), prefixed or framed as QA Brigade when useful.
 - `mode` — `"review"` for QA/review/security consensus, `"idea"` for exploratory design or option discovery.
 - `scope` — concrete framing: file list, task description, design doc path, changed files, and host QA report/evidence path.
-- `participants` — the provider/agent IDs the user specified, or all configured and available review-capable providers from `provider_list`, plus the host QA participant (`claude-qa` compatibility ID) through auto-injection or explicit listing. For QA, use `trace_summary` for lens assignment rather than narrowing by default. Exclude `ollama` unless explicitly requested for lightweight cross-checking.
-- `source_documents` — optional pre-created individual documents, each as `{ "document_id": "...", "provider": "..." }`. For QA, pass the host QA report/evidence packet as source material for the matching host QA participant. The `provider` value must be present in `participants`.
-- `auto_inject_specialists` — default `true`. When true, the moderator auto-adds host reviewer/QA/security specialists on top of `participants` based on topic heuristics (currently exposed as `claude-reviewer`, `claude-qa`, and/or `claude-security` for compatibility). When the user wants verbatim participants only, pass `false`.
+- `participants` — the provider/agent IDs the user specified, or all configured and available review-capable providers from `provider_list`, plus the host QA participant (`claude-qa` compatibility ID) through auto-injection or explicit listing. For QA, use detected model capabilities for lens assignment; use `trace_summary` only when it has relevant observations.
+- `source_documents` — pre-created individual documents, each as `{ "document_id": "...", "provider": "..." }`. **Required** when the brigade includes Claude specialists on Claude-Code host (see 5M.0b — host runs the native subagent first, persists the result, and supplies it here). The `provider` value must be present in `participants`. For QA, also pass the host QA report/evidence packet as source material for the matching host QA participant. Pre-injected providers skip the individual fan-out AND every consensus round.
+- `auto_inject_specialists` — default `true` only when the leader has not pre-injected specialists. **Pass `false` whenever you supply specialist `source_documents`**, otherwise the moderator may add a duplicate specialist participant on top of the one you already injected. When the user wants verbatim participants only, also pass `false`.
 - `exclude_participants` — participant IDs to never include, applied regardless of `auto_inject_specialists`. Use this when the user explicitly wants a provider (including Ollama — there is no automatic Ollama filter anymore) kept out.
 - `leader` — omit unless you need to override the session-context leader.
 - `max_rounds` — default `10`. Raise for contested topics, lower for quick smoke-debates.
+- `participant_timeout_ms` — omit for normal scoped reviews; set at least `600000` for whole-project, large-directory, deep review, or provider timeouts.
 - `individual_review_prompt` / `files` — optional framing for the individual-review fan-out.
 - `locale` — pass the locale resolved from `agestra.config.json` (fall back to providers.config locale). The moderator uses it for human-facing text; provider prompts remain English regardless.
 
@@ -479,7 +530,7 @@ When transitioning between workflow phases, create a handoff document summarizin
 
 Phase 2→3 Handoff:
 - Work mode selected (Leader-host only / Multi-AI)
-- Total tasks, host-implementer task count, CLI workers count, proposal-only provider task count
+- Total tasks, host-implementer task count, CLI worker count, local/tool-model AgentLoop task count with read-only vs write-enabled policy
 - Task dependency graph
 - Risk flags (shared files, complex tasks)
 - Context for workers (design doc path, Implementation Progress rows, naming conventions, key decisions)
@@ -505,8 +556,8 @@ Bad: "Add a validation function to the user module"
 Good: "In `packages/core/src/user.ts`, add a `validateEmail(email: string): boolean` function that follows the same pattern as `validateUsername` on line 42. Must handle empty strings, return false for invalid format. Export from `packages/core/src/index.ts`. Do NOT modify existing functions."
 </Prompt_Crafting>
 
-<Ollama_Routing>
-When routing tasks to Ollama, check model size via `ollama_models` first:
+<Model_Capability_Routing>
+Distribute work according to the capabilities of detected models, including frontier and local models. For local Ollama models, check model size via `ollama_models` first:
 
 | Model Size | Suitable Tasks |
 |---|---|
@@ -515,8 +566,12 @@ When routing tasks to Ollama, check model size via `ollama_models` first:
 | 8-20 GB (~7-14B params) | Code generation, detailed analysis, multi-step reasoning |
 | > 20 GB (~14B+ params) | Complex refactoring, architecture analysis |
 
-Do NOT assign tasks beyond a model's capability. When in doubt, use a cloud provider instead.
-</Ollama_Routing>
+Do NOT assign tasks beyond a detected model's capability. When in doubt, use a higher-capability frontier provider or host-local specialist instead.
+
+For implementation tasks, also check the provider execution policy:
+- `read-only`: assign only reading, searching, analysis, review, patch-plan, or candidate-diff work.
+- `workspace-write` / `full-auto`: the model has the same workspace write permission class as other write-enabled providers. Keep tasks scoped to explicit files and inspect the resulting diff before continuing.
+</Model_Capability_Routing>
 
 <Principles>
 
@@ -556,7 +611,7 @@ The design document is the authority. If an AI's output conflicts with the desig
 ## MCP (External AI & Infrastructure)
 - `environment_check` — detect CLI tools, Ollama models, infrastructure
 - `provider_list` / `provider_health` — check external AI availability
-- `trace_query` / `trace_summary` / `trace_visualize` — provider quality tracking and inspection
+- `trace_query` / `trace_summary` / `trace_visualize` — optional provider quality observations from prior recorded runs
 - `ai_chat` / `ai_analyze_files` / `ai_compare` — query external AI
 - `agent_debate_structured` — start a structured multi-AI debate in the background (individual/source material → clarification → JSON consensus rounds → aggregation → approval gate). It returns `status: running`; poll `agent_debate_status`. Supports `mode: "review" | "idea"`, optional `source_documents`, `auto_inject_specialists` (default `true`) to auto-add host reviewer/QA/security specialists (compatibility IDs: `claude-reviewer` / `claude-qa` / `claude-security`) based on topic, and `exclude_participants` as the escape hatch (also the way to keep Ollama or any other provider out — there is no automatic Ollama filter).
 - `agent_debate_approve` / `agent_debate_continue` / `agent_debate_reject` — leader-only finalization tools for a structured session at the approval gate. `approve` writes an approved synthesis under `.agestra/workspace/synthesis/`; `continue(additional_rounds=N)` accepts only `3`, `5`, or `10` and returns `running`; `reject(reason=..., spawn_issue?=true)` writes a rejected synthesis and can also write a follow-up issue document.
@@ -598,7 +653,7 @@ Spawning a Codex CLI worker to refactor the auth module in an isolated worktree.
 <Constraints>
 - Do NOT write, edit, or create files. Delegate all implementation.
 - Do NOT skip the user approval step before executing tasks (in supervised mode).
-- Do NOT assign complex tasks to small Ollama models.
+- Do NOT assign complex tasks to models whose detected capability does not qualify, including small local models.
 - Do NOT accept "simplified" or "partial" results from AIs.
 - Do NOT proceed to QA until you've inspected all results yourself.
 - Use MCP tools for external AI orchestration and change review.

package/commands/design.md

@@ -97,7 +97,7 @@ Team-lead owns the rest:
 - Spawn `agestra:agestra-moderator` or `agestra:agestra-designer` directly when external providers are involved
 - Build individual documents or hand-edit generated debate/synthesis Markdown
 
-Direct execution from this command bypasses team-lead's quality-based routing (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B.
+Direct execution from this command bypasses team-lead's capability-based routing and optional trace-assisted signals (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B.
 
 ## Step 3: Present the result
 

package/commands/idea.md

@@ -87,7 +87,7 @@ Team-lead owns the rest:
 
 Writing the final project-facing idea decision record under `docs/ideas/` is allowed and expected after the user chooses or approves ideas. `.agestra/workspace/` is the internal research/debate workspace, not the user's primary browsing surface.
 
-Direct execution bypasses team-lead's quality-based routing and consistency enforcement. Always go through team-lead in Branch B.
+Direct execution bypasses team-lead's capability-based routing, optional trace-assisted signals, and consistency enforcement. Always go through team-lead in Branch B.
 
 ## Step 3: Present to the user
 

package/commands/implement.md

@@ -51,10 +51,11 @@ Use AskUserQuestion to present the recommended routing in the user's language, o
 If team mode is not available, skip the question and use Leader-host only.
 
 Routing guidance:
-- Simple and repetitive, low-risk work → prefer Ollama for analysis or patch suggestions, then `agestra-implementer` applies the change. Do not assume Ollama can edit files autonomously.
-- Complex or multi-file implementation → prefer Codex/Gemini CLI workers in isolated worktrees.
+- Distribute work according to detected model capability, including frontier and local models. Use model tier, task risk, and execution policy first; use trace quality data only when it exists.
+- Simple and repetitive, low-risk work → prefer a capability-matched local/tool model when available. If its `executionPolicy` is `workspace-write` or `full-auto`, it may use AgentLoop read/write tools through `ai_chat`; if it is `read-only`, use it for analysis, patch plans, or candidate diffs only.
+- Complex or multi-file implementation → prefer high-capability frontier/CLI workers such as Codex/Gemini in isolated worktrees, or the host implementer when that is safer.
 - Small but risky work → prefer `agestra-implementer` or a high-capability CLI worker, with QA/review after.
-- If trace quality data exists, use it to pick between qualified providers. If no trace data exists, treat providers as unproven and start with lower-risk assignments.
+- If trace quality data exists, use it only as a tie-breaker between otherwise qualified providers. If no trace data exists, do not invent quality history; start with lower-risk, tightly scoped assignments.
 
 ## Step 4: Ensure there is a design basis
 
@@ -106,7 +107,7 @@ Team-lead owns the rest:
 **Multi-AI mode:**
 - Presents task-to-provider routing table for approval
 - Dispatches CLI workers (`cli_worker_spawn`) for suitable Codex/Gemini tasks in isolated worktrees
-- Uses Ollama only for proposal-quality work via `ai_chat`
+- Uses capability-matched local/tool models through `ai_chat` with tools selected from their `executionPolicy`: read-only policies get read/search tools, while `workspace-write` / `full-auto` policies may perform scoped file writes.
 - Reviews changes with `agent_changes_review` before merge
 - Runs Phase 5M structured QA debate (cross-validation across providers)
 

package/commands/qa.md

@@ -69,8 +69,9 @@ Hand off to `agestra:agestra-team-lead` with:
 - **E2E/runtime execution:** host-owned only; external providers cross-validate artifacts and findings, not browser/dev-server execution
 - **Design doc reference:** path under `docs/plans/`
 - **Report artifact path expectation:** `docs/reports/qa/YYYY-MM-DD-qa-[target].md`
-- **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight cross-checking
+- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only QA/review tools so verification cannot modify source files
 - **Requested providers:** explicit names captured from user wording; otherwise "all configured and available review-capable providers"
+- **Specialist pre-injection (Claude-Code host):** when the brigade should include `claude-qa` (and optionally `claude-reviewer` / `claude-security` as supporting lenses), team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run the host specialist (`agestra-qa` etc.) via the `Agent` tool first, persist each result through `workspace_create_document`, then pass them as `source_documents` entries with `auto_inject_specialists: false`. The pre-injected host QA report itself doubles as the evidence packet for the matching `claude-qa` participant. Do NOT rely on `auto_inject_specialists: true` when a Claude specialist participant is wanted
 - **Brigade lenses:** host executable evidence, spec-to-code compliance, implementation progress truthfulness, integration/regression risk, edge/error states, test adequacy, basic safety hygiene, and E2E artifact review when E2E ran
 - **JSON finding flow:** candidate findings become `ITEM-*` ledger items; participants use the existing `agree` / `disagree` / `opinion` / `revise` stance contract; only ledger-accepted items affect the final verdict
 - **Locale:** from `setup_status`

package/commands/review.md

@@ -82,8 +82,10 @@ Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selec
 - **Depth/tone/audience:** selected or inferred values
 - **Boundary:** this is critique/evaluation, not QA PASS/FAIL and not a deep security audit
 - **Report artifact path expectation:** `docs/reports/review/YYYY-MM-DD-review-[target].md`
-- **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight commentary
+- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only review tools for code/document critique
 - **Requested providers:** explicit names captured from user wording; otherwise "all available review-capable"
+- **Specialist pre-injection (Claude-Code host):** when the brigade should include the `claude-reviewer` specialist lens, team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run `agestra-reviewer` via the `Agent` tool first, persist the result through `workspace_create_document`, then pass it as a `source_documents` entry with `auto_inject_specialists: false`. Do NOT rely on `auto_inject_specialists: true` when a Claude specialist participant is wanted — the structured-debate engine cannot call back into the Claude-Code host's native subagents
+- **Scale controls:** if the target is a whole project, a large directory, or deep review, instruct team-lead to create a bounded review packet before fan-out: changed files, key entry points, relevant docs/config, and explicit exclusions. Do not ask external CLI providers to explore an unbounded large repository from scratch. Use `participant_timeout_ms: 600000` or higher for large/deep reviews, and split the review into narrower area debates if providers still time out.
 - **Locale:** from `setup_status`
 - **Original user request:** preserve verbatim
 
@@ -99,7 +101,7 @@ Team-lead owns the rest:
 - Spawn `agestra:agestra-moderator` or `agestra:agestra-reviewer` directly when external providers are involved
 - Build individual documents or hand-edit generated debate/synthesis Markdown
 
-Direct execution from this command bypasses team-lead's task design, quality-based routing (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B.
+Direct execution from this command bypasses team-lead's task design, capability-based routing with optional trace-assisted signals (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B.
 
 ## Step 4: Present the final result
 

package/commands/security.md

@@ -59,8 +59,9 @@ Hand off to `agestra:agestra-team-lead` with:
 - **Risk surfaces:** explicit user selections or inferred surfaces
 - **Tool permission choices:** approved / declined / not asked, with exact approved commands if any
 - **Report artifact path expectation:** `docs/reports/security/YYYY-MM-DD-security-[target].md`
-- **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight commentary
+- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only security-review tools unless the user explicitly approves a separate implementation task
 - **Requested providers:** explicit names captured from user wording; otherwise "all available security-capable"
+- **Specialist pre-injection (Claude-Code host):** when the brigade should include the `claude-security` specialist lens, team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run `agestra-security` via the `Agent` tool first, persist the result through `workspace_create_document`, then pass it as a `source_documents` entry with `auto_inject_specialists: false`. The structured-debate engine cannot call back into the Claude-Code host's native subagents, so `auto_inject_specialists: true` is unsafe whenever a Claude specialist participant is wanted
 - **Locale:** from `setup_status`
 - **Original user request:** preserve verbatim