verbalcoding 0.2.11 → 0.2.13

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 프롬프트가 기본 에이전트로 재시도 제안.

package/docs/i18n/HARNESS_CODEX.ru.md

@@ -0,0 +1,55 @@
+# Codex — Заметки по 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>
+
+Codex CLI — терминальный кодинг-агент OpenAI. VerbalCoding вызывает его через `codex exec`. Поскольку `codex exec` пишет финальный текст ассистента во временный файл при `--output-last-message <path>`, адаптер вставляет этот флаг автоматически и читает ответ из файла, даже если stdout шумный.
+
+## Установка
+
+```bash
+npm install -g @openai/codex
+codex login                     # либо OPENAI_API_KEY для headless
+codex exec "hello"
+```
+
+## Настройка
+
+```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. Создаёт временный путь `verbalcoding-codex-last-<pid>-<ts>.txt` в `os.tmpdir()`.
+2. Вставляет `--output-last-message <path>` прямо перед последним позиционным аргументом.
+3. После запуска читает этот файл как авторитетный ответ (приоритетнее stdout).
+4. Удаляет временный файл.
+
+Даже если Codex льёт tool-use в stdout, в голос идёт ответ из захваченного файла.
+
+## Голосовые фразы для переключения на Codex
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- ru: `"переключись на Codex"`, `"спроси Codex"`
+
+## Подводные камни
+
+- **Долгие задачи.** Ставьте `AGENT_TASK_TIMEOUT_MS=0` под кодогенерацию на минуты. `signal.aborted` уважается — barge-in режет чисто.
+- **Нет возобновления.** Передавайте контекст через `AGENT_PROJECT_CONTEXT`, после смены маршрута — блок hand-off.
+- **Защита от patch-вывода.** Если turn прерван во время diff, мост не зачитывает diff и отправляет в текстовый канал.
+- **Авторизация.** 401 идёт как non-zero exit; fallback на дефолт, если Codex не был дефолтом.

package/docs/i18n/HARNESS_CODEX.zh.md

@@ -0,0 +1,56 @@
+# Codex — 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>
+
+Codex CLI 是 OpenAI 的终端编码代理。VerbalCoding 通过 `codex exec` 驱动。`codex exec` 在带 `--output-last-message <path>` 时会把最终助手文本写到临时文件,适配器会自动插入此标志,并从文件可靠读取答案,即便 stdout 嘈杂。
+
+## 安装
+
+```bash
+npm install -g @openai/codex
+codex login              # 或 headless 设 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` 跨调用无状态)。
+
+## 输出抓取
+
+针对 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"`
+- zh: `"切到 Codex"`、`"问 Codex"`
+
+## 坑
+
+- **长任务。** 长达分钟级的代码生成需要 `AGENT_TASK_TIMEOUT_MS=0`。适配器尊重 `signal.aborted`,barge-in 切得干净。
+- **无会话续接。** 用 `AGENT_PROJECT_CONTEXT` 传递上下文,路由变化后的连续性靠跨代理 handoff 块。
+- **patch 输出安全。** 中断时若 Codex 正发 diff,bridge 不会朗读 diff,只播报 "已中断" 并提示查看文本频道。
+- **认证。** OpenAI 后端 401 以非零退出;非默认后端时 fallback 提示改用默认代理。

package/docs/i18n/HARNESS_CURSOR.es.md

@@ -0,0 +1,42 @@
+# Cursor CLI — 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>
+
+Cursor CLI (`cursor-agent`) es el agente de terminal de Cursor. VerbalCoding lo invoca con `cursor-agent --print --prompt`, pasando la transcripción como valor de `--prompt`. `--print` mantiene la corrida no interactiva.
+
+## Instalación
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # alias 'cursor-cli' aceptado
+CURSOR_COMMAND="cursor-agent --print --prompt"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Frases de voz para cambiar a Cursor
+
+- en: `"switch to Cursor"`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- es: `"cambia a Cursor"`
+
+Alias: `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## Trampas
+
+- **Posición del prompt.** `--prompt` espera el valor a continuación; el constructor de argv coloca la transcripción al final, así que `CURSOR_COMMAND` debe terminar en `--prompt`.
+- **Efectos colaterales del editor.** Cursor CLI puede tocar ficheros de estado en el cwd; aísla con `AGENT_WORKDIR`.
+- **Sin reanudación.** `AGENT_PROJECT_CONTEXT` + bloque de handoff para continuidad.
+- **Patch safety.** Si se interrumpe en medio de un diff, no se lee en voz.

package/docs/i18n/HARNESS_CURSOR.fr.md

@@ -0,0 +1,42 @@
+# Cursor CLI — 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>
+
+Cursor CLI (`cursor-agent`) est l'agent terminal de Cursor. VerbalCoding l'invoque via `cursor-agent --print --prompt`, en passant la transcription comme valeur de `--prompt`. `--print` maintient le run non interactif.
+
+## Installation
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # alias 'cursor-cli' accepté
+CURSOR_COMMAND="cursor-agent --print --prompt"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Phrases vocales pour basculer vers Cursor
+
+- en: `"switch to Cursor"`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- fr: `"passe à Cursor"`
+
+Alias : `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## Pièges
+
+- **Position du prompt.** `--prompt` attend la valeur juste après ; le builder argv place la transcription en dernier, donc `CURSOR_COMMAND` doit se terminer par `--prompt`.
+- **Effets de bord éditeur.** Cursor CLI peut toucher des fichiers d'état dans le cwd ; isolez via `AGENT_WORKDIR`.
+- **Pas de reprise.** `AGENT_PROJECT_CONTEXT` + bloc de handoff pour la continuité.
+- **Patch safety.** Aucune lecture vocale du diff en cas d'interruption.