agestra 4.12.4 → 4.12.5

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "agestra",
       "source": "./",
       "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
-      "version": "4.12.4",
+      "version": "4.12.5",
       "author": {
         "name": "mua-vtuber"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agestra",
-  "version": "4.12.4",
+  "version": "4.12.5",
   "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
   "mcpServers": {
     "agestra": {

package/AGENTS.md

@@ -5,13 +5,17 @@ This repository includes a Codex-friendly host wrapper for Agestra.
 ## First Run
 
 1. Build the bundled MCP server if needed: `npm run bundle`
-2. Register Agestra with Codex once per machine: `npm run install:codex`
+2. Register Agestra with Codex and install generated custom agents: `npm run install:codex:assets`
 3. Open this repository in Codex. This `AGENTS.md` file is loaded automatically.
 
+Use `npm run install:codex` only when you intentionally want MCP registration without generated `.codex/agents/*.toml` assets.
+Low-level MCP calls do not silently write setup. High-level Agestra workflows must call `setup_status` first; if it reports `Setup required: yes`, run the interactive setup questions immediately, call `setup_apply` after the user chooses providers/locale, then resume the original workflow.
+Use `host_assets_status` to inspect generated host assets, and only call `host_assets_install` after the user agrees to install or refresh Codex custom agents.
+
 ## How to Work Here
 
 - Treat `commands/*.md` as the source of truth for Agestra workflows.
-- When the user asks for review, design, idea, or implementation help, start with `environment_check` and `provider_list`.
+- When the user asks for review, design, idea, or implementation help, start with `setup_status`, `environment_check`, and `provider_list`. If `setup_status` reports `Setup required: yes`, complete interactive setup first and then resume the original workflow.
 - Prefer Agestra MCP tools over ad-hoc multi-provider prompting.
 - If any legacy workflow text mentions "Claude only", interpret that as the current leader-host-only path when Claude is not the active host.
 
@@ -27,6 +31,7 @@ This repository includes a Codex-friendly host wrapper for Agestra.
 - `environment_check` and `provider_list`: inspect host/provider state first
 - `agent_debate_structured` (with `agent_debate_approve`/`_continue`/`_reject`) and `agent_debate_review`: run approval-gated multi-provider review flows
 - `cli_worker_spawn`, `agent_changes_review`, `agent_changes_accept`, `agent_changes_reject`: use for autonomous Codex/Gemini worker tasks
+- `host_assets_status`, `host_assets_install`, `host_assets_uninstall`: inspect and explicitly manage generated host-native assets such as Codex custom agents
 - `qa_run`: run workspace build/test verification before reporting implementation completion
 
 ## Project Assets

package/README.ja.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra は Ollama（ローカル）、Gemini CLI、Codex CLI を Claude Code にプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、品質ベースのプロバイダー選択を 25 個の MCP ツールで提供します。
+Agestra は Ollama（ローカル）、Gemini CLI、Codex CLI を Claude Code にプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、品質ベースのプロバイダー選択を 44 個の MCP ツールで提供します。
 
 ## クイックスタート
 
@@ -34,7 +34,7 @@ npm install -g agestra
 agestra-install codex --assets
 ```
 
-Codex ではリポジトリ直下の [AGENTS.md](AGENTS.md) と、登録済みの `agestra` MCP サーバーを一緒に使います。`--assets` は `.codex/agents/` に生成済み Codex custom agent もインストールし、Agestra host-asset manifest に記録します。MCP 登録だけでよい場合は `npm run install:codex` または `agestra-install codex` を使ってください。
+Codex ではリポジトリ直下の [AGENTS.md](AGENTS.md) と、登録済みの `agestra` MCP サーバーを一緒に使います。生成済み Codex custom agent には `--assets` が必要で、`.codex/agents/` にインストールして Agestra host-asset manifest に記録します。custom agent なしで MCP 登録だけでよい場合は `npm run install:codex` または `agestra-install codex` を使ってください。
 
 ### Gemini CLI
 
@@ -141,7 +141,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 | `@agestra/provider-codex` | OpenAI Codex CLI アダプター |
 | `@agestra/agents` | 合意検出付きディベートエンジン、ターン品質評価、タスク配分、クロスバリデーション、タスクチェーン、自動 QA、ファイル変更追跡、セッション管理 |
 | `@agestra/workspace` | レビュー、分析メモ、統合レポート向けのワークスペース文書マネージャー |
-| `@agestra/mcp-server` | MCP プロトコル層、25 ツール、環境依存のツールフィルタリング、ディスパッチ |
+| `@agestra/mcp-server` | MCP プロトコル層、44 ツール、環境依存のツールフィルタリング、ディスパッチ |
 
 ### 設計原則
 
@@ -163,7 +163,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 ---
 
-## ツール (25)
+## ツール (44)
 
 ### AI チャット (3)
 
@@ -173,7 +173,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 | `ai_analyze_files` | ディスク上のファイルを読み込み、質問と一緒にプロバイダーへ送信 |
 | `ai_compare` | 同じプロンプトを複数プロバイダーに送り、応答を比較 |
 
-### エージェントオーケストレーション (0)
+### エージェントオーケストレーション (14)
 
 | ツール | 説明 |
 |--------|------|
@@ -226,6 +226,21 @@ Turborepo モノレポで、8 パッケージ構成です:
 | `provider_list` | 状態と機能付きでプロバイダー一覧を表示 |
 | `provider_health` | 1 つまたはすべてのプロバイダーのヘルスチェック |
 
+### セットアップ (2)
+
+| ツール | 説明 |
+|--------|------|
+| `setup_status` | 利用可能なプロバイダーと現在の設定状態を確認 |
+| `setup_apply` | 選択したプロバイダー、ロケール、選択ポリシーを `providers.config.json` に書き込む |
+
+### ホストアセット (3)
+
+| ツール | 説明 |
+|--------|------|
+| `host_assets_status` | Codex custom agents などの生成済みホストネイティブアセットを確認 |
+| `host_assets_install` | 管理対象のホストネイティブアセットを明示的にインストールまたは更新 |
+| `host_assets_uninstall` | Agestra が追跡する管理対象ホストネイティブアセットを削除 |
+
 ### Ollama (2)
 
 | ツール | 説明 |
@@ -353,7 +368,7 @@ agestra/
 │   ├── provider-codex/      # Codex CLI アダプター
 │   ├── agents/              # ディベートエンジン、ディスパッチ、クロスバリデーション
 │   ├── workspace/           # ワークスペース文書マネージャー
-│   └── mcp-server/          # MCP サーバー、25 ツール、環境依存フィルタリング、ディスパッチ
+│   └── mcp-server/          # MCP サーバー、44 ツール、環境依存フィルタリング、ディスパッチ
 ├── package.json             # ワークスペースルート
 └── turbo.json               # Turborepo パイプライン
 ```

package/README.ko.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra는 Claude 호스트, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅을 25개 MCP 도구로 제공합니다.
+Agestra는 Claude 호스트, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅을 44개 MCP 도구로 제공합니다.
 
 ## 빠른 시작
 
@@ -42,7 +42,7 @@ agestra-install codex --assets
 npm run install:codex:global
 ```
 
-Codex는 저장소 루트의 [AGENTS.md](AGENTS.md)와 등록된 `agestra` MCP 서버를 함께 사용합니다. `--assets` 경로는 `.codex/agents/` 아래에 생성형 Codex custom agent도 설치하고 Agestra host-asset manifest에 기록합니다. MCP만 등록하려면 `npm run install:codex` 또는 `agestra-install codex`를 사용하세요.
+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
 
@@ -168,7 +168,7 @@ Turborepo 모노레포, 8개 패키지:
 | `@agestra/provider-codex` | OpenAI Codex CLI 어댑터 |
 | `@agestra/agents` | 합의 검출 토론 엔진, 턴 품질 평가기, 작업 분배기, 교차 검증기, 작업 체인, 자동 QA, 파일 변경 추적기, 세션 관리자 |
 | `@agestra/workspace` | 리뷰, 분석 메모, 통합 보고서를 위한 워크스페이스 문서 관리자 |
-| `@agestra/mcp-server` | MCP 프로토콜 레이어, 25개 도구, 환경별 도구 필터링, 디스패치 |
+| `@agestra/mcp-server` | MCP 프로토콜 레이어, 44개 도구, 환경별 도구 필터링, 디스패치 |
 
 ### 설계 원칙
 
@@ -190,7 +190,7 @@ Turborepo 모노레포, 8개 패키지:
 
 ---
 
-## 도구 (25개)
+## 도구 (44개)
 
 ### AI 채팅 (3개)
 
@@ -200,7 +200,7 @@ Turborepo 모노레포, 8개 패키지:
 | `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 |
 | `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 |
 
-### 에이전트 오케스트레이션 (0개)
+### 에이전트 오케스트레이션 (14개)
 
 | 도구 | 설명 |
 |------|------|
@@ -253,6 +253,21 @@ Turborepo 모노레포, 8개 패키지:
 | `provider_list` | 공급자 목록 (상태, 능력 포함) |
 | `provider_health` | 공급자 상태 체크 |
 
+### 설정 (2개)
+
+| 도구 | 설명 |
+|------|------|
+| `setup_status` | 사용 가능한 공급자와 현재 설정/구성 상태 확인 |
+| `setup_apply` | 선택한 공급자, 언어, 선택 정책을 `providers.config.json`에 기록 |
+
+### 호스트 자산 (3개)
+
+| 도구 | 설명 |
+|------|------|
+| `host_assets_status` | Codex custom agents 같은 생성된 호스트 네이티브 자산 상태 확인 |
+| `host_assets_install` | 관리되는 호스트 네이티브 자산을 명시적으로 설치 또는 갱신 |
+| `host_assets_uninstall` | Agestra가 추적하는 관리형 호스트 네이티브 자산 제거 |
+
 ### Ollama (2개)
 
 | 도구 | 설명 |
@@ -381,7 +396,7 @@ agestra/
 │   ├── provider-codex/      # Codex CLI 어댑터
 │   ├── agents/              # 토론 엔진, 분배기, 교차 검증기
 │   ├── workspace/           # 워크스페이스 문서 관리자
-│   └── mcp-server/          # MCP 서버, 25개 도구, 환경별 필터링, 디스패치
+│   └── mcp-server/          # MCP 서버, 44개 도구, 환경별 필터링, 디스패치
 ├── package.json             # 워크스페이스 루트
 └── turbo.json               # Turborepo 파이프라인
 ```

package/README.md

@@ -7,7 +7,7 @@
 
 [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 25 MCP tools.
+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.
 
 ## Quick Start
 
@@ -42,7 +42,7 @@ If you want MCP-only registration of the global package while working from a rep
 npm run install:codex:global
 ```
 
-Codex uses the repository-level [AGENTS.md](AGENTS.md) instructions plus the registered `agestra` MCP server. The `--assets` path also installs generated Codex custom agents under `.codex/agents/` and tracks them in the Agestra host-asset manifest. For MCP-only registration, use `npm run install:codex` or `agestra-install codex`.
+Codex uses the repository-level [AGENTS.md](AGENTS.md) instructions plus the registered `agestra` MCP server. The `--assets` path is required for generated Codex custom agents; it installs them under `.codex/agents/` and tracks them in the Agestra host-asset manifest. For MCP-only registration without custom agents, use `npm run install:codex` or `agestra-install codex`.
 
 ### Gemini CLI
 
@@ -169,7 +169,7 @@ Turborepo monorepo with 8 packages:
 | `@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, 25 tools, environment-aware tool filtering, dispatch |
+| `@agestra/mcp-server` | MCP protocol layer, 44 tools, environment-aware tool filtering, dispatch |
 
 ### Design Principles
 
@@ -191,7 +191,7 @@ Turborepo monorepo with 8 packages:
 
 ---
 
-## Tools (25)
+## Tools (44)
 
 ### AI Chat (3)
 
@@ -201,7 +201,7 @@ Turborepo monorepo with 8 packages:
 | `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 (0)
+### Agent Orchestration (14)
 
 | Tool | Description |
 |------|-------------|
@@ -254,6 +254,21 @@ Turborepo monorepo with 8 packages:
 | `provider_list` | List providers with status and capabilities |
 | `provider_health` | Health check one or all providers |
 
+### Setup (2)
+
+| Tool | Description |
+|------|-------------|
+| `setup_status` | Detect available providers and show the current setup/config state |
+| `setup_apply` | Write selected providers, locale, and selection policy to `providers.config.json` |
+
+### Host Assets (3)
+
+| Tool | Description |
+|------|-------------|
+| `host_assets_status` | Check generated host-native assets such as Codex custom agents |
+| `host_assets_install` | Explicitly install or refresh managed host-native assets |
+| `host_assets_uninstall` | Remove managed host-native assets tracked by Agestra |
+
 ### Ollama (2)
 
 | Tool | Description |
@@ -383,7 +398,7 @@ agestra/
 │   ├── provider-codex/      # Codex CLI adapter
 │   ├── agents/              # Debate engine, dispatcher, cross-validator
 │   ├── workspace/           # Workspace document manager
-│   └── mcp-server/          # MCP server, 25 tools, environment-aware filtering, dispatch
+│   └── mcp-server/          # MCP server, 44 tools, environment-aware filtering, dispatch
 ├── package.json             # Workspace root
 └── turbo.json               # Turborepo pipeline
 ```

package/README.zh.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra 将 Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入 Claude Code，通过 25 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证和基于质量的提供方路由。
+Agestra 将 Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入 Claude Code，通过 44 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证和基于质量的提供方路由。
 
 ## 快速开始
 
@@ -34,7 +34,7 @@ npm install -g agestra
 agestra-install codex --assets
 ```
 
-Codex 会结合仓库根目录下的 [AGENTS.md](AGENTS.md) 与已注册的 `agestra` MCP 服务一起工作。`--assets` 还会在 `.codex/agents/` 下安装生成的 Codex custom agent，并写入 Agestra host-asset manifest。只注册 MCP 时，请使用 `npm run install:codex` 或 `agestra-install codex`。
+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
 
@@ -141,7 +141,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 | `@agestra/provider-codex` | OpenAI Codex CLI 适配器 |
 | `@agestra/agents` | 带共识检测的辩论引擎、轮次质量评估、任务分发、交叉验证、任务链、自动 QA、文件变更跟踪、会话管理 |
 | `@agestra/workspace` | 用于评审、分析笔记和汇总报告的工作区文档管理器 |
-| `@agestra/mcp-server` | MCP 协议层，25 个工具，按环境过滤工具并动态分发 |
+| `@agestra/mcp-server` | MCP 协议层，44 个工具，按环境过滤工具并动态分发 |
 
 ### 设计原则
 
@@ -163,7 +163,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 
 ---
 
-## 工具（25）
+## 工具（44）
 
 ### AI Chat（3）
 
@@ -173,7 +173,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 | `ai_analyze_files` | 从磁盘读取文件并连同问题一起发送给提供方 |
 | `ai_compare` | 将同一提示发送给多个提供方并比较结果 |
 
-### Agent Orchestration（0）
+### Agent Orchestration（14）
 
 | 工具 | 说明 |
 |------|------|
@@ -226,6 +226,21 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 | `provider_list` | 列出提供方及其状态和能力 |
 | `provider_health` | 对一个或全部提供方进行健康检查 |
 
+### Setup（2）
+
+| 工具 | 说明 |
+|------|------|
+| `setup_status` | 检测可用提供方并显示当前设置/配置状态 |
+| `setup_apply` | 将选择的提供方、语言和选择策略写入 `providers.config.json` |
+
+### Host Assets（3）
+
+| 工具 | 说明 |
+|------|------|
+| `host_assets_status` | 检查 Codex custom agents 等生成的宿主原生资产 |
+| `host_assets_install` | 显式安装或刷新受管宿主原生资产 |
+| `host_assets_uninstall` | 移除 Agestra 追踪的受管宿主原生资产 |
+
 ### Ollama（2）
 
 | 工具 | 说明 |
@@ -353,7 +368,7 @@ agestra/
 │   ├── provider-codex/      # Codex CLI 适配器
 │   ├── agents/              # 辩论引擎、分发器、交叉验证器
 │   ├── workspace/           # 工作区文档管理器
-│   └── mcp-server/          # MCP Server，25 个工具，按环境过滤并分发
+│   └── mcp-server/          # MCP Server，44 个工具，按环境过滤并分发
 ├── package.json             # 工作区根目录
 └── turbo.json               # Turborepo pipeline
 ```

package/agents/agestra-designer.md

@@ -1,28 +1,41 @@
 ---
 name: agestra-designer
 description: |
-  Pre-implementation design explorer using Socratic questioning. Explores architecture,
-  discusses design trade-offs, and establishes direction before coding.
+  Host-local pre-implementation design explorer using Socratic questioning. Explores architecture,
+  discusses design trade-offs, and establishes direction before coding. Single-host scope only —
+  does NOT orchestrate external providers (Codex/Gemini/Ollama). For multi-AI design debates or
+  consensus design with external providers, route through agestra-team-lead or agestra-moderator
+  (mode: "idea") instead.
 
   <example>
-  Context: User needs to plan architecture before implementing
+  Context: User needs to plan architecture before implementing (single-host)
   user: "이 기능 어떻게 설계하면 좋을까?"
   assistant: "I'll use the agestra-designer agent to explore architecture approaches."
   <commentary>
-  User wants design exploration before coding — designer asks clarifying questions and proposes approaches.
+  Single-host design exploration — designer asks clarifying questions and proposes approaches without external providers.
   </commentary>
   </example>
 
   <example>
-  Context: User is comparing implementation approaches
+  Context: User is comparing implementation approaches (single-host)
   user: "REST vs GraphQL, 어떤 방향으로 가야할지 고민이야"
   assistant: "I'll use the agestra-designer agent to analyze trade-offs between the approaches."
   <commentary>
-  Design trade-off discussion — designer explores pros/cons of each approach.
+  Single-host design trade-off discussion — designer explores pros/cons. If user wanted multi-AI input, route to team-lead instead.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User explicitly asks for multi-AI design input — DO NOT use this agent directly
+  user: "코덱스랑 제미니 의견도 받아서 설계 결정하자"
+  assistant: "I'll use the agestra-team-lead agent to orchestrate a multi-AI design consensus."
+  <commentary>
+  Multi-AI design — must go through team-lead (which can dispatch to designer + external providers via structured debate). Do NOT call agestra-designer directly here.
   </commentary>
   </example>
 model: opus
 color: blue
+codexSandboxMode: workspace-write
 disallowedTools: Edit, NotebookEdit
 ---
 

package/agents/agestra-ideator.md

@@ -1,28 +1,40 @@
 ---
 name: agestra-ideator
 description: |
-  Discover improvements, compare with similar projects, collect user feedback, explore new features,
-  or research what to build. Use for competitive analysis, gap discovery, and idea generation.
+  Host-local idea & improvement discoverer. Compares with similar projects, collects user feedback,
+  explores new features, researches what to build. Single-host scope — does NOT orchestrate external
+  providers (Codex/Gemini/Ollama). For multi-AI idea consensus or competitive brainstorming with
+  external providers, route through agestra-team-lead or agestra-moderator (mode: "idea") instead.
 
   <example>
-  Context: User wants to find improvements for their project
+  Context: User wants to find improvements for their project (single-host research)
   user: "이 프로젝트에 뭐 추가하면 좋을까?"
   assistant: "I'll use the agestra-ideator agent to research improvements and feature ideas."
   <commentary>
-  User seeking feature ideas — ideator researches competitors, user complaints, and gaps.
+  Single-host research — ideator does the web research and analysis alone.
   </commentary>
   </example>
 
   <example>
-  Context: User exploring whether a new project is viable
+  Context: User exploring whether a new project is viable (single-host research)
   user: "이거 만들 가치가 있을까? 비슷한 도구가 있나?"
   assistant: "I'll use the agestra-ideator agent to research the landscape and assess viability."
   <commentary>
-  New project validation — ideator compares with existing tools and identifies gaps.
+  Single-host viability research — ideator compares with existing tools alone.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants multi-AI idea brainstorming — DO NOT use this agent directly
+  user: "코덱스 제미니 같이 의견 모아서 뭐 만들지 정하자"
+  assistant: "I'll use the agestra-team-lead agent to orchestrate a multi-AI idea consensus."
+  <commentary>
+  Multi-AI idea generation — must go through team-lead which can run structured debate (mode:idea) with external providers. Do NOT call agestra-ideator directly here.
   </commentary>
   </example>
 model: sonnet
 color: green
+codexSandboxMode: read-only
 disallowedTools: Edit, NotebookEdit
 ---
 

package/agents/agestra-implementer.md

@@ -1,20 +1,31 @@
 ---
 name: agestra-implementer
 description: |
-  Implementation executor. Applies scoped code changes, writes or updates tests,
+  Host-local implementation executor. Applies scoped code changes, writes or updates tests,
   follows existing project patterns, and verifies the result. Receives tasks from
-  the team lead; does not orchestrate other providers.
+  agestra-team-lead; does not orchestrate other providers and does not run debates or QA.
+  For multi-AI implementation (Codex/Gemini/Ollama workers), route through agestra-team-lead.
 
   <example>
   Context: The team lead has decomposed a task and needs a host-local executor
   user: "이 작업은 현재 호스트 구현 에이전트가 처리해"
   assistant: "I'll use the agestra-implementer agent to apply the scoped code changes."
   <commentary>
-  Implementation executor — modifies code within the assigned files and verifies.
+  Single-host implementation executor — modifies code within the assigned files and verifies.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants multi-AI implementation — DO NOT use this agent directly
+  user: "코덱스로 이 부분 구현하고 제미니로 검증해줘"
+  assistant: "I'll use the agestra-team-lead agent to orchestrate multi-AI implementation."
+  <commentary>
+  Multi-AI implementation with external providers — must go through team-lead which spawns CLI workers and coordinates results. Do NOT call agestra-implementer directly here.
   </commentary>
   </example>
 model: sonnet
 color: green
+codexSandboxMode: workspace-write
 ---
 
 <Role>

package/agents/agestra-moderator.md

@@ -1,16 +1,25 @@
 ---
 name: agestra-moderator
 description: |
-  Multi-AI discussion facilitator and result aggregator. Manages turn-based debates,
-  independent result aggregation, document review rounds, and merge conflict resolution.
-  Neutral — does not inject domain opinions, only facilitates.
+  Multi-AI discussion facilitator and result aggregator. Manages structured turn-based debates with
+  JSON consensus ledger, independent result aggregation, document review rounds, and merge conflict
+  resolution. Neutral — does not inject domain opinions, only facilitates. The right entry point when
+  the work is purely facilitation/aggregation rather than full lifecycle orchestration (use
+  agestra-team-lead for end-to-end multi-AI development).
+
+  ROUTING — invoke this agent (not the host-local specialists) for:
+  - Explicit debate/discussion requests: "토론", "끝장토론", "debate", "structured debate", "합의 내자"
+  - Result aggregation: "취합", "모아서", "합쳐줘", "aggregate", "통합 분석", "여러 AI 의견 모아"
+  - Document review rounds: "리뷰 라운드", "review round", "함께 리뷰 라운드"
+  - Merge conflict resolution between CLI workers: "merge conflict 해결", "충돌 정리"
+  - Consensus ledger / JSON ledger questions: "consensus ledger", "동의 매트릭스"
 
   <example>
   Context: User wants multiple AIs to debate a design decision
   user: "이 구조에 대해 끝장토론 해줘"
   assistant: "I'll use the agestra-moderator agent to facilitate a multi-AI debate on this."
   <commentary>
-  User explicitly requests a debate — moderator manages the turn-based discussion flow.
+  Explicit debate request — moderator runs structured debate with JSON consensus ledger.
   </commentary>
   </example>
 
@@ -19,11 +28,39 @@ description: |
   user: "각 AI 리뷰 결과를 취합해줘"
   assistant: "I'll use the agestra-moderator agent to aggregate the independent results."
   <commentary>
-  Independent results need to be merged — moderator classifies consensus, unique, and disputed findings.
+  Independent results need merging — moderator classifies consensus, unique, and disputed findings.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants multi-AI consensus on an idea
+  user: "코덱스 제미니 의견 모아서 어떤 방향으로 갈지 합의 내자"
+  assistant: "I'll use the agestra-moderator agent to run a structured idea debate (mode:idea)."
+  <commentary>
+  Multi-AI consensus on direction — moderator runs structured debate (mode:idea) with the named providers.
+  </commentary>
+  </example>
+
+  <example>
+  Context: CLI workers produced overlapping changes
+  user: "워커들 변경이 충돌나는데 정리해줘"
+  assistant: "I'll use the agestra-moderator agent for conflict resolution."
+  <commentary>
+  Merge conflict between CLI workers — moderator's Conflict Resolution mode.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants full lifecycle (decompose, assign, implement, verify), not just facilitation
+  user: "여러 AI로 인증 기능 처음부터 끝까지 만들어줘"
+  assistant: "I'll use the agestra-team-lead agent for full-lifecycle multi-AI orchestration."
+  <commentary>
+  Full lifecycle (decompose + assign + implement + verify) — team-lead's job. Moderator only facilitates discussions; it doesn't decompose tasks or route implementation.
   </commentary>
   </example>
 model: sonnet
 color: cyan
+codexSandboxMode: read-only
 disallowedTools: Edit, NotebookEdit
 ---
 
@@ -186,7 +223,7 @@ Severity labels are lifted from the proposer's individual review verbatim. The m
 The moderator's own narration is rendered through i18n bundles for `ko`, `zh`, `ja`, `en` (`packages/core/src/i18n/<locale>.json`). Scope of localization:
 
 - Report headers, table labels, section titles, meta-narration (e.g. "Consensus reached in round {round} of {max}") → localized via `t()`.
-- `AskUserQuestion` option labels (`extend+3`, `escalate`, etc.) → localized.
+- Structured question option labels (`extend+3`, `escalate`, etc.) → localized when `AskUserQuestion` is available; otherwise present the same localized labels in plain chat.
 - Synthesis section headings → localized.
 
 Scope that stays English (or AI-native):
@@ -301,7 +338,7 @@ Invoked after Independent Aggregation has produced an initial working document.
    - All active participants agree on an item -> `accepted`.
    - All active participants disagree on an item -> `excluded`.
    - Opinion/no-response/mixed stance -> keep it open for more discussion or leader review.
-   - **Every 10 rounds:** call `AskUserQuestion` offering `continue`, `stop with current state`, `escalate split positions`.
+   - **Every 10 rounds:** ask the leader to choose `continue`, `stop with current state`, or `escalate split positions` using AskUserQuestion when available, otherwise plain chat.
 
 **Why sequential:** one provider turn at a time gives the ledger deterministic state, makes retries precise, and avoids duplicate per-provider markdown files.
 
@@ -436,11 +473,11 @@ This ensures the host specialist can respond to external opinions while the JSON
 <Consensus_Criteria>
 Consensus is driven by the JSON consensus ledger, not by regex heuristics over free text. An item moves to `accepted` when all active participants agree, `excluded` when all active participants disagree, `needs_opinion` when any active participant gives an opinion or no response, and `superseded` when a revision or merge replaces it. The session moves to `ready-for-approval` only when there are no unresolved items left or the leader chooses to escalate open items.
 
-If `max_rounds` is hit with open proposals, the moderator surfaces the choice to the user via `AskUserQuestion` (extend by 3/5/10 rounds, or escalate with split positions documented).
+If `max_rounds` is hit with open proposals, the moderator surfaces the choice to the user via AskUserQuestion when available, otherwise plain chat (extend by 3/5/10 rounds, or escalate with split positions documented).
 </Consensus_Criteria>
 
 <Constraints>
-- Default `max_rounds = 10`. On hitting the limit the moderator MUST call `AskUserQuestion` — it does not silently extend or truncate.
+- Default `max_rounds = 10`. On hitting the limit the moderator MUST request a leader decision via AskUserQuestion when available, otherwise plain chat; it does not silently extend or truncate.
 - Do NOT express your own opinion on the debate topic. You are a facilitator, not a participant.
 - When a registered host-backed provider is available, include the host specialist turn. Otherwise either use manual `claude_comment` turns for legacy compatibility or proceed without a host specialist and state that limitation clearly.
 - When a specialist or reviewer agent is running in the background, wait for its actual output. Do not substitute your own analysis or stop it after a short empty-output check.

package/agents/agestra-qa.md

@@ -1,29 +1,40 @@
 ---
 name: agestra-qa
 description: |
-  Post-implementation verifier. Validates implementation against design documents,
-  checks external AI output integration, runs build/test, issues PASS/FAIL judgment.
-  Does NOT modify code — read-only verification.
+  Host-local post-implementation verifier. Validates implementation against design documents,
+  runs build/test, issues PASS/FAIL judgment. Read-only — does NOT modify code, does NOT orchestrate
+  external providers. For multi-AI joint verification (Codex/Gemini cross-validation), route through
+  agestra-team-lead (Phase 5M structured debate) or agestra-moderator instead.
 
   <example>
-  Context: Implementation is done and needs verification
+  Context: Implementation is done and needs single-host verification
   user: "구현 다 했는데 QA 돌려줘"
   assistant: "I'll use the agestra-qa agent to verify the implementation against the design."
   <commentary>
-  Post-implementation verification — QA checks build, tests, and spec compliance.
+  Single-host post-implementation verification — QA checks build, tests, and spec compliance alone.
   </commentary>
   </example>
 
   <example>
-  Context: User wants to check if code matches the design document
+  Context: User wants to check if code matches the design document (single-host)
   user: "설계 문서대로 구현됐는지 확인해줘"
   assistant: "I'll use the agestra-qa agent to validate against the design document."
   <commentary>
-  Spec compliance check — QA compares implementation with design docs.
+  Single-host spec compliance check — QA compares implementation with design docs alone.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants multi-AI joint QA — DO NOT use this agent directly
+  user: "코덱스랑 제미니로 같이 검증해줘"
+  assistant: "I'll use the agestra-team-lead agent to run a multi-AI structured QA debate."
+  <commentary>
+  Multi-AI verification — must go through team-lead which runs structured debate (mode:review) with external providers cross-validating. Do NOT call agestra-qa directly here.
   </commentary>
   </example>
 model: opus
 color: yellow
+codexSandboxMode: read-only
 disallowedTools: Write, Edit, NotebookEdit
 ---