npm - @kyo-so/cli - Versions diffs - 0.9.0 → 0.10.0 - Mend

@kyo-so/cli 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/CHANGELOG.md +71 -0
package/README.ja.md +225 -123
package/README.md +225 -126
package/README.zh-CN.md +225 -123
package/dist/acp/AcpAgentProcess.d.ts +2 -1
package/dist/acp/FakeAgentManager.d.ts +1 -1
package/dist/bin/kyoso.js +35895 -34770
package/dist/cli/openRouterAcpSmoke.d.ts +25 -0
package/dist/cli/pluginRuntimeContract.d.ts +4 -4
package/dist/cli/setup.d.ts +3 -2
package/dist/config/loadConfig.d.ts +19 -0
package/dist/config/projectScope.d.ts +1 -1
package/dist/config/schema.d.ts +9 -0
package/dist/core/constants.d.ts +1 -1
package/dist/core/types.d.ts +1 -0
package/dist/index.js +580 -111
package/dist/utils/env.d.ts +13 -0
package/examples/codex-config.toml +4 -1
package/examples/kyoso.toml +14 -0
package/package.json +4 -3

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.10.0] - 2026-07-15
+### Added
+- User-authorized project-scoped `agents.codex.provider = "openrouter"` and
+  inherited OpenRouter model overrides, with a required non-empty Codex model
+  for provider selection and a user-global exact absolute-directory
+  `allowProjectProvider` allowlist,
+  a `provider = "default"` project opt-out that clears an inherited OpenRouter
+  model unless the reset layer supplies one, and a fixed OpenRouter Responses
+  API preset.
+- OpenRouter readiness in `kyoso doctor`, including detected/missing key
+  guidance without exposing credential values.
+- `kyoso setup --with-openrouter` for explicit `OPENROUTER_API_KEY` forwarding
+  in newly generated manual Codex and Claude Code MCP registrations. New Codex
+  registrations also include `CODEX_HOME` and `CODEX_ACCESS_TOKEN` alongside
+  the existing credential allowlist.
+- A release-gated pinned Codex ACP/OpenRouter smoke command that requires an
+  explicit environment opt-in and never accepts credentials through argv.
+### Changed
+- Forward `OPENROUTER_API_KEY` to the Codex child only for the OpenRouter
+  provider; omit the provider to retain existing Codex login, OpenAI/Codex key,
+  and `CODEX_CONFIG` behavior.
+- Preserve existing MCP registrations during setup, including disabled entries;
+  existing users update their environment allowlist manually.
+- Omit `OPENROUTER_API_KEY` from new manual MCP registrations unless
+  `--with-openrouter` is explicitly requested.
+- Keep the released Marketplace Plugin environment contract unchanged: it does
+  not forward `OPENROUTER_API_KEY` until a later coordinated Plugin
+  promotion.
+### Fixed
+- Require the explicit `--set` provider and model pair when direct CLI input
+  selects OpenRouter, preventing a project-supplied model from completing that
+  external-routing selection.
+- Resolve existing project allowlist directories by real path and document
+  intentional preflight-only audit completion events.
+## [0.9.1] - 2026-07-13
+### Added
+- Claude Code Marketplace Plugin distribution with a shared Kyoso Skill and
+  version-pinned local stdio MCP server.
+- Best-effort post-publish reminders when either Plugin CLI pin lags the
+  released CLI version.
+### Changed
+- Move the Codex Plugin MCP definition to
+  `plugins/kyoso/.codex-plugin/mcp.json` so it cannot be auto-discovered by
+  Claude Code as a Plugin-root `.mcp.json`.
+- Document opt-in per-tool approval settings for avoiding Kyoso rejections in
+  Codex Auto mode, including the risk of sending selected code and review
+  context to configured external model providers. The Plugin keeps approvals
+  disabled by default.
+- Update the default `@agentclientprotocol/claude-agent-acp` adapter from
+  `0.57.0` to `0.58.1` for resumed-session model preservation, cancelled-turn
+  usage reporting, and streamed-thinking robustness.
+- Update `@modelcontextprotocol/server` from `2.0.0-beta.2` to
+  `2.0.0-beta.3`, restoring legacy `CallToolResult` parsing tolerance and
+  incorporating transport and authentication validation fixes.
+### Fixed
+- Updated the pinned Codex ACP adapter to `1.1.2`, whose bundled Codex model
+  catalog advertises reasoning-effort options for `gpt-5.6` family models.
 ## [0.9.0] - 2026-07-11
 ### Added

package/README.ja.md CHANGED Viewed

@@ -30,36 +30,31 @@ Kyoso はコード変更を適用しません。
   <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-review-flow.ja.svg" alt="Kyo-so のレビュー実行フロー。MCP/CLI リクエストから secret scan、スナップショット、アンサンブルレビュー、集約、ゲート、最終決定まで" width="640">
 </p>
-backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに 1 agent が `combined_reviewer` として実行されます。この図の Mermaid ソースは [docs/assets/](docs/assets/) にあります。
+backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに 1 agent が `combined_reviewer` として実行されます([Single-backend mode](#single-backend-mode) を参照)。この図の Mermaid ソースは [docs/assets/](docs/assets/) にあります。
 ## Quick Start
-グローバルインストールは不要です。Kyoso は `npx` または `bunx` で実行します。
+グローバルインストールは不要です。Kyoso は `npx` または `bunx` で実行します。パッケージ化された CLI を実行するには Node.js 20 以降が必要です。
 ### 導入モード
 | モード             | 導入物                   |  MCP | 対象               |
 | ------------------ | ------------------------ | ---: | ------------------ |
-| Marketplace Plugin | Skill＋ローカルstdio MCP | あり | Codex              |
+| Marketplace Plugin | Skill＋ローカルstdio MCP | あり | Codex／Claude Code |
 | CLI＋Skill-only    | npm CLI＋Skill           | なし | Codex／Claude Code |
 | 手動setup          | 手動MCP登録＋Skill       | あり | Codex／Claude Code |
-#### Codex Marketplace Plugin
+迷ったらMarketplace Pluginを選んでください。2コマンドでSkillとMCP serverをまとめて導入できます。手順は下の[Codex](#codex)／[Claude Code](#claude-code)節を参照してください。導入モードを後から切り替える場合は[移行](#移行)を参照してください。
-```bash
-codex plugin marketplace add hokupod/kyoso
-codex plugin list --marketplace kyoso --available --json
-codex plugin add kyoso@kyoso
-codex plugin list --marketplace kyoso --json
-```
-Codex desktopのPlugins pageまたは`/plugins`からKyosoを選ぶこともできます。追加したMarketplaceが見えない場合はdesktop appをrefresh／restartしてください。削除は`codex plugin remove kyoso@kyoso`です。
+#### Marketplace Plugin
 PluginはSkillと公開済みのKyoso CLIの完全一致versionへpinしたMCP定義を同梱しますが、CLI本体は同梱しません。MCPの初回起動ではnpmへのnetwork accessが必要です。cache済みpackageでoffline起動できる場合はありますが、保証しません。manifestの`Read` capabilityは表示metadataであり、filesystem認可を追加するものではありません。
-PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。Codex Auto modeでは、Kyoso toolsがannotationsを宣言していないため、最初のMCP呼び出しでapprovalが必要になることがあります。以後も許可する場合は「Allow and don't ask me again」を選択してください。
+`kyoso setup ... --with-openrouter` の出力と手動セットアップ例は、利用者が管理するクライアント登録テンプレートであり、Marketplace Plugin の manifest を変更・定義するものではありません。Stage A では同 manifest の公開済み CLI pin と環境契約を固定し、変更は Stage B の promotion でのみ行います。
+PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
-同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
+次回のPlugin promotionまでは、公開済みMarketplace Pluginは`OPENROUTER_API_KEY`を転送しません。OpenRouterのproject opt-inには、manual MCP registrationを伴うCLI／source経路を使ってください。この制約はpromotion後に対応Plugin versionの記載へ置き換えます。
 #### CLI＋Skill-only
@@ -77,21 +72,6 @@ Claude Codeでは`codex`を`claude-code`へ置き換えます。既定はdry-run
 Skill-onlyは意図的にMCP dependencyを宣言しません。`npx`または`bunx`のpackage-runner fallbackに到達すると、Codex Auto modeはsandbox network escalation approvalを要求することがあります。PATH上に`kyoso`を導入すると、このfallbackを避けられます。
-#### 移行
-- 手動MCPからCLI＋Skill: CLIとSkillを先に導入し、`codex mcp remove kyoso`または`claude mcp remove kyoso --scope local|project|user`を実行します。
-- CLI＋SkillからPlugin: Pluginを追加してenabledを確認してから、手動MCP登録を削除します。手動コピーSkillは自動削除しません。
-- PluginからCLI＋Skill: CLIとSkillを先に導入し、`codex plugin remove kyoso@kyoso`を実行します。
-- CLI＋Skillから手動MCPへ戻す: `kyoso setup codex --write`または`kyoso setup claude-code --write`を実行します。
-### Claude Only / Codex Only
-Kyoso は Claude だけ、または Codex だけでも実行できます。利用できない backend は `kyoso.toml` で無効化してください。例は `examples/claude-only.toml` と `examples/codex-only.toml` にあります。
-single-agent mode では、残った backend が `combined_reviewer` として 1 回だけ実行され、implementation と architecture/security の両方を確認します。JSON output には `reviewMode: "single_agent"` と `agentsUsed` が入り、Markdown output には cross-model verification が行われていないことと disagreements が N/A であることを表示します。
-この mode では独立した cross-model validation はなく、自己レビュー bias が残ります。一方で、別プロセスの read-only review、temporary snapshots、adversarial review prompts、secret scanning、deterministic gates は利用できます。
 ### Claude Code
 1. Claude 認証を準備します。
@@ -102,21 +82,32 @@ claude setup-token
 このコマンドで得た `CLAUDE_CODE_OAUTH_TOKEN` を設定するか、直接 API 課金を使う場合は `ANTHROPIC_API_KEY` を設定します。
-2. MCP を登録し、review skill をインストールします。
+2. Marketplace Plugin を導入します(推奨)。
+```text
+/plugin marketplace add hokupod/kyoso
+/plugin install kyoso@kyoso
+```
+Plugin は Kyoso review Skill と、公開済み CLI version に pin したローカル stdio MCP server を導入します。Plugin で導入した場合、`kyoso setup claude-code` は不要です。
+3. または、MCP を登録して review skill をインストールします。
 ```bash
 npx @kyo-so/cli setup claude-code --write
 bunx @kyo-so/cli setup claude-code --write
 ```
-3. セットアップを確認します。
+手動で MCP を登録する場合は、`examples/claude-code-mcp.json` を使用します。
+4. セットアップを確認します。
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
-4. Claude Code からレビューを依頼します。
+5. Claude Code からレビューを依頼します。
 ```text
 Use Kyoso plan_review on this plan before implementation.
@@ -130,21 +121,32 @@ Use Kyoso plan_review on this plan before implementation.
 codex login
 ```
-2. MCP を登録し、review skill をインストールします。
+2. Marketplace Plugin を導入します(推奨)。
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin add kyoso@kyoso
+```
+Codex desktopのPlugins pageまたは`/plugins`からKyosoを選ぶこともできます。追加したMarketplaceが見えない場合はdesktop appをrefresh／restartしてください。確認は`codex plugin list --marketplace kyoso --json`、削除は`codex plugin remove kyoso@kyoso`です。Plugin で導入した場合、`kyoso setup codex` は不要です。
+Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否されることがあります。個人設定で事前承認する方法は [Codex approval prompts](#codex-approval-prompts) を参照してください。
+3. または、MCP を登録して review skill をインストールします。
 ```bash
 npx @kyo-so/cli setup codex --write
 bunx @kyo-so/cli setup codex --write
 ```
-3. セットアップを確認します。
+4. セットアップを確認します。
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
-4. Codex からレビューを依頼します。
+5. Codex からレビューを依頼します。
 ```text
 Use Kyoso diff_review on the current diff. I need a second opinion before merging.
@@ -152,34 +154,9 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 手動セットアップ用の例は `examples/codex-config.toml` と `examples/claude-code-mcp.json` にあります。
-## Install / Run
-```bash
-npx @kyo-so/cli mcp
-bunx @kyo-so/cli mcp
-```
-Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
-ローカル開発:
-```bash
-nix develop
-safe-chain bun install
-safe-chain bun run typecheck
-safe-chain bun test
-safe-chain bun run build
-```
-パッケージ化された CLI を実行するには Node.js 20 以降が必要です。
-Nix dev shell は Node.js 24 と nixpkgs が提供する Bun version を固定します。`.envrc` を確認してから `direnv allow` を一度実行すると、自動で shell を読み込めます。CI は Bun 1.3.14 に pin したままです。現在の nixpkgs Bun version は少し異なる場合がありますが、`flake.lock` により local shell の再現性を保ちます。
-既知の配布リスク: `@modelcontextprotocol/server` にはまだ stable release がありません。Kyoso は現在 prerelease API を pin しているため、MCP SDK API の変更に追従する follow-up release が必要になる場合があります。
 ## CLI
-通常の実行経路は `npx @kyo-so/cli` と `bunx @kyo-so/cli` です。以下の例では、この prefix を `kyoso` と省略しています。
+通常の実行経路は `npx @kyo-so/cli` と `bunx @kyo-so/cli` です。以下の例では、この prefix を `kyoso` と省略しています。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -261,45 +238,44 @@ Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools
 managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのSkill directoryだけを置換し、MCP設定を削除・上書きしません。
-## Safety Model
+## Configuration
-Kyoso MVP は disposable temporary snapshot と policy-level write denial を使用します。完全な OS sandbox ではありません。リスクを理解していない場合、untrusted repositories に対して Kyoso を実行しないでください。
-Secret detection は best-effort です。Kyoso は request、selected files、diff 内で secret らしき値を検出すると、その値を redact し、既定では backend agents の実行前に block します。
+### Files and precedence
-Kyoso は provider credentials を保存しません。Child agent environment variables は allowlist されます。
-Repository content、plans、diffs、selected files は backend prompts 内で untrusted data として扱われます。Kyoso はそれらを `<untrusted-content>` tags で包み、その中にある instructions に従わないよう agents に指示します。最終判断は schema-constrained findings から導出されます。agents は files の書き込みや commands の実行ができず、judge は deterministic decision を変更できません。
-Finding title は aggregation のため簡潔な英語に正規化されます。evidence、recommendations、summaries はユーザーの言語のままで構いません。
-Audit trace は workspace が制御するpathではなく、trusted user state root 配下へ書き込みます。対応するPOSIX runtimeでは、absoluteな`$XDG_STATE_HOME`が利用可能ならそれを、そうでなければ`$HOME/.local/state`を使用し、owner、permission、containment、symlinkを確認できた場合だけ書き込みます。検証またはsafe openに失敗した場合、別locationへ黙ってfallbackせず、そのreviewのAudit writeを無効化してsanitized warningを返し、review自体は継続します。
+Kyoso は次の順に config を load します。
-Windows、および必要なfilesystem capabilityを証明できない環境では、Audit writeをfail-closeで無効化します。trusted state rootを変更できる、または検証済みinodeをrenameできるsame OS user権限のhostile processはこの保証の対象外です。この脅威にはOS sandboxまたはnative dirfd-based supportが必要です。
+- built-in defaults
+- user global TOML: `$XDG_CONFIG_HOME/kyoso/config.toml`、または `~/.config/kyoso/config.toml`
+- project TOML: `<cwd>/kyoso.toml`
+- `--network` などの CLI flags と `--set agents.claude.effort=high` などの反復可能な overrides
-## Agent Auth
+`plan`、`security`、`diff` は、反復可能な `--set <key>=<value>` overrides を受け付けます。CLI で指定した値は config files より優先され、`--ignore-config` との併用も可能です。
-Codex は利用可能な場合、local `codex` login を使用します。既定の subscription-backed path では API key は不要です。
+未知の key は拒否されます。boolean / numeric config keys は schema の型へ変換し、string keys は文字列のまま保持した後、config 全体を再検証します。
-Claude は 2 つの auth paths をサポートします。
+Project `kyoso.toml` は declarative で、trust approval は不要です。tools toggles、agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、user global authorization後のCodex専用`provider`または継承したOpenRouterのmodel上書き、workspace byte limits と additive `workspace.deny`、verification settings、advisory judge settings、tightening-only security/network settings を設定できます。
-- `ANTHROPIC_API_KEY`: direct Anthropic API billing
-- `CLAUDE_CODE_OAUTH_TOKEN`: `claude setup-token` から得る subscription auth
+Global TOML は command 実行や env forwarding を含む user-owned settings 用です。
-Claude credentials が両方設定されている場合、Kyoso は既定で `CLAUDE_CODE_OAUTH_TOKEN` だけを Claude child agent に forward します。`ANTHROPIC_API_KEY` だけを forward するには、`agents.claude.auth.preferApiKey: true` を設定してください。
+```toml
+[agents.codex]
+command = "bunx"
+args = ["@agentclientprotocol/codex-acp"]
+# この完全一致のproject directoryだけに`provider`選択、または継承した
+# OpenRouterのmodel上書きを許可します。
+allowProjectProvider = ["/absolute/path/to/project"]
-Default child-agent env allowlist:
+[agents.codex.env]
+CODEX_CONFIG = '{"model":"gpt-5.5"}'
+```
-| Agent  | Provider env                                                                                                                                                                                 |
-| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Codex  | `CODEX_API_KEY`, `OPENAI_API_KEY`, `CODEX_HOME`, `CODEX_ACCESS_TOKEN`                                                                                                                        |
-| Claude | `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL`, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` |
+`kyoso.config.ts` は deprecated ですが、互換性のため引き続き supported です。trust-on-first-use approval の後にのみ load され、trusted hashes は `~/.kyoso/trusted-configs.json` に保存されます。`kyoso.toml` と `kyoso.config.ts` が両方ある場合、Kyoso は TOML を使用し TypeScript config を無視します。
-Kyoso は subprocesses の起動に必要な最小限の runtime env も forward します: `PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `SHELL`, `USER`, `USERNAME`, `SystemRoot`。
+### Agents
-## Agent Models and Effort
+Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`。Codexには`agents.codex.provider`もあり、`"openrouter"`はexternal providerを選択し、`"default"`は継承したOpenRouter選択を通常のCodex behaviorへ戻します。Claudeにprovider設定はありません。`agents.codex.allowProjectProvider`はglobal config専用のabsolute project directory allowlistです。完全一致のproject TOMLだけが`provider`を選択、または継承したOpenRouterの`model`を上書きでき、descendantやglobには一致しません。project configと`--set`では変更できず、legacy boolean値は拒否します。`command` / `args` / `env`もglobal config専用です([Files and precedence](#files-and-precedence) を参照)。
-`agents.<name>.model` または `agents.<name>.effort` を省略すると、各 agent 独自の default を使用します。Codex は `~/.codex/config.toml` などの local Codex config を使用し、Claude は adapter default を使用します。
+`agents.<name>.model` または `agents.<name>.effort` を省略すると、各 agent 独自の default を使用します。Codex は `~/.codex/config.toml`（`CODEX_HOME`を設定している場合は`$CODEX_HOME/config.toml`）などの local Codex config を使用し、Claude は adapter default を使用します。
 指定できる model 名は [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview) と [Codex models](https://developers.openai.com/codex/models) を参照してください。
@@ -320,53 +296,99 @@ Kyoso は model pins を adapter-supported configuration に mapping します
 effort は仕組みが異なります。Kyoso は env var を設定せず、session ごとに最初の prompt の前に一度、backend agent へ ACP の `session/set_config_option` リクエストを送信します(Claude は `configId: "effort"`、Codex は `configId: "reasoning_effort"`)。有効な値は backend agent のバージョンと選択した model に依存します(例えば Claude は effort levels に対応した model でのみこの option を公開します)。Kyoso は `effort` の値自体を validate しません。backend agent がリクエストを reject した場合、または対応していない場合、Kyoso は stderr に log を出力してレビューを継続します。
-## Audit
+### Codex の OpenRouter project opt-in
-対応するPOSIX runtimeでは、Audit traces はuser state base（absoluteな`$XDG_STATE_HOME`、なければ`$HOME/.local/state`）配下の次の場所に書き込まれます。
+まずuser global configでproject-level OpenRouter routingを許可します。
-```text
-<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
+```toml
+# ~/.config/kyoso/config.toml
+[agents.codex]
+allowProjectProvider = ["/absolute/path/to/project"]
 ```
-`audit.directory`はlogicalなrelative directory（既定: `.kyoso/traces`）であり、workspace内のdirectoryではありません。既存のworkspace `.kyoso/traces`は自動で移行・削除されません。
+続けてOpenRouterが必要なprojectだけでopt-inします。
-Raw agent output と raw file contents は既定で無効です。`audit.includeRawAgentOutput`を有効にすると、traces に sensitive review output が残る場合があります。local retention policy に従って古い traces を削除してください。Windowsまたは安全なfilesystem capabilityを証明できない環境では、Audit trace writeは無効のままで、reviewはsanitized warningを返します。
+```toml
+# <project>/kyoso.toml
+[agents.codex]
+provider = "openrouter"
+model = "openai/o4-mini"
+```
-## Config
+`provider = "openrouter"` の場合、`model`は空白でない値が必須です。これはOpenRouterのmodel IDです。Kyosoはcatalogやtool calling対応を検証しないため、利用するmodelのtool supportはproviderで確認してください。
-Kyoso は次の順に config を load します。
+`allowProjectProvider`はprojectの`provider`と、OpenRouterを継承中のproject `model`上書きに必要で、listには解決後のproject config fileを含むcanonical directoryのabsolute pathを完全一致で指定します。invocationのcwdやlexical pathではありません。trusted `kyoso.config.ts`を含むproject config fileとallowlist entryの両方をsymlink経由も含めて同じdirectoryのreal pathへ解決して比較するため、そのdirectoryへ解決されるentryは一致し、別の場所へ解決されるentryまたは解決できないpathはfail closedです。user globalの`provider = "openrouter"`にはallowlist entryは不要です。CLIで選択する場合は、同一 invocation に`--set agents.codex.provider=openrouter`と`--set agents.codex.model=<model>`の両方が必要であり、project modelで前者を補完することはできません。`allowProjectProvider`は`--set` pathではなく、legacy boolean値は拒否されます。
-- built-in defaults
-- user global TOML: `$XDG_CONFIG_HOME/kyoso/config.toml`、または `~/.config/kyoso/config.toml`
-- project TOML: `<cwd>/kyoso.toml`
-- `--network` などの CLI flags と `--set agents.claude.effort=high` などの反復可能な overrides
+user global configがOpenRouterを選択している場合、projectは`provider = "default"`で明示的にopt-outできます。このresetにはmodelもauthorizationも不要で、同じlayerで通常のCodex modelを明示しない限り継承したOpenRouter modelも消去し、そのprojectではOpenRouter keyをforwardしません。
-`plan`、`security`、`diff` は、反復可能な `--set <key>=<value>` overrides を受け付けます。CLI で指定した値は config files より優先され、`--ignore-config` との併用も可能です。
+Kyosoを起動するCodexまたはClaude client processのenvironmentにkeyを設定します。直接のenvironment variableをprimary pathとし、1Passwordなどのsecret managerはoptionalでKyosoの依存ではありません。
-- Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`
-- Verification keys: `verification.<enabled|maxFindings|timeoutMs>`
-- Judge keys: `judge.<mode|provider|timeoutMs>`
+```bash
+export OPENROUTER_API_KEY="<secret>"
+```
-未知の key は拒否されます。boolean / numeric config keys は schema の型へ変換し、string keys は文字列のまま保持した後、config 全体を再検証します。
+keyは`kyoso.toml`、Git管理するconfig、Audit trace、review outputへ保存しません。KyosoはKyoso processまたは明示した`agents.codex.env`のいずれのsourceであっても、このproviderを選択した場合だけCodex childへ転送します。`provider`を省略するか`provider = "default"`の場合は、両方のsourceを意図的に転送しません。空でない明示的な`agents.codex.env.OPENROUTER_API_KEY`は、転送しなかったことを示すsanitized warningも出します。選択されたCodex OpenRouter childだけがkeyを受け取れるため、`agents.claude.env`など別のchild configurationに空でないkeyがある場合も同じwarningを出します。`provider`を省略すると既存のCodex login、`OPENAI_API_KEY`、`CODEX_API_KEY`、`CODEX_CONFIG`の挙動を維持し、行を削除するとその挙動へ戻ります。
-Project `kyoso.toml` は declarative で、trust approval は不要です。tools toggles、agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、workspace byte limits と additive `workspace.deny`、verification settings、advisory judge settings、tightening-only security/network settings を設定できます。
+GUI clientはshell exportを継承しない場合があります。新規manual MCP registrationは`kyoso setup <client> --write --with-openrouter`で作成し、clientを再起動してから`kyoso doctor`でKyoso processがkeyを検出できるか確認してください。`kyoso setup`は既存のMCP entryを再書換えせずに保持するため、既存registrationでは[examples](examples/codex-config.toml)を参照してopt-in allowlistを手動更新する必要があります。
-Global TOML は command 実行や env forwarding を含む user-owned settings 用です。
+新規manual MCP registrationは既定で`OPENROUTER_API_KEY`を含めません。providerを意図して選択した後だけ`--with-openrouter`で追加し、既存registrationは書換えません。Claude Code registrationの`${OPENROUTER_API_KEY}`はclientが展開する必要があり、Kyosoは`${NAME}`、`$NAME`、`%NAME%`（前後の空白は許容）だけから成る未展開credential placeholderだけを無視し、変数名だけを含むsanitized warningを出します。ほかの文字列を含む値は維持します。custom credential-like nameの末尾が`_KEY`、`_TOKEN`、`_SECRET`、`_PASSWORD`である場合にも同じ規則を適用し、credentialではないtemplateは維持されます。
-```toml
-[agents.codex]
-command = "bunx"
-args = ["@agentclientprotocol/codex-acp"]
+このuser-authorized project-scoped opt-inを推奨します。global `provider = "openrouter"`は、projectが`provider = "default"`を設定するまで継承されます。`provider`の省略だけでは解除されません。固定のOpenRouter Responses API presetはbetaです。custom endpoint、provider routing、fallback、judge integrationは公開しません。keyをこのpresetに束縛するため、OpenRouter modeではtop-levelの`profile`または`profiles`を含む`CODEX_CONFIG`と、objectではない`model_providers` valueをchild起動前に拒否します。objectの場合は`model_providers`を固定の`kyoso-openrouter` entryだけに置換し、破棄したentry数だけを含むsanitized warningを出します。provider IDやconfig valueは出力しません。拒否するfield以外では、`model`、`model_provider`、`model_providers`以外のunrelatedな`CODEX_CONFIG` fieldを維持するため、foreign provider configurationがkey付きのendpointを選択することはできません。Claudeは設定済みproviderのままで、judgeは`OPENROUTER_API_KEY`を使用しません。
-[agents.codex.env]
-CODEX_CONFIG = '{"model":"gpt-5.5"}'
+user global authorization後、projectの`kyoso.toml`はexternal providerを選択、または継承したOpenRouter modelを上書きし、review contextをそこへ送ることがあります。untrusted repositoryでは`--ignore-config`を使用し、必要なCLI optionsだけを明示してください。
+実際のCodex ACP/OpenRouter smokeはrelease-gatedであり、testでは実行しません。networkと課金が明示許可された後だけ、client environmentへkeyをexportして次を実行します。
+```bash
+KYOSO_OPENROUTER_ACP_SMOKE=release KYOSO_OPENROUTER_MODEL=<model> safe-chain bun run smoke:openrouter:codex-acp
 ```
-`kyoso.config.ts` は deprecated ですが、互換性のため引き続き supported です。trust-on-first-use approval の後にのみ load され、trusted hashes は `~/.kyoso/trusted-configs.json` に保存されます。`kyoso.toml` と `kyoso.config.ts` が両方ある場合、Kyoso は TOML を使用し TypeScript config を無視します。
+このcommandはCLI argumentsを受け付けず、pinしたCodex ACP adapterを使います。呼び出し元のrepositoryやcached Codex loginを利用しないよう、空のtemporary workspace、`HOME`、`CODEX_HOME`を新規作成し、key/modelをconfig・temporary artifact・outputへ書かずに固定の成功または失敗メッセージだけを返します。
+### Agent auth
+Codex は利用可能な場合、local `codex` login を使用します。既定の subscription-backed path では API key は不要です。
+Claude は 2 つの auth paths をサポートします。
-Default agent timeouts は Codex 120 秒、Claude 300 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
+- `ANTHROPIC_API_KEY`: direct Anthropic API billing
+- `CLAUDE_CODE_OAUTH_TOKEN`: `claude setup-token` から得る subscription auth
+Claude credentials が両方設定されている場合、Kyoso は既定で `CLAUDE_CODE_OAUTH_TOKEN` だけを Claude child agent に forward します。`ANTHROPIC_API_KEY` だけを forward するには、`agents.claude.auth.preferApiKey: true` を設定してください。
+Default child-agent env allowlist:
+| Agent  | Provider env                                                                                                                                                                                 |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codex  | `CODEX_API_KEY`, `OPENAI_API_KEY`, `CODEX_HOME`, `CODEX_ACCESS_TOKEN`                                                                                                                        |
+| Claude | `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL`, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` |
-Optional finding verification は default で disabled です:
+`OPENROUTER_API_KEY`は通常のCodex allowlistには意図的に含めません。`agents.codex.provider = "openrouter"`の場合だけKyoso processからcopyし、keyがないか空の場合はCodex childを起動せず、構造化されたagent failureとして返します。別reviewerはdegraded modeで継続できます。
+資格情報露出を最小化するため、OpenRouter modeでは`OPENAI_API_KEY`、`CODEX_API_KEY`、`CODEX_ACCESS_TOKEN`をCodex childから除外します。local adapter state用に`CODEX_HOME`は残ります。そのためadapterはlocal login cacheを読み取れ、これはcredential isolationではなくdefense in depthです。
+Kyoso は subprocesses の起動に必要な最小限の runtime env も forward します: `PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `SHELL`, `USER`, `USERNAME`, `SystemRoot`。
+Subscription-only setup:
+- Codex: local `codex` login を使用
+- Claude: `claude setup-token` を実行し、`CLAUDE_CODE_OAUTH_TOKEN` を設定
+- Judge: API keys を設定しないことで、Kyoso は `deterministic_fallback` を使用([Judge](#judge) を参照)
+- `OPENAI_API_KEY` が存在するときに OpenAI judge calls を避けるには、`judge.provider = "none"` を設定
+Team admins は organization Usage credits も確認してください。Credits が有効な場合、subscription limits を超える billing behavior は Kyoso の外側で制御されます。
+### Single-backend mode
+Kyoso は Claude だけ、または Codex だけでも実行できます。利用できない backend は `kyoso.toml` で無効化してください。例は `examples/claude-only.toml` と `examples/codex-only.toml` にあります。
+single-agent mode では、残った backend が `combined_reviewer` として 1 回だけ実行され、implementation と architecture/security の両方を確認します。JSON output には `reviewMode: "single_agent"` と `agentsUsed` が入り、Markdown output には cross-model verification が行われていないことと disagreements が N/A であることを表示します。
+この mode では独立した cross-model validation はなく、自己レビュー bias が残ります。一方で、別プロセスの read-only review、temporary snapshots、adversarial review prompts、secret scanning、deterministic gates は利用できます。
+### Verification
+Verification keys: `verification.<enabled|maxFindings|timeoutMs>`。Optional finding verification は default で disabled です:
 ```toml
 [verification]
@@ -379,7 +401,9 @@ allowDemotion = false
 Enabled の場合、Kyoso は high/critical かつ single-source の各 finding について、その finding を報告していない agent に反証を試みさせます。Phase 1 は annotate-only です。verification は finding confidence と notes を更新できますが、severity や final decision は変更しません。`allowDemotion` は future opt-in phase 用に予約されており、現時点では no-op です。
-Judge LLMs は optional です。OpenAI judge を使うには `OPENAI_API_KEY` または `CODEX_API_KEY` を設定し、Anthropic judge を使うには `ANTHROPIC_API_KEY` を設定します。Optional overrides:
+### Judge
+Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs は optional です。OpenAI judge を使うには `OPENAI_API_KEY` または `CODEX_API_KEY` を設定し、Anthropic judge を使うには `ANTHROPIC_API_KEY` を設定します。Optional overrides:
 - `OPENAI_BASE_URL`: OpenAI-compatible API base URL
 - `KYOSO_OPENAI_JUDGE_MODEL`: OpenAI judge model, default `gpt-5.4-mini`
@@ -387,23 +411,101 @@ Judge LLMs は optional です。OpenAI judge を使うには `OPENAI_API_KEY`
 Judge defaults は意図的に lightweight models を使用します。より強い judge を使う場合は、`KYOSO_ANTHROPIC_JUDGE_MODEL` に `claude-sonnet-5` のような Sonnet-class model を設定してください。
-Subscription-only setup:
+### Timeouts
-- Codex: local `codex` login を使用
-- Claude: `claude setup-token` を実行し、`CLAUDE_CODE_OAUTH_TOKEN` を設定
-- Judge: API keys を設定しないことで、Kyoso は `deterministic_fallback` を使用
-- `OPENAI_API_KEY` が存在するときに OpenAI judge calls を避けるには、`judge.provider = "none"` を設定
+Default agent timeouts は Codex 120 秒、Claude 300 秒です。verification round の default は 90 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
-Team admins は organization Usage credits も確認してください。Credits が有効な場合、subscription limits を超える billing behavior は Kyoso の外側で制御されます。
+### Audit
+対応するPOSIX runtimeでは、Audit traces はuser state base（absoluteな`$XDG_STATE_HOME`、なければ`$HOME/.local/state`）配下の次の場所に書き込まれます。
+```text
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
+```
+`audit.directory`はlogicalなrelative directory（既定: `.kyoso/traces`）であり、workspace内のdirectoryではありません。既存のworkspace `.kyoso/traces`は自動で移行・削除されません。
+Raw agent output と raw file contents は既定で無効です。`audit.includeRawAgentOutput`を有効にすると、traces に sensitive review output が残る場合があります。local retention policy に従って古い traces を削除してください。Windowsまたは安全なfilesystem capabilityを証明できない環境では、Audit trace writeは無効のままで、reviewはsanitized warningを返します([Safety Model](#safety-model) を参照)。
+## Safety Model
+Kyoso MVP は disposable temporary snapshot と policy-level write denial を使用します。完全な OS sandbox ではありません。リスクを理解していない場合、untrusted repositories に対して Kyoso を実行しないでください。
+Secret detection は best-effort です。Kyoso は request、selected files、diff 内で secret らしき値を検出すると、その値を redact し、既定では backend agents の実行前に block します。
+Kyoso は provider credentials を保存しません。Child agent environment variables は allowlist されます。
+Repository content、plans、diffs、selected files は backend prompts 内で untrusted data として扱われます。Kyoso はそれらを `<untrusted-content>` tags で包み、その中にある instructions に従わないよう agents に指示します。最終判断は schema-constrained findings から導出されます。agents は files の書き込みや commands の実行ができず、judge は deterministic decision を変更できません。
+Finding title は aggregation のため簡潔な英語に正規化されます。evidence、recommendations、summaries はユーザーの言語のままで構いません。
+Audit trace は workspace が制御するpathではなく、trusted user state root 配下へ書き込みます。対応するPOSIX runtimeでは、absoluteな`$XDG_STATE_HOME`が利用可能ならそれを、そうでなければ`$HOME/.local/state`を使用し、owner、permission、containment、symlinkを確認できた場合だけ書き込みます。検証またはsafe openに失敗した場合、別locationへ黙ってfallbackせず、そのreviewのAudit writeを無効化してsanitized warningを返し、review自体は継続します。
+Windows、および必要なfilesystem capabilityを証明できない環境では、Audit writeをfail-closeで無効化します。trusted state rootを変更できる、または検証済みinodeをrenameできるsame OS user権限のhostile processはこの保証の対象外です。この脅威にはOS sandboxまたはnative dirfd-based supportが必要です。
+## 移行
+- 手動MCPからCLI＋Skill: CLIとSkillを先に導入し、`codex mcp remove kyoso`または`claude mcp remove kyoso --scope local|project|user`を実行します。
+- CLI＋SkillからPlugin: Pluginを追加してenabledを確認してから、手動MCP登録を削除します。手動コピーSkillは自動削除しません。
+- PluginからCLI＋Skill: CLIとSkillを先に導入し、`codex plugin remove kyoso@kyoso`を実行します。
+- CLI＋Skillから手動MCPへ戻す: `kyoso setup codex --write`または`kyoso setup claude-code --write`を実行します。
 ## Troubleshooting
-- MCP timeout: client tool timeouts を少なくとも 360 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は Codex 120 秒、Claude 300 秒、verification 90 秒です。
+- MCP timeout: client tool timeouts を少なくとも 360 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は [Timeouts](#timeouts) を参照してください。
 - Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx @kyo-so/cli` の解決が一時的に block される場合があります。
 - Deprecated TypeScript config: `--trust-config` を渡さない限り、untrusted `kyoso.config.ts` は skip されます。新規設定は `kyoso.toml` を使ってください。
+- OpenRouter key missing: 空でないCodex `model`、Kyoso processへ転送された`OPENROUTER_API_KEY`、clientの再起動を確認し、`kyoso doctor`を実行してください。公開済みMarketplace Pluginは次回promotionまでこのkeyを転送せず、既存MCP registrationはsetupで再書換えされません。
+### Codex approval prompts
+Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否されることがあります。個人設定で事前承認するには、次を`~/.codex/config.toml`（`CODEX_HOME`を設定している場合は`$CODEX_HOME/config.toml`）へ追加します。**Kyosoを信頼し、選択したコードとレビュー用contextが設定済みの外部model providerへ送信されることを許容できる場合だけ設定してください。** Pluginの既定値では有効にしていません。
+```toml
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+Pluginではなく、MCP serverとして直接登録している場合（`kyoso setup codex --write` または手動設定）は、`plugins."kyoso@kyoso".` プレフィックスなしの `mcp_servers.kyoso` キーを使用します。
+```toml
+[mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+[mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+[mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
 ## Development
+ローカル開発:
+```bash
+nix develop
+safe-chain bun install
+safe-chain bun run typecheck
+safe-chain bun test
+safe-chain bun run build
+safe-chain bun run pack:verify
+```
+Nix dev shell は Node.js 24 と nixpkgs が提供する Bun version を固定します。`.envrc` を確認してから `direnv allow` を一度実行すると、自動で shell を読み込めます。CI は Bun 1.3.14 に pin したままです。現在の nixpkgs Bun version は少し異なる場合がありますが、`flake.lock` により local shell の再現性を保ちます。
+test suite は credential-free の MCP stdio と ACP subprocess の integration coverage を含みます。`pack:verify` はさらに、pack 済みの `dist/bin/kyoso.js` MCP server を起動し、published bundle の protocol handshake を確認します。
+既知の配布リスク: `@modelcontextprotocol/server` にはまだ stable release がありません。Kyoso は現在 prerelease API を pin しているため、MCP SDK API の変更に追従する follow-up release が必要になる場合があります。`@modelcontextprotocol/server`、`@agentclientprotocol/sdk`、または pin 済み ACP adapters を bump する release の前には、手動での real-agent dogfooding を実行してください。
+Debug 用の environment variables:
 - `KYOSO_TEST_FAKE_AGENTS=1`: test-only fake ACP agents; production では設定しないでください。
 - `KYOSO_KEEP_TEMP=1`: local debugging 用に temporary snapshots を保持します。