docs: overhaul settings example for MCP-first architecture (v0.37.1)

- Rewrite .claude/codex-collab.local.md.example: drop retired model
  names, recommend omitting `model` (use Codex default), add missing
  documented keys (workflow, review.max_verdict_retries, claude_leads.*,
  collab_planning.*), and mark codex.wait_timeout / exchange.history_mode
  as Bash-fallback-only
- Sync README settings table (add max_verdict_retries and
  codex.wait_timeout rows, Bash-fallback annotations)
- Replace outdated o3/o4-mini/codex-mini references across CLAUDE.md,
  commands, SKILL.md, codex-options.md, and workflow-patterns.md
- Rewrite codex-options.md model selection guidance to avoid
  hardcoding model names

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaxhNebQHKaMTtd2yaTYhQ

Author: masuP9

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "codex-collab",
       "source": "./",
       "description": "Claude Code と OpenAI Codex CLI の協調タスク実行プラグイン",
-      "version": "0.37.0",
+      "version": "0.37.1",
       "author": {
         "name": "masuP9"
       }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-collab",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "Claude Code と OpenAI Codex CLI の協調タスク実行プラグイン",
   "author": {
     "name": "masuP9"

.claude/codex-collab.local.md.example

@@ -1,33 +1,57 @@
 # Codex Collab Settings Example
 
 Copy this file to `.claude/codex-collab.local.md` and customize for your project.
+Global settings can also be placed at `~/.claude/codex-collab.local.md`
+(priority: command args > project settings > global settings > safe defaults).
 
 ---
-model: o4-mini
-sandbox: read-only
-language: en               # Response language for Codex: en | ja | etc.
-                           # When set to non-English, adds language directive to all prompts.
-                           # For ja: "日本語で回答してください。途中の説明や思考プロセスも日本語で..."
-                           # This ensures both final output and thinking process are in the target language.
-
-# Timeout settings
-codex:
-  wait_timeout: 180        # seconds (default: 180, max: 600)
-                           # codex exec の最大実行時間（Bash tool の max は 600s）
+# ワークフロー選択
+workflow: auto             # auto | codex-leads | claude-leads
+                           # auto は常に codex-leads を選択（claude-leads は明示指定時のみ有効）
+
+# Codex モデル（省略推奨: 省略時は Codex 側デフォルト = ~/.codex/config.toml の model を使用）
+# 提供モデルは変わりやすいため、特別な理由がなければ固定しないこと。
+# model: gpt-5.6-sol       # 例: gpt-5.6-sol | gpt-5.5
+
+sandbox: read-only         # read-only | workspace-write | danger-full-access
+                           # codex-leads 用（Codex は計画・レビュー担当なので read-only 推奨）。
+                           # claude-leads の実装フェーズには claude_leads.sandbox が使われる。
 
-# Planning exchange settings (Codex plans → Claude questions → Codex refines)
+language: en               # Codex の応答言語: en | ja | etc.
+                           # 非英語を設定すると全プロンプトに言語指示が付加される。
+                           # ja の場合: 「日本語で回答してください。途中の説明や思考プロセスも日本語で...」
+
+# Planning exchange settings (codex-leads: Codex plans → Claude questions → Codex refines)
 exchange:
-  enabled: true              # Global kill-switch for planning exchanges
-  max_iterations: 3
+  enabled: true              # Planning exchange のグローバルキルスイッチ
+  max_iterations: 3          # 暴走防止の上限ラウンド数
   user_confirm: on_important # never | always | on_important
   history_mode: summarize    # full | summarize
+                             # ※ Bash fallback 専用。MCP モードではスレッドが履歴を保持するため無視される。
 
-# Review iteration settings (Codex reviews → Claude fixes → Codex re-reviews)
+# Review iteration settings (codex-leads: Codex reviews → Claude fixes → Codex re-reviews)
 review:
-  enabled: true              # Enable/disable review iterations
-  max_iterations: 5          # Can be higher than exchange (goal is clear, diff is small)
-  max_verdict_retries: 3     # Retries when verdict is missing/unclear from Codex
-  user_confirm: never        # Auto-iterate for reviews
+  enabled: true              # Review iteration の有効化
+  max_iterations: 5          # exchange より多め（ゴールが明確で diff が小さいため）
+  max_verdict_retries: 3     # verdict が取れない/不明瞭な場合のリトライ回数
+  user_confirm: never        # レビューは自動イテレーション
+
+# claude-leads workflow settings（Claude が計画・レビュー、Codex が実装）
+claude_leads:
+  sandbox: workspace-write   # Codex 実装フェーズ用 sandbox
+  consult_codex: true        # 実装前の計画壁打ちフェーズを有効化
+  safety_checkpoint: stash   # stash | wip-commit | none（実装前のチェックポイント方式）
+  review:
+    max_iterations: 3        # Claude レビュー修正ループの上限
+
+# /collab-planning settings（計画のみ作成するワークフロー）
+collab_planning:
+  max_iterations: 3          # 計画レビュー改善サイクルの上限
+  user_confirm: on_important # never | always | on_important
+
+# Bash fallback 専用設定（MCP モードでは無視される）
+codex:
+  wait_timeout: 180          # codex exec の最大実行時間（秒。default: 180, max: 600 = Bash tool の上限）
 ---
 
 ## Project-specific Instructions

CLAUDE.md

@@ -76,8 +76,8 @@ MCP が利用できない場合のフォールバック。プロンプトを std
 # 基本パターン
 codex exec -s read-only - < prompt.txt
 
-# モデル指定
-codex exec -s read-only -m o4-mini - < prompt.txt
+# モデル指定（通常は省略して Codex デフォルトを使用）
+codex exec -s read-only -m gpt-5.6-sol - < prompt.txt
 ```
 
 - 各呼び出しはステートレス（会話コンテキストは保持されない）

README.md

@@ -343,36 +343,40 @@ Claude と Codex に**同じ問いを独立に解かせ**、答えの食い違
 
 ```markdown
 ---
-model: o4-mini
 sandbox: read-only
+language: ja
 ---
 
 # プロジェクト固有の指示
 
 このプロジェクトでは TypeScript を使用しています。
 ```
 
+サンプルは [`.claude/codex-collab.local.md.example`](.claude/codex-collab.local.md.example) を参照してください。
+
 ### 設定オプション
 
 | オプション | デフォルト | 説明 |
 |-----------|-----------|------|
 | `workflow` | `auto` | ワークフロー選択 (auto, codex-leads, claude-leads) |
-| `model` | (Codexデフォルト) | 使用するモデル (o3, o4-mini等) |
+| `model` | (Codexデフォルト) | 使用するモデル (gpt-5.6-sol 等)。省略時は `~/.codex/config.toml` の設定を使用 |
 | `sandbox` | `read-only` | サンドボックスモード (read-only, workspace-write, danger-full-access)。codex-leads用 |
 | `language` | `en` | レスポンス言語 (en, ja 等) |
 | `exchange.enabled` | `true` | Planning exchangeのグローバルキルスイッチ (codex-leads) |
 | `exchange.max_iterations` | `3` | Planning exchangeの最大ラウンド数 |
 | `exchange.user_confirm` | `on_important` | ユーザー確認タイミング (never, always, on_important) |
-| `exchange.history_mode` | `summarize` | 履歴管理方式: full=全履歴保持, summarize=最新2ラウンドのみ全文 |
+| `exchange.history_mode` | `summarize` | 履歴管理方式: full=全履歴保持, summarize=最新2ラウンドのみ全文。**Bash fallback 専用**（MCPモードではスレッドが履歴を保持） |
 | `review.enabled` | `true` | Review iterationの有効化 (codex-leads) |
 | `review.max_iterations` | `5` | Review iterationの最大ラウンド数（ゴールが明確なので多め） |
+| `review.max_verdict_retries` | `3` | verdict が取れない/不明瞭な場合のリトライ回数 |
 | `review.user_confirm` | `never` | レビュー時は自動でイテレーション |
 | `claude_leads.sandbox` | `workspace-write` | Codex実装用サンドボックス (claude-leads) |
 | `claude_leads.consult_codex` | `true` | 計画の壁打ちフェーズ有効化 (claude-leads) |
 | `claude_leads.safety_checkpoint` | `stash` | 実装前チェックポイント (stash, wip-commit, none) |
 | `claude_leads.review.max_iterations` | `3` | Claudeレビュー修正ループの上限 (claude-leads) |
 | `collab_planning.max_iterations` | `3` | 計画レビュー改善サイクルの上限 |
 | `collab_planning.user_confirm` | `on_important` | ユーザー確認タイミング (never, always, on_important) |
+| `codex.wait_timeout` | `180` | `codex exec` の最大実行時間（秒、max 600）。**Bash fallback 専用**（MCPモードでは無視） |
 
 ### 設定の優先順位
 
@@ -384,7 +388,7 @@ sandbox: read-only
 
 ### Codex-Leads（従来）
 
-Codex が計画・レビュー、Claude が実装するワークフロー。推論に優れたモデル（o3, gpt-5等）に最適。
+Codex が計画・レビュー、Claude が実装するワークフロー。推論に優れたモデルに最適。
 
 ```
 1. ユーザー: /codex-collab "機能Xを実装して"
@@ -397,7 +401,7 @@ Codex が計画・レビュー、Claude が実装するワークフロー。推
 
 ### Claude-Leads（新規）
 
-Claude が計画・レビュー、Codex が実装するワークフロー。高速実行向きモデル（codex-mini, o4-mini等）に最適。
+Claude が計画・レビュー、Codex が実装するワークフロー。高速実行向きの軽量モデルに最適。
 
 ```
 1. ユーザー: /codex-collab "機能Xを実装して"

commands/codex-collab.md

@@ -330,7 +330,7 @@ echo "Codex plan saved to: $CODEX_OUTPUT"
 > For long-running tasks, use `run_in_background: true` on the Bash tool.
 
 **Options to include based on settings:**
-- `-m, --model <model>` - Specify model (e.g., o4-mini, o3) from `model` setting
+- `-m, --model <model>` - Specify model from `model` setting (omit when unset — Codex uses its own default)
 - `-s, --sandbox <mode>` - read-only | workspace-write | danger-full-access from `sandbox` setting
 
 ### Step 5: Read and Process Response

skills/codex-collab/SKILL.md

@@ -145,28 +145,30 @@ Check for `.claude/codex-collab.local.md` in project root:
 
 ```markdown
 ---
-model: o4-mini
 sandbox: read-only
+language: ja
 ---
 
 # Project-specific instructions
 ```
 
 Parse YAML frontmatter for:
-- `model`: Codex model to use
+- `model`: Codex model to use (omit to use the Codex default from `~/.codex/config.toml`)
 - `sandbox`: read-only | workspace-write | danger-full-access
 - `workflow`: Workflow mode (auto | codex-leads | claude-leads, default: auto; auto は常に codex-leads を選択)
 - `exchange.enabled`: Enable planning exchange (default: true, codex-leads only)
 - `exchange.max_iterations`: Maximum rounds for multi-turn exchange (default: 3)
 - `exchange.user_confirm`: When to ask user confirmation (never | always | on_important)
-- `exchange.history_mode`: How to handle history (full | summarize)
+- `exchange.history_mode`: How to handle history (full | summarize; Bash fallback only — MCP threads preserve history)
 - `review.enabled`: Enable review iteration (default: true, codex-leads only)
 - `review.max_iterations`: Maximum rounds for review iteration (default: 5)
+- `review.max_verdict_retries`: Retries when verdict is missing/unclear (default: 3)
 - `review.user_confirm`: When to ask user confirmation for reviews (default: never)
 - `claude_leads.sandbox`: Sandbox for Codex implementation (default: workspace-write)
 - `claude_leads.consult_codex`: Enable plan consultation phase (default: true)
 - `claude_leads.safety_checkpoint`: Pre-implementation checkpoint (stash | wip-commit | none, default: stash)
 - `claude_leads.review.max_iterations`: Max review-fix iterations (default: 3)
+- `codex.wait_timeout`: Max execution time for `codex exec` in seconds (default: 180, max: 600; Bash fallback only)
 
 ### Settings Priority
 
@@ -241,15 +243,15 @@ MCP が利用できない場合、`codex exec`（ステートレス実行）を
 source scripts/codex-helpers.sh
 PROMPT_FILE=$(codex_write_prompt "$PROMPT_CONTENT" "plan")
 OUTPUT_FILE="$(codex_tmp_path 'codex-output.md')"
-codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only" "o4-mini"
+codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only"
 
-# 直接実行
-codex exec -s read-only -m o4-mini - < prompt.txt 2>&1 | tee output.md
+# 直接実行（モデルは通常 Codex デフォルトを使用。指定する場合のみ -m を付ける）
+codex exec -s read-only - < prompt.txt 2>&1 | tee output.md
 ```
 
 ### Codex CLI Options
 
-- `-m, --model <model>` - Specify model (e.g., o4-mini, o3)
+- `-m, --model <model>` - Specify model (e.g., gpt-5.6-sol; omit to use the Codex default)
 - `-s, --sandbox <mode>` - read-only | workspace-write | danger-full-access
 - `-C, --cd <dir>` - Working directory
 - `--full-auto` - Automatic execution mode

skills/codex-collab/references/codex-options.md

@@ -50,32 +50,31 @@ Override settings from `~/.codex/config.toml`:
 
 ```bash
 # Set model
-codex exec -c model="o3" "prompt"
+codex exec -c model="gpt-5.6-sol" "prompt"
 
 # Set sandbox permissions
 codex exec -c 'sandbox_permissions=["disk-full-read-access"]' "prompt"
 
 # Multiple overrides
-codex exec -c model="o4-mini" -c 'features.stream=true' "prompt"
+codex exec -c model="gpt-5.6-sol" -c 'features.stream=true' "prompt"
 ```
 
 ## Model Selection
 
 ### Available Models
 
-Common models (subject to OpenAI availability):
-- `o3` - Most capable, higher cost
-- `o4-mini` - Balanced performance/cost
-- Default varies by Codex installation
+Model availability changes with OpenAI releases — do not hardcode model names in prompts or settings unless there is a specific reason.
+
+- **Default (recommended)**: omit `model` / `-m` entirely; Codex uses the `model` value from `~/.codex/config.toml`
+- Example current models: `gpt-5.6-sol`, `gpt-5.5` (check `~/.codex/config.toml` or the Codex release notes for what is currently available)
+- Retired model names (e.g., `o3`, `o4-mini`, `gpt-5.x-codex`) will fail or be silently migrated
 
 ### Selection Criteria
 
-| Task Type | Recommended Model |
-|-----------|-------------------|
-| Complex planning | o3 |
-| Quick review | o4-mini |
-| Architectural decisions | o3 |
-| Simple validation | o4-mini |
+| Task Type | Recommendation |
+|-----------|----------------|
+| Planning / review / architectural decisions | Codex default (usually the most capable current model) |
+| Quick validation on a budget | A lighter current model, if one is available |
 
 ## Configuration Hierarchy
 
@@ -118,7 +117,7 @@ Provide a code review with verdict (PASS/CONDITIONAL/FAIL)."
 
 ```bash
 codex exec \
-  -m o4-mini \
+  -m gpt-5.6-sol \
   -s read-only \
   "Quick validation: Is this function safe? [code here]"
 ```
@@ -216,7 +215,7 @@ codex review [OPTIONS] [PROMPT]
 | Option | Short | Description |
 |--------|-------|-------------|
 | `--uncommitted` | | Review uncommitted/staged changes |
-| `--config <key=value>` | `-c` | Override config values (e.g., `model="o4-mini"`) |
+| `--config <key=value>` | `-c` | Override config values (e.g., `model="gpt-5.6-sol"`) |
 
 ### Usage
 
@@ -228,7 +227,7 @@ codex review --uncommitted
 codex review --uncommitted "Focus on security vulnerabilities"
 
 # With model override
-codex review --uncommitted -c 'model="o4-mini"'
+codex review --uncommitted -c 'model="gpt-5.6-sol"'
 ```
 
 ### Key Differences from `codex exec`
@@ -267,11 +266,11 @@ source scripts/codex-helpers.sh
 # For general execution
 PROMPT_FILE=$(codex_write_prompt "$PROMPT_CONTENT" "plan")
 OUTPUT_FILE="$(codex_tmp_path 'codex-output.md')"
-codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only" "o4-mini"
+codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only"   # model arg omitted → Codex default
 
 # For code review (preferred for review phase)
 REVIEW_OUTPUT="$(codex_tmp_path 'codex-review-output.md')"
-codex_run_review "$REVIEW_OUTPUT" "o4-mini"
+codex_run_review "$REVIEW_OUTPUT"
 ```
 
 ### Helper Functions

skills/codex-collab/references/workflow-patterns.md

@@ -148,7 +148,7 @@ Complete
 
 **Best for**:
 - Tasks requiring deep codebase understanding for planning
-- When Codex model is optimized for fast execution (codex-mini, o4-mini)
+- When the configured Codex model is optimized for fast execution over deep reasoning
 - Complex refactoring where planning quality matters most
 - When Claude's reasoning strength should drive the architecture
 
@@ -214,7 +214,7 @@ Complete
 | Large task | Divide and Conquer |
 | Critical code | Review Type (strict) |
 | Complex planning needed | Claude-Led Type |
-| Reasoning model (o3 系) | Review Type |
+| Reasoning-optimized model configured | Review Type |
 
 ## Switching Patterns Mid-Task