@kyo-so/cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-09
+
+### Added
+
+- `agents.<name>.effort` config field for Codex and Claude, mirroring
+  `agents.<name>.model`. Kyoso sends it once per session as an ACP
+  `session/set_config_option` request (`effort` for Claude,
+  `reasoning_effort` for Codex). The request is fail-soft: a rejection is
+  logged to stderr as a sanitized warning and surfaced to MCP/JSON callers
+  via `result.audit.warnings`, and the review continues at the backend's
+  own default effort. Settable from both user-global and project TOML
+  (same risk profile as `model`: no command execution or env forwarding).
+
+### Fixed
+
+- Documentation still described the default Claude agent timeout as 240
+  seconds; README (all languages), the design document, and the example
+  config now reflect the 300-second default introduced in 0.6.0.
+
+## [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
@@ -18,13 +22,23 @@ Kyo-so は Codex と Claude の reviewer を連携させ、次のレビューを
 
 Kyoso はコード変更を適用しません。
 
+## Review Flow
+
+3 つの review tool はすべて同じパイプラインで動きます。secret scan の後、read-only の一時スナップショット上で reviewer ensemble を ACP 経由で並列実行し、所見の集約・ゲート適用・決定を行います。
+
+<p align="center">
+  <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/) にあります。
+
 ## Quick Start
 
 グローバルインストールは不要です。Kyoso は `npx` または `bunx` で実行します。
 
 ### 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 であることを表示します。
 
@@ -225,21 +239,20 @@ Default child-agent env allowlist:
 
 Kyoso は subprocesses の起動に必要な最小限の runtime env も forward します: `PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `SHELL`, `USER`, `USERNAME`, `SystemRoot`。
 
-## Agent Models
-
-`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",
-    },
-  },
-});
+## Agent Models and Effort
+
+`agents.<name>.model` または `agents.<name>.effort` を省略すると、各 agent 独自の default を使用します。Codex は `~/.codex/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) を参照してください。
+
+```toml
+[agents.codex]
+model = "gpt-5.5"
+effort = "medium"
+
+[agents.claude]
+model = "claude-sonnet-5"
+effort = "high"
 ```
 
 Kyoso は model pins を adapter-supported configuration に mapping します。
@@ -247,6 +260,8 @@ Kyoso は model pins を adapter-supported configuration に mapping します
 - Claude: `agents.claude.env` または whitelisted parent env で未設定の場合に `ANTHROPIC_MODEL` を設定します。
 - Codex: `CODEX_CONFIG` が未設定の場合、`CODEX_CONFIG={"model":"..."}` を設定します。model pin と他の Codex session config を組み合わせるには、`agents.codex.env.CODEX_CONFIG` を直接設定してください。
 
+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
 
 Audit traces は次の場所に書き込まれます。
@@ -261,21 +276,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
 
-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` を渡してください。
+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 を設定できます。
 
-Default agent timeouts は Codex 120 秒、Claude 240 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
+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 300 秒です。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,15 +326,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 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は Codex 120 秒、Claude 240 秒、verification 90 秒です。
+- MCP timeout: client tool timeouts を少なくとも 360 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は Codex 120 秒、Claude 300 秒、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
@@ -16,13 +20,23 @@ It coordinates Codex and Claude reviewers for:
 
 Kyoso does not apply code changes.
 
+## Review Flow
+
+All three review tools run the same pipeline: scan for secrets, snapshot the workspace read-only, run the reviewer ensemble in parallel over ACP, then aggregate findings, apply gates, and decide.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-review-flow.en.svg" alt="Kyo-so review execution flow, from MCP/CLI request through secret scan, snapshot, ensemble review, aggregation, gates, and final decision" width="640">
+</p>
+
+With a single backend enabled, one agent runs as `combined_reviewer` instead of the two-role ensemble. The Mermaid sources for this diagram live in [docs/assets/](docs/assets/).
+
 ## Quick Start
 
 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.
 
@@ -226,21 +240,20 @@ Default child-agent env allowlist:
 
 Kyoso also forwards minimal runtime env needed to launch subprocesses: `PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `SHELL`, `USER`, `USERNAME`, and `SystemRoot`.
 
-## Agent Models
-
-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",
-    },
-  },
-});
+## Agent Models and Effort
+
+Omit `agents.<name>.model` or `agents.<name>.effort` to use each agent's own default. Codex uses the local Codex config, such as `~/.codex/config.toml`; Claude uses the adapter default.
+
+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"
+effort = "medium"
+
+[agents.claude]
+model = "claude-sonnet-5"
+effort = "high"
 ```
 
 Kyoso maps model pins to adapter-supported configuration:
@@ -248,6 +261,8 @@ Kyoso maps model pins to adapter-supported configuration:
 - Claude: sets `ANTHROPIC_MODEL` when not already set in `agents.claude.env` or a whitelisted parent env.
 - Codex: sets `CODEX_CONFIG={"model":"..."}` when `CODEX_CONFIG` is not already set. To combine other Codex session config with a model pin, set `agents.codex.env.CODEX_CONFIG` directly.
 
+Effort works differently: Kyoso does not set an env var for it. Instead, it sends an ACP `session/set_config_option` request to the backend agent once per session, before the first prompt: `configId: "effort"` for Claude, `configId: "reasoning_effort"` for Codex. Valid values depend on the backend agent version and the selected model (for example, Claude only exposes effort levels for models that support them). Kyoso does not validate `effort` values itself; if the backend agent rejects the request or does not support it, Kyoso logs it to stderr and continues the review.
+
 ## Audit
 
 Audit traces are written to:
@@ -262,21 +277,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`
 
-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.
+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` / `effort` / `role` / `timeoutMs`, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network settings.
 
-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.
+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 300 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,15 +327,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, or at least 480 seconds when `verification.enabled` is true. Kyoso defaults are Codex 120 seconds, Claude 240 seconds, and verification 90 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 300 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
@@ -18,13 +22,23 @@ Kyo-so (Kyoso / 協奏) 是面向 AI coding workflows 的 MCP-native、ACP-power
 
 Kyoso 不会应用代码更改。
 
+## Review Flow
+
+三个 review tool 都运行同一条流水线：先进行 secret scan，在 read-only 的临时快照上通过 ACP 并行运行 reviewer ensemble，然后聚合发现、应用门禁并作出决定。
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/kyoso/main/docs/assets/kyoso-review-flow.zh-CN.svg" alt="Kyo-so 评审执行流程：从 MCP/CLI 请求到 secret scan、快照、协奏评审、聚合、门禁与最终决定" width="640">
+</p>
+
+当只启用一个 backend 时，会由 1 个 agent 以 `combined_reviewer` 运行，替代双角色 ensemble。此图的 Mermaid 源文件位于 [docs/assets/](docs/assets/)。
+
 ## Quick Start
 
 无需全局安装。通过 `npx` 或 `bunx` 运行 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。
 
@@ -225,21 +239,20 @@ Default child-agent env allowlist:
 
 Kyoso 还会 forward 启动 subprocesses 所需的最小 runtime env：`PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `LANG`, `LC_ALL`, `SHELL`, `USER`, `USERNAME`, and `SystemRoot`。
 
-## Agent Models
-
-省略 `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",
-    },
-  },
-});
+## Agent Models and Effort
+
+省略 `agents.<name>.model` 或 `agents.<name>.effort` 时，会使用各 agent 自身的 default。Codex 使用 local Codex config，例如 `~/.codex/config.toml`；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)。
+
+```toml
+[agents.codex]
+model = "gpt-5.5"
+effort = "medium"
+
+[agents.claude]
+model = "claude-sonnet-5"
+effort = "high"
 ```
 
 Kyoso 会将 model pins 映射到 adapter-supported configuration：
@@ -247,6 +260,8 @@ Kyoso 会将 model pins 映射到 adapter-supported configuration：
 - Claude: 当 `agents.claude.env` 或 whitelisted parent env 中尚未设置时，设置 `ANTHROPIC_MODEL`。
 - Codex: 当 `CODEX_CONFIG` 尚未设置时，设置 `CODEX_CONFIG={"model":"..."}`。若要将 model pin 与其他 Codex session config 组合，请直接设置 `agents.codex.env.CODEX_CONFIG`。
 
+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 本身不会 validate `effort` 的值；如果 backend agent reject 了该请求，或不支持该 option，Kyoso 会将其记录到 stderr 并继续 review。
+
 ## Audit
 
 Audit traces 写入：
@@ -261,21 +276,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
 
-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。
+Project `kyoso.toml` 是 declarative config，不需要 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。
 
-Default agent timeouts 是 Codex 120 秒、Claude 240 秒。MCP clients 应允许 tool calls 至少运行 360 秒。如果 `verification.enabled` 为 true，Kyoso 可能会运行额外的 cross-agent verification round，因此建议至少允许 480 秒。
+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 300 秒。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,15 +326,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 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 是 Codex 120 秒、Claude 240 秒、verification 90 秒。
+- MCP timeout: 将 client tool timeouts 设置为至少 360 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 是 Codex 120 秒、Claude 300 秒、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