@kyo-so/cli 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.6.0] - 2026-07-08
+
+### Added
+
+- TOML config loading with XDG user-global layering:
+  `$XDG_CONFIG_HOME/kyoso/config.toml` or `~/.config/kyoso/config.toml`, then
+  project `kyoso.toml`.
+- Unknown-key detection for user-global `config.toml`; security-sensitive
+  unknown settings fail closed by default, with `--allow-unknown-config` as an
+  explicit opt-out.
+- Project TOML scope validation for repository-owned settings, including
+  additive `workspace.deny` and tightening-only security/network keys.
+- `kyoso doctor` now reports global, project TOML, and legacy TypeScript config
+  layers.
+
+### Changed
+
+- `kyoso init` now writes `kyoso.toml`.
+- `--config` now fails when the specified file does not exist.
+- Default Claude agent timeout raised from 240s to 300s; dogfooding traces
+  showed frequent reviews truncated at the previous limit.
+- Repository dogfooding config and examples now use TOML.
+
+### Deprecated
+
+- `kyoso.config.ts` remains supported through the existing trust flow, but emits
+  a deprecation warning. When both `kyoso.toml` and `kyoso.config.ts` exist,
+  TOML takes precedence.
+
+## [0.5.0] - 2026-07-08
+
+### Added
+
+- Cross-validation classification on aggregated findings: findings backed by
+  both agents are marked `corroborated`, single-agent findings `single_source`.
+- Fusion-style cross-model analysis from the advisory judge: blind spots,
+  semantic contradictions, and partial coverage are reported as advisory
+  metadata (`crossModelAnalysis`); the deterministic decision is unchanged.
+- Optional adversarial verification round (`verification.enabled`, default
+  off): single-source high/critical findings are sent to the other agent with
+  a skeptical refute-first prompt. Annotate-only: verdicts adjust confidence
+  and notes, never severity or the decision.
+- CI-ready MCP stdio and ACP subprocess integration tests now cover the real
+  protocol boundaries without live LLM credentials. `pack:verify` also starts
+  the packed CLI bin as an MCP server and checks its version and tool list.
+- Nix development shell pinning Node.js and Bun for reproducible local setups.
+
+### Changed
+
+- Reviewer prompts now require concise English finding titles (evidence,
+  recommendations, and summaries may stay in the user's language) and clarify
+  that selected files show the pre-change base state during diff reviews.
+- Same-category findings that reference overlapping line ranges in the same
+  file now merge regardless of title wording, so cross-model corroboration no
+  longer depends on title phrasing.
+
 ## [0.4.1] - 2026-07-07
 
 ### Changed

package/README.ja.md

@@ -10,6 +10,10 @@ Kyo-so (Kyoso / 協奏) は、AI coding workflow 向けの MCP-native、ACP-powe
 
 「協奏」という名前には、複数の独立した奏者がそれぞれの役割を保ちながら、ひとつの成果をつくるという意味を込めています。
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-ensemble.png" alt="指揮者がドラマー・バイオリニスト・ピアニストをまとめる様子" width="480">
+</p>
+
 Kyo-so は Codex と Claude の reviewer を連携させ、次のレビューを行います。
 
 - implementation plan review
@@ -24,7 +28,7 @@ Kyoso はコード変更を適用しません。
 
 ### Claude Only / Codex Only
 
-Kyoso は Claude だけ、または Codex だけでも実行できます。利用できない backend は `kyoso.config.ts` で無効化してください。例は `examples/claude-only.config.ts` と `examples/codex-only.config.ts` にあります。
+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 であることを表示します。
 
@@ -102,6 +106,7 @@ Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応)
 ローカル開発:
 
 ```bash
+nix develop
 safe-chain bun install
 safe-chain bun run typecheck
 safe-chain bun test
@@ -110,6 +115,8 @@ 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
@@ -200,6 +207,8 @@ Kyoso は provider credentials を保存しません。Child agent environment v
 
 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 はユーザーの言語のままで構いません。
+
 ## Agent Auth
 
 Codex は利用可能な場合、local `codex` login を使用します。既定の subscription-backed path では API key は不要です。
@@ -224,17 +233,14 @@ Kyoso は subprocesses の起動に必要な最小限の runtime env も forward
 
 `agents.<name>.model` を省略すると、各 agent 独自の default を使用します。Codex は `~/.codex/config.toml` などの local Codex config を使用し、Claude は adapter default を使用します。
 
-```ts
-export default defineConfig({
-  agents: {
-    codex: {
-      model: "gpt-5.5",
-    },
-    claude: {
-      model: "claude-sonnet-5",
-    },
-  },
-});
+指定できる model 名は [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview) と [Codex models](https://developers.openai.com/codex/models) を参照してください。
+
+```toml
+[agents.codex]
+model = "gpt-5.5"
+
+[agents.claude]
+model = "claude-sonnet-5"
 ```
 
 Kyoso は model pins を adapter-supported configuration に mapping します。
@@ -256,11 +262,42 @@ Raw agent output と raw file contents は既定で無効です。
 
 ## Config
 
-`kyoso.config.ts` は trust-on-first-use approval の後にのみ load されます。Trusted hashes は `~/.kyoso/trusted-configs.json` に保存されます。
+Kyoso は次の順に config を load します。
+
+- built-in defaults
+- user global TOML: `$XDG_CONFIG_HOME/kyoso/config.toml`、または `~/.config/kyoso/config.toml`
+- project TOML: `<cwd>/kyoso.toml`
+- `--network` などの CLI flags
+
+Project `kyoso.toml` は declarative で、trust approval は不要です。tools toggles、agent `enabled` / `model` / `role` / `timeoutMs`、workspace byte limits と additive `workspace.deny`、verification settings、advisory judge settings、tightening-only security/network settings を設定できます。
+
+Global TOML は command 実行や env forwarding を含む user-owned settings 用です。
 
-TypeScript config files は任意の code を実行できます。TTY では、untrusted config を実行する前に Kyoso が確認します。MCP や CI のような non-interactive mode では、untrusted config は skip され、defaults が使われます。現在の config hash を明示的に trust するには `--trust-config` を渡し、常に defaults を使うには `--ignore-config` を渡してください。
+```toml
+[agents.codex]
+command = "bunx"
+args = ["@agentclientprotocol/codex-acp"]
+
+[agents.codex.env]
+CODEX_CONFIG = '{"model":"gpt-5.5"}'
+```
+
+`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 を無視します。
+
+Default agent timeouts は Codex 120 秒、Claude 240 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
+
+Optional finding verification は default で disabled です:
+
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+allowDemotion = false
+```
 
-Default agent timeouts は Codex 120 秒、Claude 240 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。
+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:
 
@@ -275,15 +312,15 @@ Subscription-only setup:
 - Codex: local `codex` login を使用
 - Claude: `claude setup-token` を実行し、`CLAUDE_CODE_OAUTH_TOKEN` を設定
 - Judge: API keys を設定しないことで、Kyoso は `deterministic_fallback` を使用
-- `OPENAI_API_KEY` が存在するときに OpenAI judge calls を避けるには、`judgeProvider: "none"` を設定
+- `OPENAI_API_KEY` が存在するときに OpenAI judge calls を避けるには、`judge.provider = "none"` を設定
 
 Team admins は organization Usage credits も確認してください。Credits が有効な場合、subscription limits を超える billing behavior は Kyoso の外側で制御されます。
 
 ## Troubleshooting
 
-- MCP timeout: client tool timeouts を少なくとも 360 秒に設定してください。Kyoso defaults は Codex 120 秒、Claude 240 秒です。
+- MCP timeout: client tool timeouts を少なくとも 360 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は Codex 120 秒、Claude 240 秒、verification 90 秒です。
 - Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx @kyo-so/cli` の解決が一時的に block される場合があります。
-- Non-interactive config: `--trust-config` を渡さない限り、untrusted `kyoso.config.ts` は skip されます。
+- Deprecated TypeScript config: `--trust-config` を渡さない限り、untrusted `kyoso.config.ts` は skip されます。新規設定は `kyoso.toml` を使ってください。
 
 ## Development
 

package/README.md

@@ -8,6 +8,10 @@ Kyo-so (Kyoso / 協奏) is an MCP-native, ACP-powered multi-agent review gate fo
 
 The Japanese word 協奏 translates to concerto in English: multiple independent players performing one coordinated piece.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-ensemble.png" alt="A conductor coordinating a drummer, a violinist, and a pianist" width="480">
+</p>
+
 It coordinates Codex and Claude reviewers for:
 
 - implementation plan review
@@ -22,7 +26,7 @@ No global install is required. Run Kyoso through `npx` or `bunx`.
 
 ### Claude Only / Codex Only
 
-Kyoso can run when only Claude or only Codex is available. Disable the missing backend in `kyoso.config.ts` using `examples/claude-only.config.ts` or `examples/codex-only.config.ts`.
+Kyoso can run when only Claude or only Codex is available. Disable the missing backend in `kyoso.toml` using `examples/claude-only.toml` or `examples/codex-only.toml`.
 
 In single-agent mode, the remaining backend runs once as `combined_reviewer` and covers both implementation and architecture/security focus areas. JSON output includes `reviewMode: "single_agent"` and `agentsUsed`; Markdown output states that cross-model verification was not performed and marks disagreements as N/A.
 
@@ -100,15 +104,21 @@ Naming note: the npm package is `@kyo-so/cli` (matching the product name Kyo-so)
 For local 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
 ```
 
 Requires Node.js 20 or newer when running the packaged CLI.
 
-Known distribution risk: `@modelcontextprotocol/server` has no stable release yet; Kyoso currently pins a prerelease API, so MCP SDK API changes may require a follow-up release.
+The Nix dev shell pins Node.js 24 and the nixpkgs-provided Bun version. After reviewing `.envrc`, you can also run `direnv allow` once and let it load the shell automatically. CI remains pinned to Bun 1.3.14; the current nixpkgs Bun version may differ slightly, but `flake.lock` keeps local shells reproducible.
+
+The test suite includes credential-free MCP stdio and ACP subprocess integration coverage. `pack:verify` additionally starts the packed `dist/bin/kyoso.js` MCP server and checks the published bundle's protocol handshake.
+
+Known distribution risk: `@modelcontextprotocol/server` has no stable release yet; Kyoso currently pins a prerelease API, so MCP SDK API changes may require a follow-up release. Run manual real-agent dogfooding before releases that bump `@modelcontextprotocol/server`, `@agentclientprotocol/sdk`, or pinned ACP adapters.
 
 ## CLI
 
@@ -198,6 +208,8 @@ Kyoso does not store provider credentials. Child agent environment variables are
 
 Repository content, plans, diffs, and selected files are treated as untrusted data in backend prompts. Kyoso wraps them in `<untrusted-content>` tags and tells agents not to follow instructions found inside. Final decisions are derived from schema-constrained findings; agents cannot write files or run commands, and the judge cannot change the deterministic decision.
 
+Finding titles are normalized to concise English for aggregation; evidence, recommendations, and summaries can remain in the user's language.
+
 ## Agent Auth
 
 Codex uses the local `codex` login when available. No API key is required for the default subscription-backed path.
@@ -222,17 +234,14 @@ Kyoso also forwards minimal runtime env needed to launch subprocesses: `PATH`, `
 
 Omit `agents.<name>.model` to use each agent's own default. Codex uses the local Codex config, such as `~/.codex/config.toml`; Claude uses the adapter default.
 
-```ts
-export default defineConfig({
-  agents: {
-    codex: {
-      model: "gpt-5.5",
-    },
-    claude: {
-      model: "claude-sonnet-5",
-    },
-  },
-});
+For available model names, see the [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview) and the [Codex models list](https://developers.openai.com/codex/models).
+
+```toml
+[agents.codex]
+model = "gpt-5.5"
+
+[agents.claude]
+model = "claude-sonnet-5"
 ```
 
 Kyoso maps model pins to adapter-supported configuration:
@@ -254,11 +263,42 @@ Keep `.kyoso/traces/` out of Git. `kyoso init` adds `.kyoso/` to `.gitignore`, a
 
 ## Config
 
-`kyoso.config.ts` is loaded only after trust-on-first-use approval. Trusted hashes are stored in `~/.kyoso/trusted-configs.json`.
+Kyoso loads config in this order:
+
+- built-in defaults
+- user global TOML: `$XDG_CONFIG_HOME/kyoso/config.toml`, or `~/.config/kyoso/config.toml`
+- project TOML: `<cwd>/kyoso.toml`
+- CLI flags such as `--network`
+
+Project `kyoso.toml` is declarative and does not require trust approval. It can set safe project-scoped keys such as tool toggles, agent `enabled` / `model` / `role` / `timeoutMs`, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network settings.
+
+Global TOML is for user-owned settings that can launch commands or forward environment variables:
 
-TypeScript config files can execute arbitrary code. In a TTY, Kyoso prompts before executing an untrusted config. In non-interactive mode such as MCP or CI, untrusted config is skipped and defaults are used. Pass `--trust-config` to explicitly trust the current config hash, or `--ignore-config` to always use defaults.
+```toml
+[agents.codex]
+command = "bunx"
+args = ["@agentclientprotocol/codex-acp"]
+
+[agents.codex.env]
+CODEX_CONFIG = '{"model":"gpt-5.5"}'
+```
+
+`kyoso.config.ts` is deprecated but still supported for compatibility. It is loaded only after trust-on-first-use approval; trusted hashes are stored in `~/.kyoso/trusted-configs.json`. If both `kyoso.toml` and `kyoso.config.ts` exist, Kyoso uses TOML and ignores the TypeScript config.
+
+Default agent timeouts are Codex 120 seconds and Claude 240 seconds. MCP clients should allow at least 360 seconds for tool calls. If `verification.enabled` is true, allow at least 480 seconds because Kyoso may run an additional cross-agent verification round.
+
+Optional finding verification is disabled by default:
+
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+allowDemotion = false
+```
 
-Default agent timeouts are Codex 120 seconds and Claude 240 seconds. MCP clients should allow at least 360 seconds for tool calls.
+When enabled, Kyoso asks the agent that did not report each high/critical single-source finding to try to refute it. Phase 1 is annotate-only: verification can update finding confidence and notes, but it does not change severity or the final decision. `allowDemotion` is reserved for a future opt-in phase and is currently a no-op.
 
 Judge LLMs are optional. Set `OPENAI_API_KEY` or `CODEX_API_KEY` to use the OpenAI judge, or `ANTHROPIC_API_KEY` to use the Anthropic judge. Optional overrides:
 
@@ -273,15 +313,15 @@ Subscription-only setup:
 - Codex: use local `codex` login
 - Claude: run `claude setup-token`, then set `CLAUDE_CODE_OAUTH_TOKEN`
 - Judge: set no API keys, so Kyoso uses `deterministic_fallback`
-- To avoid OpenAI judge calls when `OPENAI_API_KEY` is present, set `judgeProvider: "none"`
+- To avoid OpenAI judge calls when `OPENAI_API_KEY` is present, set `judge.provider = "none"`
 
 Team admins should also check organization Usage credits. If credits are enabled, billing behavior beyond subscription limits is controlled outside Kyoso.
 
 ## Troubleshooting
 
-- MCP timeout: set client tool timeouts to at least 360 seconds. Kyoso defaults are Codex 120 seconds and Claude 240 seconds.
+- MCP timeout: set client tool timeouts to at least 360 seconds, or at least 480 seconds when `verification.enabled` is true. Kyoso defaults are Codex 120 seconds, Claude 240 seconds, and verification 90 seconds.
 - Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx @kyo-so/cli` resolution after publish.
-- Non-interactive config: untrusted `kyoso.config.ts` is skipped unless you pass `--trust-config`.
+- Deprecated TypeScript config: untrusted `kyoso.config.ts` is skipped unless you pass `--trust-config`; prefer `kyoso.toml`.
 
 ## Development
 

package/README.zh-CN.md

@@ -10,6 +10,10 @@ Kyo-so (Kyoso / 協奏) 是面向 AI coding workflows 的 MCP-native、ACP-power
 
 日语词「協奏」在英语中可译为 concerto：多个独立演奏者各司其职，共同完成一部协调的作品。
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-ensemble.png" alt="指挥家协调鼓手、小提琴手和钢琴家" width="480">
+</p>
+
 它会协调 Codex 和 Claude reviewers，用于：
 
 - implementation plan review
@@ -24,7 +28,7 @@ Kyoso 不会应用代码更改。
 
 ### Claude Only / Codex Only
 
-Kyoso 可以在只有 Claude 或只有 Codex 可用时运行。请在 `kyoso.config.ts` 中禁用缺失的 backend；示例见 `examples/claude-only.config.ts` 和 `examples/codex-only.config.ts`。
+Kyoso 可以在只有 Claude 或只有 Codex 可用时运行。请在 `kyoso.toml` 中禁用缺失的 backend；示例见 `examples/claude-only.toml` 和 `examples/codex-only.toml`。
 
 在 single-agent mode 中，剩余 backend 会以 `combined_reviewer` 运行一次，同时覆盖 implementation 和 architecture/security 两类关注点。JSON output 会包含 `reviewMode: "single_agent"` 和 `agentsUsed`；Markdown output 会说明未执行 cross-model verification，并将 disagreements 标记为 N/A。
 
@@ -102,6 +106,7 @@ Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后
 本地开发：
 
 ```bash
+nix develop
 safe-chain bun install
 safe-chain bun run typecheck
 safe-chain bun test
@@ -110,6 +115,8 @@ safe-chain bun run build
 
 运行打包后的 CLI 需要 Node.js 20 或更高版本。
 
+Nix dev shell 会 pin Node.js 24 和 nixpkgs 提供的 Bun version。确认 `.envrc` 后，也可以运行一次 `direnv allow`，让它自动加载 shell。CI 仍然 pin 到 Bun 1.3.14；当前 nixpkgs Bun version 可能略有不同，但 `flake.lock` 会保证 local shell 可复现。
+
 已知分发风险：`@modelcontextprotocol/server` 目前还没有 stable release；Kyoso 当前 pin 了 prerelease API，因此 MCP SDK API 变更可能需要后续 release。
 
 ## CLI
@@ -200,6 +207,8 @@ Kyoso 不存储 provider credentials。Child agent environment variables 使用
 
 Repository content、plans、diffs 和 selected files 在 backend prompts 中被视为 untrusted data。Kyoso 会用 `<untrusted-content>` tags 包裹它们，并告诉 agents 不要遵循其中的 instructions。最终 decisions 来自 schema-constrained findings；agents 不能写 files 或运行 commands，judge 不能改变 deterministic decision。
 
+Finding title 会为 aggregation 规范化为简洁英文；evidence、recommendations 和 summaries 可以继续使用用户的语言。
+
 ## Agent Auth
 
 可用时，Codex 使用 local `codex` login。默认 subscription-backed path 不需要 API key。
@@ -224,17 +233,14 @@ Kyoso 还会 forward 启动 subprocesses 所需的最小 runtime env：`PATH`, `
 
 省略 `agents.<name>.model` 时，会使用各 agent 自身的 default。Codex 使用 local Codex config，例如 `~/.codex/config.toml`；Claude 使用 adapter default。
 
-```ts
-export default defineConfig({
-  agents: {
-    codex: {
-      model: "gpt-5.5",
-    },
-    claude: {
-      model: "claude-sonnet-5",
-    },
-  },
-});
+可指定的 model 名称请参阅 [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview) 与 [Codex models](https://developers.openai.com/codex/models)。
+
+```toml
+[agents.codex]
+model = "gpt-5.5"
+
+[agents.claude]
+model = "claude-sonnet-5"
 ```
 
 Kyoso 会将 model pins 映射到 adapter-supported configuration：
@@ -256,11 +262,42 @@ Raw agent output 和 raw file contents 默认禁用。
 
 ## Config
 
-`kyoso.config.ts` 只会在 trust-on-first-use approval 之后 load。Trusted hashes 保存在 `~/.kyoso/trusted-configs.json`。
+Kyoso 按以下顺序 load config：
+
+- built-in defaults
+- user global TOML: `$XDG_CONFIG_HOME/kyoso/config.toml`，或 `~/.config/kyoso/config.toml`
+- project TOML: `<cwd>/kyoso.toml`
+- `--network` 等 CLI flags
+
+Project `kyoso.toml` 是 declarative config，不需要 trust approval。它可以设置 tools toggles、agent `enabled` / `model` / `role` / `timeoutMs`、workspace byte limits 和 additive `workspace.deny`、verification settings、advisory judge settings，以及 tightening-only security/network settings。
+
+Global TOML 用于 user-owned settings，包括 command 启动和 env forwarding。
 
-TypeScript config files 可以执行任意 code。在 TTY 中，Kyoso 会在执行 untrusted config 前提示确认。在 MCP 或 CI 等 non-interactive mode 中，untrusted config 会被 skip，并使用 defaults。传入 `--trust-config` 可明确 trust 当前 config hash；传入 `--ignore-config` 可始终使用 defaults。
+```toml
+[agents.codex]
+command = "bunx"
+args = ["@agentclientprotocol/codex-acp"]
+
+[agents.codex.env]
+CODEX_CONFIG = '{"model":"gpt-5.5"}'
+```
+
+`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。
+
+Default agent timeouts 是 Codex 120 秒、Claude 240 秒。MCP clients 应允许 tool calls 至少运行 360 秒。如果 `verification.enabled` 为 true，Kyoso 可能会运行额外的 cross-agent verification round，因此建议至少允许 480 秒。
+
+Optional finding verification 默认 disabled:
+
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+allowDemotion = false
+```
 
-Default agent timeouts 是 Codex 120 秒、Claude 240 秒。MCP clients 应允许 tool calls 至少运行 360 秒。
+启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。Phase 1 是 annotate-only：verification 可以更新 finding confidence 和 notes，但不会改变 severity 或 final decision。`allowDemotion` 为未来的 opt-in phase 保留，目前是 no-op。
 
 Judge LLMs 是 optional。设置 `OPENAI_API_KEY` 或 `CODEX_API_KEY` 可使用 OpenAI judge，设置 `ANTHROPIC_API_KEY` 可使用 Anthropic judge。Optional overrides:
 
@@ -275,15 +312,15 @@ Subscription-only setup:
 - Codex: 使用 local `codex` login
 - Claude: 运行 `claude setup-token`，然后设置 `CLAUDE_CODE_OAUTH_TOKEN`
 - Judge: 不设置 API keys，因此 Kyoso 使用 `deterministic_fallback`
-- 当存在 `OPENAI_API_KEY` 时，如需避免 OpenAI judge calls，请设置 `judgeProvider: "none"`
+- 当存在 `OPENAI_API_KEY` 时，如需避免 OpenAI judge calls，请设置 `judge.provider = "none"`
 
 Team admins 还应检查 organization Usage credits。如果启用了 credits，超出 subscription limits 的 billing behavior 由 Kyoso 外部控制。
 
 ## Troubleshooting
 
-- MCP timeout: 将 client tool timeouts 设置为至少 360 秒。Kyoso defaults 是 Codex 120 秒、Claude 240 秒。
+- MCP timeout: 将 client tool timeouts 设置为至少 360 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 是 Codex 120 秒、Claude 240 秒、verification 90 秒。
 - Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
-- Non-interactive config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip。
+- Deprecated TypeScript config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip；新配置请使用 `kyoso.toml`。
 
 ## Development
 

package/dist/acp/FakeAgentManager.d.ts

@@ -1,9 +1,21 @@
 import type { AgentRunInput, AgentRunResult } from "../core/types.js";
 import { BaseAcpAgentManager } from "./AcpAgentManager.js";
 export type FakeAgentScenario = "success" | "markdown_json" | "timeout" | "malformed" | "auth_failure" | "permission_request" | "write_attempt";
+export type FakeVerifierVerdict = {
+    findingId: string;
+    verdict: "confirmed" | "refuted" | "uncertain";
+    reasoning?: string;
+    evidence?: string;
+};
+export type FakeVerifierScenario = "confirmed" | "refuted" | "uncertain" | "malformed" | "timeout" | {
+    rawText: string;
+} | {
+    verdicts: FakeVerifierVerdict[];
+};
 export declare class FakeAgentManager extends BaseAcpAgentManager {
     private readonly scenarios;
+    private readonly verifierScenarios;
     readonly calls: AgentRunInput[];
-    constructor(scenarios?: Partial<Record<"codex" | "claude", FakeAgentScenario>>);
+    constructor(scenarios?: Partial<Record<"codex" | "claude", FakeAgentScenario>>, verifierScenarios?: Partial<Record<"codex" | "claude", FakeVerifierScenario>>);
     runAgent(input: AgentRunInput): Promise<AgentRunResult>;
 }

package/dist/acp/prompts.d.ts

@@ -1,2 +1,3 @@
-import type { AgentName, AgentRole, KyosoReviewRequest, ReviewTool } from "../core/types.js";
+import type { AgentName, AgentRole, KyosoFinding, KyosoReviewRequest, ReviewTool } from "../core/types.js";
 export declare function buildAgentPrompt(tool: ReviewTool, request: KyosoReviewRequest, agent: AgentName, role: AgentRole): string;
+export declare function buildFindingVerifierPrompt(tool: ReviewTool, request: KyosoReviewRequest, verifier: AgentName, findings: KyosoFinding[]): string;

package/dist/aggregate/aggregateFindings.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRunResult, KyosoFinding } from "../core/types.js";
+import type { AgentRunResult, KyosoFinding, ReviewMode } from "../core/types.js";
 export type AggregatedReview = {
     findings: KyosoFinding[];
     testsToAdd: string[];
@@ -12,4 +12,7 @@ export type AggregatedReview = {
         judgeComment: string;
     }>;
 };
-export declare function aggregateAgentResults(results: AgentRunResult[]): AggregatedReview;
+export declare function aggregateAgentResults(results: AgentRunResult[], options?: {
+    reviewMode?: ReviewMode;
+}): AggregatedReview;
+export declare function realSourceAgentCount(sourceAgents: KyosoFinding["sourceAgents"]): number;