verbalcoding 0.2.12 → 0.2.13

package/docs/i18n/HARNESS_AIDER.zh.md

@@ -0,0 +1,48 @@
+# Aider — Harness 说明
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="HARNESSES.zh.md">Harness</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a>
+</p>
+
+Aider 是专注于直接编辑文件的结对编程 AI CLI。VerbalCoding 通过 `aider --no-pretty --yes-always --message` 驱动 — prompt 作为 `--message` 的值传入,每个语音 turn 都是一次可能直接修改 `AGENT_WORKDIR` 中文件的非交互 Aider 运行。
+
+## 安装
+
+```bash
+pip install aider-chat
+aider --version
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider 需要所用模型对应的 API key (OpenAI / Anthropic / 本地服务器)。详见 <https://aider.chat>。
+
+## VerbalCoding 配置
+
+```bash
+# .env
+AGENT_BACKEND=aider
+AIDER_COMMAND="aider --no-pretty --yes-always --message"   # 默认
+AGENT_WORKDIR=/Users/you/code/your-project                 # Aider 编辑的目录
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000                               # Aider 通常更久
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` 去掉 Rich 框字符以免卡住流式 sentencer。`--yes-always` 保持非交互 (Aider 不再因 "应用此 diff?" 提示停下)。
+
+## 切到 Aider 的语音表述
+
+- en: `"switch to Aider"`、`"ask Aider to ..."`
+- zh: `"切到 Aider"`、`"让 Aider 处理"`
+
+别名: `aider`。
+
+## 坑
+
+- **Aider 会改文件。** 与 `-p` 模式下的 Claude / Codex / Gemini 不同,Aider 在回答时直接修改工作树。慎选 `AGENT_WORKDIR` — 通常用项目会话的 `workdir`。
+- **输出含 diff。** Aider 经常输出 diff 形态文本。turn 被中断时 bridge 只播报 "已中断",不朗读 diff — 用文本频道与 `git status` 确认。
+- **认证。** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` 必须在 Aider 环境中;实例隔离常用 `instances/<project>.env`。
+- **按频道状态。** 跨代理路由按 Discord 频道隔离,在某个项目房间切到 Aider 不影响其它房间。

package/docs/i18n/HARNESS_CLAUDE.es.md

@@ -0,0 +1,55 @@
+# Claude Code — Notas del Harness
+
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="HARNESSES.es.md">Harnesses</a> ·
+  <a href="USAGE.es.md">Uso</a> ·
+  <a href="CONFIGURATION.es.md">Configuración</a>
+</p>
+
+Claude Code es el agente de codificación oficial de Anthropic en terminal. VerbalCoding lo invoca con `claude -p`: cada turno de voz es una invocación. `-p` no expone un contrato estable de reanudación entre llamadas, así que cada turno empieza con contexto fresco — usa `AGENT_PROJECT_CONTEXT` y el bloque de handoff entre agentes para mantener continuidad.
+
+## Instalación
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"
+```
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=claude
+CLAUDE_COMMAND="claude -p"
+AGENT_PROJECT_CONTEXT="Trabajando en el módulo de auth; decisiones previas: oauth=github."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` no se usa en este harness (Claude Code `-p` es stateless).
+
+## Lo que recibe Claude por turno
+
+Cada turno el adaptador antepone: el preamble Discord (en/es según `VOICE_LANGUAGE`), el contexto del proyecto, el contexto reciente del canal de texto y por último la transcripción. En un handoff entre agentes, también se incluye un bloque "Recent user voice" (hasta 4 elocuciones) y las decisiones de plan más recientes, para que Claude no parta de frío.
+
+## Progreso detallado
+
+Claude Code no emite un stream estándar bajo `-p`. Con `AGENT_VERBOSE_PROGRESS=1` el adaptador extrae menciones de herramientas/archivos/web de stdout/stderr, pero más groseramente que Hermes.
+
+## Frases de voz para cambiar a Claude Code
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- es: `"cambia a Claude"`, `"pregunta a Claude"`
+
+El matcher acepta `claude` y `claude code`. El modo strict para enrutamiento puro exige coincidencia exacta.
+
+## Trampas
+
+- **Sin reanudación de sesión.** Las sesiones largas dependen del bloque de handoff para arrastrar decisiones; dentro del mismo backend, pon `AGENT_PROJECT_CONTEXT` con un resumen corto.
+- **Comandos entrecomillados.** Si `CLAUDE_COMMAND` tiene una ruta absoluta con espacios (p. ej. `"/Applications/Claude Code/claude" -p`), la sonda de instalación usa `shellSplit` y respeta las comillas.
+- **Refresco de auth.** La caducidad de `claude login` se ve como salida no cero; el puente reporta el fallo y, si no era el backend por defecto, ofrece fallback.
+- **Salida tipo patch.** Si se interrumpe el turno mientras Claude devuelve un diff, el puente no lee el diff en voz alta; dice "interrumpido; revisa el canal de texto".

package/docs/i18n/HARNESS_CLAUDE.fr.md

@@ -0,0 +1,55 @@
+# Claude Code — Notes Harness
+
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="HARNESSES.fr.md">Harnesses</a> ·
+  <a href="USAGE.fr.md">Utilisation</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a>
+</p>
+
+Claude Code est l'agent de codage de terminal officiel d'Anthropic. VerbalCoding l'invoque via `claude -p` : un tour vocal = une invocation. `-p` n'expose pas de contrat stable de reprise — chaque tour repart sur un contexte vierge. Utilisez `AGENT_PROJECT_CONTEXT` et le bloc de handoff inter-agents pour la continuité.
+
+## Installation
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"
+```
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=claude
+CLAUDE_COMMAND="claude -p"
+AGENT_PROJECT_CONTEXT="Module auth en cours ; décisions : oauth=github."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` n'est pas utilisé pour ce harness (Claude `-p` est stateless).
+
+## Ce que reçoit Claude par tour
+
+À chaque tour, l'adaptateur préfixe : préambule Discord (en/fr selon `VOICE_LANGUAGE`), contexte projet, contexte texte récent, puis la transcription. Lors d'un handoff inter-agents, on ajoute une ligne "Recent user voice" (jusqu'à 4 énoncés) et les décisions de plan résolues les plus récentes, pour éviter le démarrage à froid.
+
+## Progression verbeuse
+
+Claude Code n'émet pas de stream standard via `-p`. Avec `AGENT_VERBOSE_PROGRESS=1`, l'adaptateur extrait les mentions d'outils/fichiers/web de stdout/stderr — granularité plus grossière qu'Hermes.
+
+## Phrases vocales pour basculer vers Claude Code
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- fr: `"passe à Claude"`, `"demande à Claude"`
+
+Le matcher accepte `claude` et `claude code`. Le mode strict du routage exige une correspondance exacte.
+
+## Pièges
+
+- **Pas de reprise.** Les sessions longues s'appuient sur le bloc de handoff ; à l'intérieur d'un même backend, fournissez un résumé via `AGENT_PROJECT_CONTEXT`.
+- **Chemins entre guillemets.** Si `CLAUDE_COMMAND` contient un chemin absolu avec espaces (ex. `"/Applications/Claude Code/claude" -p`), la sonde d'installation utilise `shellSplit` et respecte les guillemets.
+- **Expiration d'auth.** L'expiration `claude login` ressort en exit non-nul ; le bridge signale et propose un fallback si Claude n'était pas le défaut.
+- **Sortie type patch.** Si Claude est interrompu en plein diff, le bridge ne lit pas le diff — il annonce "interrompu, vérifiez le canal texte".

package/docs/i18n/HARNESS_CLAUDE.ja.md

@@ -0,0 +1,56 @@
+# Claude Code — ハーネスノート
+
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="HARNESSES.ja.md">ハーネス</a> ·
+  <a href="USAGE.ja.md">使い方</a> ·
+  <a href="CONFIGURATION.ja.md">設定</a>
+</p>
+
+Claude Code は Anthropic 公式のターミナル常駐コーディングエージェントです。VerbalCoding は `claude -p` で呼び出し、音声ターン 1 つにつき 1 invocation。`-p` は呼び出し間の安定なセッション再開契約を持たないため毎回新規コンテキスト — 連続性は `AGENT_PROJECT_CONTEXT` とクロスエージェントハンドオフブロックで維持してください。
+
+## インストール
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"     # 応答確認
+```
+
+## VerbalCoding 設定
+
+```bash
+# .env
+AGENT_BACKEND=claude              # 'claude-code' エイリアスも可
+# 任意
+CLAUDE_COMMAND="claude -p"        # 既定。--model, --debug 追加可
+AGENT_PROJECT_CONTEXT="auth モジュール作業中。既決定: oauth=github。"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` は既定 `<repo>/.agent-sessions/claude` ですが、このハーネスでは**未使用** — Claude Code の `-p` は stateless。設定したままでも no-op。
+
+## 各ターン Claude が受け取るもの
+
+各ターン、アダプタは Discord 音声対応の preamble (`VOICE_LANGUAGE` に応じ英語または日本語)、プロジェクトコンテキスト、最近の Discord テキストコンテキスト、最後に STT 結果を順に prepend します。クロスエージェントハンドオフ時 (前ターンが `"ask Codex ..."` で今回が初復帰など) は "最近のユーザー音声" 行 (最大 4 件) と直近解決済みプラン決定も含み、Claude が cold start しないようにします。
+
+## 詳細進捗
+
+Claude Code は `-p` で標準 progress stream を emit しません。`AGENT_VERBOSE_PROGRESS=1` 時はアダプタが stdout/stderr のツール/ファイル/Web 言及をキーワードで拾いますが、Hermes より粗い情報量。
+
+## Claude Code へ切り替える音声表現
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- ja: `"Claude に切り替えて"`, `"Claude に聞いて"`
+
+マッチャは `claude` と `claude code` 双方をエイリアスとして受けます。ルーティング専用発話で使う strict モードは完全一致のみ。
+
+## 罠
+
+- **セッション再開なし。** 長期ペアプロは、クロスエージェントハンドオフコンテキストブロックに依存して決定を引き継ぎます。バックエンド切替時は自動付与、同一バックエンド内では `AGENT_PROJECT_CONTEXT` に要約を入れておく。
+- **引用付きコマンドパス。** `CLAUDE_COMMAND` に空白を含む絶対パス (例: `"/Applications/Claude Code/claude" -p`) がある場合、VerbalCoding のインストール検査は `shellSplit` を使い引用符を正しく扱います。
+- **認証更新。** `claude login` トークン失効は非零 exit。bridge が失敗を報告し、既定でなければ fallback プロンプトで既定エージェントへの retry を提案。
+- **patch 形式出力。** Claude が diff 返却中に turn が割り込まれた場合、bridge は diff を読み上げず "中断: テキストチャンネルでファイルとテスト状況を確認してください" のみ発話。

package/docs/i18n/HARNESS_CLAUDE.ko.md

@@ -0,0 +1,56 @@
+# Claude Code — 하니스 노트
+
+<p align="center">
+  <a href="../../README.ko.md">README</a> ·
+  <a href="HARNESSES.ko.md">하니스</a> ·
+  <a href="USAGE.ko.md">사용법</a> ·
+  <a href="CONFIGURATION.ko.md">설정</a>
+</p>
+
+Claude Code는 Anthropic의 공식 터미널 코딩 에이전트야. VerbalCoding은 `claude -p`로 호출하고, voice turn 하나가 invocation 한 번. `-p`는 호출 간 세션 재개 계약이 없어서 매번 fresh context — 연속성을 유지하려면 `AGENT_PROJECT_CONTEXT`와 크로스 에이전트 핸드오프 블록을 활용해.
+
+## 설치
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"     # 응답 오는지 확인
+```
+
+## VerbalCoding 설정
+
+```bash
+# .env
+AGENT_BACKEND=claude              # 'claude-code' 별칭도 허용
+# 선택
+CLAUDE_COMMAND="claude -p"        # 기본값. --model, --debug 같은 플래그 추가 가능
+AGENT_PROJECT_CONTEXT="auth 모듈 작업 중; 이전 결정: oauth=github."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE`은 기본 `<repo>/.agent-sessions/claude`이지만 이 하니스에서는 **사용되지 않아** — Claude Code의 `-p`는 stateless. 그대로 둬도 no-op.
+
+## 매 턴 Claude가 받는 것
+
+매 턴 어댑터는 디스코드 음성 대응 preamble(`VOICE_LANGUAGE`에 따라 영어 또는 한국어), 프로젝트 컨텍스트, 최근 디스코드 텍스트 컨텍스트, 마지막으로 STT 결과를 순서대로 prepend해. 크로스 에이전트 핸드오프인 경우(예: 이전 턴에 `"코덱스한테 물어봐"`였고 이번 턴이 첫 복귀) "최근 사용자 음성" 라인(최대 4개)과 가장 최근 해결된 플랜 결정도 같이 붙어서 Claude가 cold start하지 않아.
+
+## 상세 진행
+
+Claude Code는 `-p`에서 표준 progress stream을 emit하지 않아. `AGENT_VERBOSE_PROGRESS=1`을 켜면 어댑터가 stdout/stderr에서 tool/file/web 멘션을 키워드로 파싱하긴 하지만, Hermes보다 거친 진행 정보만 잡혀.
+
+## Claude Code로 전환하는 음성 표현
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- ko: `"클로드로 전환"`, `"claude한테 물어봐"`
+
+매처는 `claude`와 `claude code` 둘 다 별칭으로 받아. 라우팅-온리 발화에서 쓰는 strict 모드는 정확히 일치해야 매치돼.
+
+## 함정
+
+- **세션 재개 없음.** 긴 페어 프로그래밍 세션은 크로스 에이전트 핸드오프 컨텍스트 블록에 의존해서 결정사항을 이어가야 해. 백엔드 전환 시 자동으로 들어가고, 같은 백엔드 안에서는 `AGENT_PROJECT_CONTEXT`에 짧은 요약을 넣어둬.
+- **인용된 명령 경로.** `CLAUDE_COMMAND`에 공백이 든 절대 경로가 있으면(예: `"/Applications/Claude Code/claude" -p`) VerbalCoding의 설치 검사가 `shellSplit`을 써서 따옴표를 올바르게 처리해.
+- **인증 갱신.** `claude login` 토큰 만료는 non-zero exit로 surfacing돼. bridge가 실패를 보고하고, 기본 백엔드가 아니면 fallback 프롬프트가 기본 에이전트로 재시도를 제안.
+- **Patch 형식 출력.** Claude가 diff를 반환 중에 턴이 interrupt되면 bridge는 diff를 음성으로 읽지 않고 `"에이전트 작업이 중단됐어. 파일 변경과 테스트 상태는 텍스트 채널을 확인해줘"`라고만 말해.

package/docs/i18n/HARNESS_CLAUDE.ru.md

@@ -0,0 +1,55 @@
+# Claude Code — Заметки по harness
+
+<p align="center">
+  <a href="../../README.ru.md">README</a> ·
+  <a href="HARNESSES.ru.md">Harness-ы</a> ·
+  <a href="USAGE.ru.md">Использование</a> ·
+  <a href="CONFIGURATION.ru.md">Настройка</a>
+</p>
+
+Claude Code — официальный терминальный кодинг-агент Anthropic. VerbalCoding вызывает его через `claude -p`: один turn — один вызов. У `-p` нет стабильного контракта возобновления, поэтому каждый turn начинается с чистого контекста — используйте `AGENT_PROJECT_CONTEXT` и блок hand-off между агентами для непрерывности.
+
+## Установка
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"
+```
+
+## Настройка
+
+```bash
+# .env
+AGENT_BACKEND=claude
+CLAUDE_COMMAND="claude -p"
+AGENT_PROJECT_CONTEXT="Работаем над auth-модулем; решения: oauth=github."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` для этого harness не используется (Claude `-p` stateless).
+
+## Что получает Claude каждый turn
+
+Каждый turn адаптер добавляет в начало: Discord-преамбулу (en/ru по `VOICE_LANGUAGE`), контекст проекта, недавний контекст текстового канала и саму расшифровку. При cross-agent handoff к этому добавляется блок "Recent user voice" (до 4 реплик) и последние резолвнутые решения плана, чтобы Claude не стартовал «вхолодную».
+
+## Подробный прогресс
+
+Под `-p` Claude не выдаёт стандартный stream. С `AGENT_VERBOSE_PROGRESS=1` адаптер парсит из stdout/stderr упоминания инструментов/файлов/веба — грубее, чем Hermes.
+
+## Голосовые фразы для переключения на Claude Code
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- ru: `"переключись на Claude"`, `"спроси Claude"`
+
+Матчер принимает `claude` и `claude code`. Strict-режим маршрутизации требует точного совпадения.
+
+## Подводные камни
+
+- **Нет возобновления.** Длинные сессии опираются на блок hand-off для переноса решений; внутри одного backend держите краткое резюме в `AGENT_PROJECT_CONTEXT`.
+- **Кавычки в путях.** Если `CLAUDE_COMMAND` — абсолютный путь с пробелами (`"/Applications/Claude Code/claude" -p`), проверка установки использует `shellSplit` и обрабатывает кавычки корректно.
+- **Истечение auth.** Просрочка `claude login` ловится как non-zero exit; мост сообщает и предлагает fallback, если Claude не был дефолтом.
+- **Patch-вывод.** Если turn прерван во время diff, мост не зачитывает diff: говорит "прервано; проверьте текстовый канал".

package/docs/i18n/HARNESS_CLAUDE.zh.md

@@ -0,0 +1,56 @@
+# Claude Code — Harness 说明
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="HARNESSES.zh.md">Harness</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a>
+</p>
+
+Claude Code 是 Anthropic 官方的终端编码代理。VerbalCoding 通过 `claude -p` 驱动,每个语音 turn 一次调用。`-p` 没有稳定的跨调用会话续接,因此每次都是全新上下文 — 通过 `AGENT_PROJECT_CONTEXT` 和跨代理 handoff 块保持连续性。
+
+## 安装
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"     # 确认能回应
+```
+
+## VerbalCoding 配置
+
+```bash
+# .env
+AGENT_BACKEND=claude              # 也接受 'claude-code' 别名
+# 可选
+CLAUDE_COMMAND="claude -p"        # 默认,可加 --model、--debug
+AGENT_PROJECT_CONTEXT="auth 模块工作中;既定:oauth=github。"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` 默认 `<repo>/.agent-sessions/claude`,但此 harness **未使用** — Claude Code 的 `-p` 是无状态的。
+
+## 每个 turn Claude 收到的内容
+
+每个 turn,适配器按顺序前置: Discord 语音前言 (按 `VOICE_LANGUAGE` 英文或中文)、项目上下文、最近 Discord 文本上下文,最后是用户的 STT 发言。跨代理 handoff 时 (例如上 turn 说了 `"ask Codex ..."`),还会加入 "最近用户语音" 行 (最多 4 条) 和最近已解决的计划决定,避免 Claude 冷启。
+
+## 详细进度
+
+Claude Code 在 `-p` 下不发出标准 progress stream。开启 `AGENT_VERBOSE_PROGRESS=1` 时,适配器会从 stdout/stderr 关键字解析工具/文件/网页提及,但粒度比 Hermes 粗。
+
+## 切到 Claude Code 的语音表述
+
+- en: `"switch to Claude Code"`、`"ask Claude ..."`、`"let Claude finish this"`
+- zh: `"切到 Claude"`、`"问 Claude"`
+
+匹配器接受 `claude` 和 `claude code`。路由专用发言使用 strict 模式,需精确匹配。
+
+## 坑
+
+- **无会话续接。** 长配对编程依赖跨代理 handoff 上下文块来传递决定;同一后端内,设 `AGENT_PROJECT_CONTEXT` 为简短摘要。
+- **带引号的命令路径。** 若 `CLAUDE_COMMAND` 含带空格的绝对路径 (如 `"/Applications/Claude Code/claude" -p`),VerbalCoding 的安装检测会用 `shellSplit` 正确处理引号。
+- **认证刷新。** `claude login` 令牌失效会以非零退出;bridge 报告失败,如果不是默认后端,fallback 会建议改用默认代理。
+- **patch 形输出。** 如果 Claude 在返回 diff 时被中断,bridge 不会朗读 diff,而是说 "代理被中断;请在文本频道确认文件与测试状态"。

package/docs/i18n/HARNESS_CODEX.es.md

@@ -0,0 +1,55 @@
+# Codex — Notas del Harness
+
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="HARNESSES.es.md">Harnesses</a> ·
+  <a href="USAGE.es.md">Uso</a> ·
+  <a href="CONFIGURATION.es.md">Configuración</a>
+</p>
+
+Codex CLI es el agente de codificación de terminal de OpenAI. VerbalCoding lo invoca con `codex exec`. Como `codex exec` escribe el texto final del asistente a un fichero temporal cuando recibe `--output-last-message <path>`, el adaptador inserta ese flag automáticamente y lee la respuesta desde el fichero incluso si stdout está ruidoso.
+
+## Instalación
+
+```bash
+npm install -g @openai/codex
+codex login                     # o OPENAI_API_KEY headless
+codex exec "hello"
+```
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=codex
+CODEX_COMMAND="codex exec"
+AGENT_PROJECT_CONTEXT="Qué estamos haciendo, qué ya está decidido."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` no se usa (Codex `exec` es stateless entre llamadas).
+
+## Captura de salida
+
+El adaptador para Codex:
+
+1. Genera una ruta temporal `verbalcoding-codex-last-<pid>-<ts>.txt` en `os.tmpdir()`.
+2. Inserta `--output-last-message <path>` justo antes del argumento posicional final.
+3. Tras la ejecución, lee ese fichero como respuesta autoritativa (preferida sobre stdout).
+4. Borra el temporal.
+
+Aunque Codex pinte tool-use en stdout, la respuesta hablada viene siempre del fichero capturado.
+
+## Frases de voz para cambiar a Codex
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- es: `"cambia a Codex"`, `"pregunta a Codex"`
+
+## Trampas
+
+- **Tareas largas.** Pon `AGENT_TASK_TIMEOUT_MS=0` para generación que tarde minutos. El adaptador respeta `signal.aborted`, así que el barge-in corta limpio.
+- **Sin reanudación.** Pasa contexto vía `AGENT_PROJECT_CONTEXT` y deja el bloque de handoff hacer el resto.
+- **Seguridad ante patches.** Si el turno se interrumpe con Codex a medio diff, el puente no lee el diff: anuncia "interrumpido" y te manda al canal de texto.
+- **Autenticación.** Un 401 sale como exit no cero; si no eras el backend por defecto, fallback ofrece el por defecto.

package/docs/i18n/HARNESS_CODEX.fr.md

@@ -0,0 +1,55 @@
+# Codex — Notes Harness
+
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="HARNESSES.fr.md">Harnesses</a> ·
+  <a href="USAGE.fr.md">Utilisation</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a>
+</p>
+
+Codex CLI est l'agent terminal d'OpenAI. VerbalCoding l'invoque via `codex exec`. Comme `codex exec` écrit le texte final assistant dans un fichier temp si on lui passe `--output-last-message <path>`, l'adaptateur insère ce flag automatiquement et lit la réponse depuis le fichier même si stdout est bruyant.
+
+## Installation
+
+```bash
+npm install -g @openai/codex
+codex login                     # ou OPENAI_API_KEY headless
+codex exec "hello"
+```
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=codex
+CODEX_COMMAND="codex exec"
+AGENT_PROJECT_CONTEXT="Ce qu'on fait, ce qui est déjà tranché."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` est inutilisé (Codex `exec` est stateless).
+
+## Capture de sortie
+
+Pour Codex, l'adaptateur :
+
+1. Génère `verbalcoding-codex-last-<pid>-<ts>.txt` dans `os.tmpdir()`.
+2. Insère `--output-last-message <path>` juste avant l'argument final.
+3. Après exécution, lit ce fichier comme réponse de référence (prioritaire sur stdout).
+4. Supprime le fichier temp.
+
+Même si Codex pollue stdout, la voix joue toujours la réponse capturée.
+
+## Phrases vocales pour basculer vers Codex
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- fr: `"passe à Codex"`, `"demande à Codex"`
+
+## Pièges
+
+- **Tâches longues.** Mettez `AGENT_TASK_TIMEOUT_MS=0` pour la génération sur plusieurs minutes ; `signal.aborted` est respecté, le barge-in coupe net.
+- **Pas de reprise.** Continuité via `AGENT_PROJECT_CONTEXT` et bloc de handoff.
+- **Sortie type patch.** En cas d'interruption durant un diff, on annonce "interrompu" sans lire le diff.
+- **Auth.** Un 401 ressort en exit non-nul ; fallback vers le défaut si Codex n'était pas le défaut.

package/docs/i18n/HARNESS_CODEX.ja.md

@@ -0,0 +1,56 @@
+# Codex — ハーネスノート
+
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="HARNESSES.ja.md">ハーネス</a> ·
+  <a href="USAGE.ja.md">使い方</a> ·
+  <a href="CONFIGURATION.ja.md">設定</a>
+</p>
+
+Codex CLI は OpenAI のターミナルコーディングエージェント。VerbalCoding は `codex exec` で呼び出します。`codex exec` は `--output-last-message <path>` 付与時に最終応答を一時ファイルへ書くため、アダプタが自動でこのフラグを差し込み、stdout が騒がしくても確実にファイルから読み取ります。
+
+## インストール
+
+```bash
+npm install -g @openai/codex
+codex login              # ヘッドレスなら OPENAI_API_KEY
+codex exec "hello"
+```
+
+## VerbalCoding 設定
+
+```bash
+# .env
+AGENT_BACKEND=codex
+# 任意
+CODEX_COMMAND="codex exec"                      # 既定
+AGENT_PROJECT_CONTEXT="作業内容と既決定事項。"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` は未使用 (Codex `exec` は呼び出し間 stateless)。
+
+## 出力キャプチャ
+
+Codex 用にアダプタは:
+
+1. `os.tmpdir()` 配下に `verbalcoding-codex-last-<pid>-<ts>.txt` を作成。
+2. 最終 prompt 引数の直前に `--output-last-message <path>` を挿入。
+3. 実行後そのファイルを応答として読み取り (stdout より優先)。
+4. 一時ファイルを削除。
+
+Codex が stdout にツール使用ログを出しても、音声化される答えは常にキャプチャ済ファイル基準。
+
+## Codex へ切り替える音声表現
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- ja: `"Codex に切り替えて"`, `"Codex に聞いて"`
+
+## 罠
+
+- **長時間タスク。** 分単位のコード生成には `AGENT_TASK_TIMEOUT_MS=0`。アダプタが `signal.aborted` を尊重するので barge-in は綺麗に切れます。
+- **セッション再開なし。** `AGENT_PROJECT_CONTEXT` で文脈を渡し、ルート変更後の連続性はクロスエージェントハンドオフブロックに任せる。
+- **patch 出力安全策。** ターン中断時に Codex が diff 途中だった場合、bridge は diff を読み上げず "中断" 通知のみ、テキストチャンネル確認を促す。
+- **認証。** OpenAI 401 は非零 exit。既定外なら fallback プロンプトが既定エージェントへの retry 提案。

package/docs/i18n/HARNESS_CODEX.ko.md

@@ -0,0 +1,56 @@
+# Codex — 하니스 노트
+
+<p align="center">
+  <a href="../../README.ko.md">README</a> ·
+  <a href="HARNESSES.ko.md">하니스</a> ·
+  <a href="USAGE.ko.md">사용법</a> ·
+  <a href="CONFIGURATION.ko.md">설정</a>
+</p>
+
+Codex CLI는 OpenAI의 터미널 코딩 에이전트. VerbalCoding은 `codex exec`로 호출해. `codex exec`는 `--output-last-message <path>`를 주면 최종 어시스턴트 텍스트를 임시 파일에 써주는데, 어댑터가 이 플래그를 자동으로 끼워 넣고 stdout이 시끄러워도 파일에서 답변을 읽어와.
+
+## 설치
+
+```bash
+npm install -g @openai/codex
+codex login              # 또는 헤드리스용으로 OPENAI_API_KEY 설정
+codex exec "hello"
+```
+
+## VerbalCoding 설정
+
+```bash
+# .env
+AGENT_BACKEND=codex
+# 선택
+CODEX_COMMAND="codex exec"                      # 기본값
+AGENT_PROJECT_CONTEXT="작업 중인 내용과 이미 결정된 사항."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE`은 미사용 (Codex `exec`는 호출 간 stateless).
+
+## 출력 캡처
+
+Codex 어댑터는:
+
+1. `os.tmpdir()` 아래 `verbalcoding-codex-last-<pid>-<ts>.txt` 같은 임시 경로를 만들고
+2. 최종 prompt 인자 바로 앞에 `--output-last-message <path>`를 끼우고
+3. 실행 후 그 파일을 정답 답변으로 읽고 (stdout보다 우선)
+4. 임시 파일을 지워.
+
+Codex가 stdout에 tool-use chatter를 뿌려도 음성으로 나가는 답변은 항상 캡처된 파일 기준.
+
+## Codex로 전환하는 음성 표현
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- ko: `"코덱스로 전환"`, `"코덱스한테 물어봐"`
+
+## 함정
+
+- **긴 작업.** 분 단위 코드 생성을 위해 `AGENT_TASK_TIMEOUT_MS=0` 설정 권장. 어댑터가 `signal.aborted`를 존중하므로 barge-in은 깨끗하게 끊겨.
+- **세션 재개 없음.** `AGENT_PROJECT_CONTEXT`로 컨텍스트를 전달하고, 라우트 변경 후 연속성은 크로스 에이전트 핸드오프 블록에 맡겨.
+- **Patch 형식 출력 안전장치.** 턴이 interrupt됐고 Codex가 diff 중이었으면 bridge는 diff를 음성으로 읽지 **않고** "중단됨" 안내만 한 다음 텍스트 채널 확인을 권유해.
+- **인증.** OpenAI 백엔드의 401은 non-zero exit로 표면화. 기본 에이전트가 아니면 크로스 에이전트 fallback 프롬프트가 기본 에이전트로 재시도 제안.