@kyo-so/cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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

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 であることを表示します。
 
@@ -229,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 します。
@@ -261,21 +262,39 @@ 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 を設定できます。
 
-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` を渡してください。
+Global TOML は command 実行や env forwarding を含む user-owned settings 用です。
+
+```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 です:
 
-```ts
-verification: {
-  enabled: false,
-  maxFindings: 5,
-  timeoutMs: 90_000,
-  allowDemotion: false,
-}
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+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 です。
@@ -293,7 +312,7 @@ 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 の外側で制御されます。
 
@@ -301,7 +320,7 @@ Team admins は organization Usage credits も確認してください。Credits
 
 - 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.
 
@@ -230,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:
@@ -262,21 +263,39 @@ 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.
 
-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.
+Global TOML is for user-owned settings that can launch commands or forward environment variables:
+
+```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:
 
-```ts
-verification: {
-  enabled: false,
-  maxFindings: 5,
-  timeoutMs: 90_000,
-  allowDemotion: false,
-}
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+allowDemotion = false
 ```
 
 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.
@@ -294,7 +313,7 @@ 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.
 
@@ -302,7 +321,7 @@ Team admins should also check organization Usage credits. If credits are enabled
 
 - 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。
 
@@ -229,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：
@@ -261,21 +262,39 @@ 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。
 
-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。
+Global TOML 用于 user-owned settings，包括 command 启动和 env forwarding。
+
+```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:
 
-```ts
-verification: {
-  enabled: false,
-  maxFindings: 5,
-  timeoutMs: 90_000,
-  allowDemotion: false,
-}
+```toml
+[verification]
+enabled = false
+maxFindings = 5
+timeoutMs = 90000
+# global config only; project kyoso.toml cannot set this
+allowDemotion = false
 ```
 
 启用后，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。
@@ -293,7 +312,7 @@ 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 外部控制。
 
@@ -301,7 +320,7 @@ Team admins 还应检查 organization Usage credits。如果启用了 credits，
 
 - 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