@kyo-so/cli 0.9.1 → 0.11.0

package/.agents/skills/kyoso-review/SKILL.md

@@ -45,6 +45,16 @@ Do not use this skill for every coding task. It is intended for deliberate revie
    - The CLI also accepts `--repo-summary`, repeatable `--constraint`, and repeatable `--file` flags. For a large review, adjust an agent timeout with `--set agents.<agent>.timeoutMs=<ms>`.
    - Run the CLI without a config trust flag first. Inspect `audit.warnings` in the JSON result; if it contains `untrusted config was not executed`, or the command fails with an untrusted-config message, ask the user whether to rerun with `--trust-config` to use it or `--ignore-config` to skip it. Never add `--trust-config` without confirmation.
    - Keep `--json` enabled and interpret the returned `decision` exactly like the MCP result.
-5. Treat `decision: block` as a stop signal. Present the result to the user before implementing.
-6. Treat `decision: approve_with_changes` as requiring changes to the plan or implementation.
-7. Do not claim Kyoso modified files. Kyoso only reviews.
+5. Apply the [review-pass stop contract](#review-pass-stop-contract) before deciding whether to run another review.
+6. Treat `decision: block` as a stop signal. Present the result to the user before implementing.
+7. Treat `decision: approve_with_changes` as requiring changes to the plan or implementation.
+8. Do not claim Kyoso modified files. Kyoso only reviews.
+
+## Review-pass stop contract
+
+- At one explicit review checkpoint, run one automatic review pass only.
+- Record the returned `requestFingerprint`. Do not run the same fingerprint again in the same task.
+- If `completion.status !== "complete"`, stop. Present the incomplete result; do not retry the same command or enter a finding-fix loop.
+- A single confirmation pass is allowed only after fixing actionable, material findings from the first complete pass.
+- After the confirmation pass, stop even when findings remain. Do not start a third pass without the user's explicit approval.
+- Do not interpret `approve_with_changes` as permission to repeat until `approve`.

package/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-15
+
+### Added
+
+- User-global review execution budgets with lower-only request overrides,
+  absolute deadlines, streamed ACP text-output caps (including thought chunks), token-usage accounting,
+  request fingerprints, and structured incomplete-review results.
+- Audit events and JSON/Markdown budget reporting for planned, consumed, and
+  skipped model calls, wall time, output bytes, token-usage state, and review
+  completion reasons.
+- A two-pass stop contract for the bundled Kyoso review Skill: one initial
+  review plus one confirmation after material fixes, with fingerprint-based
+  duplicate prevention and explicit approval required for a third pass.
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.4.0`, pin its Codex and Claude Code MCP
+  definitions to `@kyo-so/cli@0.10.0`, and allow clients to forward
+  `OPENROUTER_API_KEY` by name for the existing OpenRouter project opt-in.
+- Default the Judge to deterministic-only mode. An LLM Judge now requires an
+  explicit `deterministic_plus_llm` opt-in and shares the review call budget.
+
+## [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

package/README.ja.md

@@ -30,11 +30,11 @@ 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 以降が必要です。
 
 ### 導入モード
 
@@ -44,14 +44,18 @@ backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに
 | CLI＋Skill-only    | npm CLI＋Skill           | なし | Codex／Claude Code |
 | 手動setup          | 手動MCP登録＋Skill       | あり | Codex／Claude Code |
 
-迷ったらMarketplace Pluginを選んでください。2コマンドでSkillとMCP serverをまとめて導入できます。手順は下の[Codex](#codex)／[Claude Code](#claude-code)節を参照してください。
+迷ったらMarketplace Pluginを選んでください。2コマンドでSkillとMCP serverをまとめて導入できます。手順は下の[Codex](#codex)／[Claude Code](#claude-code)節を参照してください。導入モードを後から切り替える場合は[移行](#移行)を参照してください。
 
 #### Marketplace Plugin
 
 PluginはSkillと公開済みのKyoso CLIの完全一致versionへpinしたMCP定義を同梱しますが、CLI本体は同梱しません。MCPの初回起動ではnpmへのnetwork accessが必要です。cache済みpackageでoffline起動できる場合はありますが、保証しません。manifestの`Read` capabilityは表示metadataであり、filesystem認可を追加するものではありません。
 
+`kyoso setup ... --with-openrouter` の出力と手動セットアップ例は、引き続き利用者が管理するクライアント登録テンプレートです。Marketplace Plugin `0.4.0` は `@kyo-so/cli@0.10.0` へpinしています。
+
 PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
 
+Marketplace Plugin `0.4.0` はMCP processへ`OPENROUTER_API_KEY`の変数名を公開しますが、credential値は保存しません。KyosoはOpenRouterを明示選択したCodex childだけへ値を転送し、展開されていないplaceholderは未設定として扱います。
+
 #### CLI＋Skill-only
 
 ```bash
@@ -68,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 認証を準備します。
@@ -141,31 +130,7 @@ 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/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"
-```
+Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否されることがあります。個人設定で事前承認する方法は [Codex approval prompts](#codex-approval-prompts) を参照してください。
 
 3. または、MCP を登録して review skill をインストールします。
 
@@ -189,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
@@ -298,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
-
-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 を変更できません。
+## Configuration
 
-Finding title は aggregation のため簡潔な英語に正規化されます。evidence、recommendations、summaries はユーザーの言語のままで構いません。
+### Files and precedence
 
-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) を参照してください。
 
@@ -357,53 +296,116 @@ 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 をサポートします。
+
+- `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` |
+
+`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: default の `deterministic_only` mode は API key を必要としません([Judge](#judge) を参照)
+- 明示的な LLM judge opt-in を無効化するには、`judge.mode = "deterministic_only"` または `judge.provider = "none"` を設定
+
+Team admins は organization Usage credits も確認してください。Credits が有効な場合、subscription limits を超える billing behavior は Kyoso の外側で制御されます。
 
-Default agent timeouts は Codex 120 秒、Claude 300 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
+### Single-backend mode
 
-Optional finding verification は default で disabled です:
+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 は利用できます。
+
+### Execution budget and review stopping
+
+各 review には、model call数、総 wall time、streaming中のagent text（message / thought chunk）、agentあたりのfinding数に user-global の hard ceiling があります。
+
+```toml
+[reviewBudget]
+maxModelCalls = 4
+maxTotalWallTimeMs = 480000
+maxAgentOutputBytes = 65536
+maxFindingsPerAgent = 10
+skipOptionalPhasesWhenTokenUsageUnknown = true
+```
+
+`reviewBudget` は user-global 専用です。project `kyoso.toml` と `--set` では変更できません。MCP / library request は `options.reviewBudget` で ceiling を下げることだけができ、引き上げはできません。Kyoso は primary reviewer を両方予約してから開始し、残りのcallだけを verification に使い、LLM Judge は advisory として扱います。既定のJudge modeは `deterministic_only` です。
+
+結果には `completion`、`executionBudget`、`requestFingerprint` が含まれます。Markdown と Audit は call数、wall time、output bytes、reported / unknown token usage を示します。`completion.status` が `incomplete` の場合、Kyoso は `retryable: false` の通常の `block` 結果を返します。これは code defect の断定ではなく、review coverage が未完了であることを意味します。同じ fingerprint を自動 retry しないでください。同一review checkpointでは、bundled Skill は初回1 passと material fix後の確認1 passだけを許可し、3回目には明示的な user approval が必要です。
+
+### Verification
+
+Verification keys: `verification.<enabled|maxFindings|timeoutMs>`。Optional finding verification は default で disabled です:
 
 ```toml
 [verification]
@@ -414,9 +416,11 @@ timeoutMs = 90000
 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 です。
+Enabled の場合、Kyoso は high/critical かつ single-source の各 finding について、その finding を報告していない agent に反証を試みさせます。Phase 1 は annotate-only で、verification は finding confidence と notes を更新できますが、severity は変更しません。verification が skip / fail / budget不足 / overflow の場合は finding を `not_verified` にし、coverage incomplete を返します。`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 で、default は `mode = "deterministic_only"` です。credential だけでは judge call を開始しません。OpenAI judge は `mode = "deterministic_plus_llm"` と `OPENAI_API_KEY` または `CODEX_API_KEY`、Anthropic judge は同modeと `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`
@@ -424,23 +428,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 秒です。review全体のdeadlineは既定480秒で、各phaseはdeadlineを延長せず残り時間を使います。MCP clients は tool calls に少なくとも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 `0.4.0`以降はこの変数名をKyoso processへ転送し、それ以前のversionは転送しません。既存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 を保持します。