@kyo-so/cli 0.7.1 → 0.9.0

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

@@ -29,10 +29,22 @@ Do not use this skill for every coding task. It is intended for deliberate revie
    - selected files
    - unified diff if available
    - constraints
-4. Call the appropriate Kyoso MCP tool:
-   - `plan_review`
-   - `security_review`
-   - `diff_review`
+4. Run the review through the first available path:
+   - Prefer the corresponding Kyoso MCP tool when it is available:
+     - `plan_review`
+     - `security_review`
+     - `diff_review`
+   - If the MCP tools are unavailable, use the first available CLI path with JSON output:
+     1. An installed `kyoso` executable on `PATH`.
+     2. `npx -y @kyo-so/cli`.
+     3. `bunx @kyo-so/cli`.
+   - Append the review command to the selected CLI path:
+     - `plan_review` -> `plan --goal <text> [--plan <path-or-text>] [--file <path>] --json`
+     - `security_review` -> `security --goal <text> [--diff <path>] [--file <path>] --json`
+     - `diff_review` -> `diff --base <ref> --head <ref> --json`
+   - 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.

package/.agents/skills/kyoso-review/agents/openai.yaml

@@ -5,10 +5,3 @@ interface:
 
 policy:
   allow_implicit_invocation: false
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "kyoso"
-      description: "Kyoso MCP server"
-      transport: "stdio"

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-07-11
+
+### Added
+
+- Codex Marketplace fixture with a version-pinned local stdio MCP, bundled
+  `kyoso-review` Skill, isolated runtime probe, and compatibility records for
+  Codex CLI 0.144.0-alpha.4 and 0.144.1.
+- `kyoso setup codex|claude-code --skill-only` for installing the canonical
+  Skill without reading or writing MCP configuration. The setup surface also
+  supports `--force` for Skill-only replacement and rejects MCP-only option
+  combinations.
+- Managed Skill updates with deterministic directory digests,
+  `.kyoso-install.json`, published 0.8.0 legacy adoption, user-change conflict
+  detection, symlink rejection, and staged backup/rename replacement.
+
+### Changed
+
+- Recover interrupted managed-Skill replacements from a fixed backup, fail
+  closed on ambiguous recovery state, and guard rename operations against
+  parent-directory replacement.
+- Audit traces now use a verified POSIX user state root (`$XDG_STATE_HOME` or
+  `$HOME/.local/state`) instead of a workspace-controlled `.kyoso/traces`
+  path. The new layout hashes the workspace realpath; existing workspace
+  traces are not migrated or deleted automatically.
+- The canonical bundled Skill continues to try Kyoso MCP tools, an installed
+  `kyoso` on `PATH`, `npx`, then `bunx`, without declaring MCP as a required
+  dependency. The generated Marketplace Plugin copy declares its bundled
+  `kyoso` MCP server as a dependency; a disabled Plugin MCP must be re-enabled
+  or migrated to CLI plus Skill-only rather than falling back to the CLI.
+- Codex MCP configuration resolves from `CODEX_HOME`, while global Codex Skill
+  installation continues to resolve from `HOME`.
+
+### Fixed
+
+- Harden Audit trace creation against workspace-controlled symlinks and races
+  with verified handles, exclusive creation, and fail-closed state-root
+  containment. Windows and runtimes without proven safe filesystem
+  capabilities disable Audit writing rather than using an insecure fallback;
+  Windows support will be re-enabled only after equivalent ownership, symlink,
+  and file-identity guarantees are implemented and verified.
+
+## [0.8.0] - 2026-07-10
+
+### Added
+
+- Repeatable `--set <config-key>=<value>` option on the `plan`, `security`,
+  and `diff` commands for overriding config values such as
+  `agents.<agent>.model`, `agents.<agent>.effort`, and `timeoutMs` from the
+  command line. Overrides are restricted to the shared project-scope
+  allowlist, applied after config files (including with `--ignore-config`),
+  and schema-validated.
+- CLI fallback in the bundled `kyoso-review` skill: when the Kyoso MCP
+  server is not registered, the skill falls back to
+  `npx`/`bunx @kyo-so/cli plan|security|diff --json`. The fallback runs
+  without config trust flags first and requires user confirmation before
+  `--trust-config` or `--ignore-config`. Documented in all README languages.
+
 ## [0.7.1] - 2026-07-09
 
 ### Changed

package/README.ja.md

@@ -36,6 +36,54 @@ backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに
 
 グローバルインストールは不要です。Kyoso は `npx` または `bunx` で実行します。
 
+### 導入モード
+
+| モード             | 導入物                   |  MCP | 対象               |
+| ------------------ | ------------------------ | ---: | ------------------ |
+| Marketplace Plugin | Skill＋ローカルstdio MCP | あり | Codex              |
+| CLI＋Skill-only    | npm CLI＋Skill           | なし | Codex／Claude Code |
+| 手動setup          | 手動MCP登録＋Skill       | あり | Codex／Claude Code |
+
+#### Codex Marketplace Plugin
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin list --marketplace kyoso --available --json
+codex plugin add kyoso@kyoso
+codex plugin list --marketplace kyoso --json
+```
+
+Codex desktopのPlugins pageまたは`/plugins`からKyosoを選ぶこともできます。追加したMarketplaceが見えない場合はdesktop appをrefresh／restartしてください。削除は`codex plugin remove kyoso@kyoso`です。
+
+PluginはSkillと公開済みのKyoso CLIの完全一致versionへpinしたMCP定義を同梱しますが、CLI本体は同梱しません。MCPの初回起動ではnpmへのnetwork accessが必要です。cache済みpackageでoffline起動できる場合はありますが、保証しません。manifestの`Read` capabilityは表示metadataであり、filesystem認可を追加するものではありません。
+
+PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。Codex Auto modeでは、Kyoso toolsがannotationsを宣言していないため、最初のMCP呼び出しでapprovalが必要になることがあります。以後も許可する場合は「Allow and don't ask me again」を選択してください。
+
+同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
+
+#### CLI＋Skill-only
+
+```bash
+# Global CLI＋Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI＋Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Claude Codeでは`codex`を`claude-code`へ置き換えます。既定はdry-runです。`--skill-only`はMCP設定を読み書きせず、`--runner`／`--command`とは併用できません。
+
+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` にあります。
@@ -136,11 +184,13 @@ Nix dev shell は Node.js 24 と nixpkgs が提供する Bun version を固定
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
 kyoso security --goal "Review this auth diff" --diff changes.patch
-kyoso diff --base main --head HEAD
+kyoso diff --base main --head HEAD --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -203,9 +253,13 @@ MCP stdout は protocol messages 専用です。logs は stderr または local
 
 同梱の `kyoso-review` skill は意図的に狭い用途にしています。Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review、diff review を明示的に依頼したときだけ trigger されるべきです。
 
-`npx @kyo-so/cli setup codex --write` と `bunx @kyo-so/cli setup codex --write` は、既定で `.agents/skills/kyoso-review/` にコピーします。`--global` を追加すると `~/.agents/skills/kyoso-review/` にコピーします。
+Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`です。package runner fallbackはnetwork accessが必要になり、version driftも起こり得るため、MCPなしの通常経路にはインストール済みCLIを使います。
+
+`kyoso setup codex --write --skill-only`はcanonical Skill directoryを既定で`.agents/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.agents/skills/kyoso-review/`へコピーします。
 
-`npx @kyo-so/cli setup claude-code --write` と `bunx @kyo-so/cli setup claude-code --write` は、既定で `.claude/skills/kyoso-review/` にコピーします。`--global` を追加すると `~/.claude/skills/kyoso-review/` にコピーします。
+`kyoso setup claude-code --write --skill-only`は既定で`.claude/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.claude/skills/kyoso-review/`へコピーします。
+
+managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのSkill directoryだけを置換し、MCP設定を削除・上書きしません。
 
 ## Safety Model
 
@@ -219,6 +273,10 @@ Repository content、plans、diffs、selected files は backend prompts 内で u
 
 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が必要です。
+
 ## Agent Auth
 
 Codex は利用可能な場合、local `codex` login を使用します。既定の subscription-backed path では API key は不要です。
@@ -264,15 +322,15 @@ effort は仕組みが異なります。Kyoso は env var を設定せず、sess
 
 ## Audit
 
-Audit traces は次の場所に書き込まれます。
+対応するPOSIX runtimeでは、Audit traces はuser state base（absoluteな`$XDG_STATE_HOME`、なければ`$HOME/.local/state`）配下の次の場所に書き込まれます。
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output と raw file contents は既定で無効です。
+`audit.directory`はlogicalなrelative directory（既定: `.kyoso/traces`）であり、workspace内のdirectoryではありません。既存のworkspace `.kyoso/traces`は自動で移行・削除されません。
 
-`.kyoso/traces/` を Git に含めないでください。`kyoso init` は `.kyoso/` を `.gitignore` に追加し、この repository も同じ設定にしています。`audit.includeRawAgentOutput` を有効にすると、traces に sensitive review output が残る場合があります。local retention policy に従って古い 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を返します。
 
 ## Config
 
@@ -281,7 +339,15 @@ 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
+- `--network` などの CLI flags と `--set agents.claude.effort=high` などの反復可能な overrides
+
+`plan`、`security`、`diff` は、反復可能な `--set <key>=<value>` overrides を受け付けます。CLI で指定した値は config files より優先され、`--ignore-config` との併用も可能です。
+
+- Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`
+- Verification keys: `verification.<enabled|maxFindings|timeoutMs>`
+- Judge keys: `judge.<mode|provider|timeoutMs>`
+
+未知の key は拒否されます。boolean / numeric config keys は schema の型へ変換し、string keys は文字列のまま保持した後、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 を設定できます。
 

package/README.md

@@ -34,6 +34,54 @@ With a single backend enabled, one agent runs as `combined_reviewer` instead of
 
 No global install is required. Run Kyoso through `npx` or `bunx`.
 
+### Integration modes
+
+| Mode                | Installs                           | MCP | Clients             |
+| ------------------- | ---------------------------------- | --: | ------------------- |
+| Marketplace Plugin  | Skill plus local stdio MCP         | Yes | Codex               |
+| CLI plus Skill-only | npm CLI plus Skill                 |  No | Codex / Claude Code |
+| Manual setup        | Manual MCP registration plus Skill | Yes | Codex / Claude Code |
+
+#### Codex Marketplace Plugin
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin list --marketplace kyoso --available --json
+codex plugin add kyoso@kyoso
+codex plugin list --marketplace kyoso --json
+```
+
+You can also select Kyoso from the Codex desktop Plugins page or `/plugins`. Refresh or restart the desktop app if a newly added marketplace is not visible. Remove the Plugin with `codex plugin remove kyoso@kyoso`.
+
+The Plugin bundles the Skill and an MCP definition pinned to an exact published Kyoso CLI version; it does not bundle the CLI itself. Its first MCP start needs network access to npm. A cached package may work offline, but offline startup is not guaranteed. The manifest's `Read` capability is display metadata, not additional filesystem authorization.
+
+The Plugin Skill declares the bundled `kyoso` MCP server as a dependency, so explicit Kyoso reviews are directed through MCP rather than a CLI fallback. In Codex Auto mode, the first MCP invocation can still require approval because Kyoso tools do not declare annotations; choose "Allow and don't ask me again" to retain that approval.
+
+If you disable the bundled Plugin MCP, treat the Plugin Skill as unavailable: re-enable it, or remove the Plugin and install CLI plus Skill-only instead. The Plugin is not a CLI-fallback mode.
+
+#### CLI plus Skill-only
+
+```bash
+# Global CLI and Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI and Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Replace `codex` with `claude-code` for Claude Code. Dry-run remains the default. `--skill-only` never reads or writes MCP configuration and cannot be combined with `--runner` or `--command`.
+
+Skill-only intentionally does not declare an MCP dependency. When it reaches an `npx` or `bunx` package-runner fallback, Codex Auto mode can request a sandbox network escalation approval; installing `kyoso` on `PATH` avoids that fallback.
+
+#### Migration
+
+- Manual MCP to CLI plus Skill: install the CLI and Skill first, then run `codex mcp remove kyoso` or `claude mcp remove kyoso --scope local|project|user`.
+- CLI plus Skill to Plugin: add the Plugin, confirm it is enabled, then remove the manual MCP registration. Manually copied Skills are not removed automatically.
+- Plugin to CLI plus Skill: install the CLI and Skill first, then run `codex plugin remove kyoso@kyoso`.
+- CLI plus Skill back to manual MCP: run `kyoso setup codex --write` or `kyoso setup claude-code --write`.
+
 ### Claude Only / Codex Only
 
 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`.
@@ -137,11 +185,13 @@ Known distribution risk: `@modelcontextprotocol/server` has no stable release ye
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
 kyoso security --goal "Review this auth diff" --diff changes.patch
-kyoso diff --base main --head HEAD
+kyoso diff --base main --head HEAD --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -204,9 +254,13 @@ MCP stdout is reserved for protocol messages. Logs go to stderr or local audit t
 
 The bundled `kyoso-review` skill is intentionally narrow. It should trigger only when you explicitly ask for Kyoso, multi-agent review, plan review, security review, CISA Secure by Design review, or diff review.
 
-`npx @kyo-so/cli setup codex --write` and `bunx @kyo-so/cli setup codex --write` copy it to `.agents/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.agents/skills/kyoso-review/`.
+The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y @kyo-so/cli`, then `bunx @kyo-so/cli`. The package-runner fallbacks may need network access and can drift to a newer version, so an installed CLI is the normal MCP-less path.
+
+`kyoso setup codex --write --skill-only` copies the canonical Skill directory to `.agents/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.agents/skills/kyoso-review/`.
 
-`npx @kyo-so/cli setup claude-code --write` and `bunx @kyo-so/cli setup claude-code --write` copy it to `.claude/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.claude/skills/kyoso-review/`.
+`kyoso setup claude-code --write --skill-only` copies it to `.claude/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.claude/skills/kyoso-review/`.
+
+Managed installs record the canonical directory digest and CLI version in `.kyoso-install.json`. Exact current or known historical copies are adopted and updated automatically. A changed or unknown copy is reported as a conflict and left untouched; `--force` replaces only that Skill directory and never removes or overwrites MCP configuration.
 
 ## Safety Model
 
@@ -220,6 +274,10 @@ Repository content, plans, diffs, and selected files are treated as untrusted da
 
 Finding titles are normalized to concise English for aggregation; evidence, recommendations, and summaries can remain in the user's language.
 
+Audit traces use a trusted user state root rather than a workspace-controlled path. On supported POSIX runtimes, Kyoso uses an absolute `$XDG_STATE_HOME` when available, otherwise `$HOME/.local/state`, only after ownership, permission, containment, and symlink checks succeed. It never silently falls back to another location: if verification or safe open fails, Audit writing is disabled for that review and a sanitized warning is returned while the review continues.
+
+Windows, and environments where the required filesystem capabilities cannot be proven, disable Audit writing fail closed. A hostile process running as the same OS user that can modify the trusted state root or rename an already verified inode is outside this guarantee; protecting against that threat requires an OS sandbox or native dirfd-based support.
+
 ## Agent Auth
 
 Codex uses the local `codex` login when available. No API key is required for the default subscription-backed path.
@@ -265,15 +323,15 @@ Effort works differently: Kyoso does not set an env var for it. Instead, it send
 
 ## Audit
 
-Audit traces are written to:
+On supported POSIX runtimes, Audit traces are written below the user state base (`$XDG_STATE_HOME` when absolute, otherwise `$HOME/.local/state`):
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output and raw file contents are disabled by default.
+`audit.directory` is a logical relative directory (default: `.kyoso/traces`), not a directory in the workspace. Existing workspace `.kyoso/traces` files are not migrated or deleted automatically.
 
-Keep `.kyoso/traces/` out of Git. `kyoso init` adds `.kyoso/` to `.gitignore`, and this repository does the same. If `audit.includeRawAgentOutput` is enabled, traces may persist sensitive review output; delete old traces regularly according to your local retention policy.
+Raw agent output and raw file contents are disabled by default. If `audit.includeRawAgentOutput` is enabled, traces may persist sensitive review output; delete old traces according to your local retention policy. On Windows or an environment without proven safe filesystem capabilities, Audit trace writing stays disabled and the review returns a sanitized warning.
 
 ## Config
 
@@ -282,7 +340,15 @@ 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`
+- CLI flags such as `--network` and repeatable overrides such as `--set agents.claude.effort=high`
+
+`plan`, `security`, and `diff` accept repeatable `--set <key>=<value>` overrides. Values set on the CLI take precedence over config files, including when `--ignore-config` is used.
+
+- Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`
+- Verification keys: `verification.<enabled|maxFindings|timeoutMs>`
+- Judge keys: `judge.<mode|provider|timeoutMs>`
+
+Unknown keys are rejected. Boolean and numeric config keys are converted to their schema types; string keys remain strings. The complete config is then validated.
 
 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.
 

package/README.zh-CN.md

@@ -36,6 +36,54 @@ Kyoso 不会应用代码更改。
 
 无需全局安装。通过 `npx` 或 `bunx` 运行 Kyoso。
 
+### 集成模式
+
+| 模式               | 安装内容             | MCP | 客户端             |
+| ------------------ | -------------------- | --: | ------------------ |
+| Marketplace Plugin | Skill＋本地stdio MCP |  有 | Codex              |
+| CLI＋Skill-only    | npm CLI＋Skill       |  无 | Codex／Claude Code |
+| 手动setup          | 手动MCP注册＋Skill   |  有 | Codex／Claude Code |
+
+#### Codex Marketplace Plugin
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin list --marketplace kyoso --available --json
+codex plugin add kyoso@kyoso
+codex plugin list --marketplace kyoso --json
+```
+
+也可以在Codex desktop的Plugins page或`/plugins`中选择Kyoso。若新添加的Marketplace未显示，请refresh／restart desktop app。使用`codex plugin remove kyoso@kyoso`删除Plugin。
+
+Plugin包含Skill和pin到已发布Kyoso CLI精确版本的MCP定义，但不包含CLI本体。MCP首次启动需要访问npm网络。已缓存的package可能可以offline启动，但不作保证。manifest中的`Read` capability仅是显示metadata，不会授予额外filesystem权限。
+
+Plugin中的Skill将内置的`kyoso` MCP server声明为dependency，因此显式Kyoso review会通过MCP而不是CLI fallback。在Codex Auto mode中，Kyoso tools未声明annotations，首次MCP调用仍可能需要approval；选择“Allow and don't ask me again”即可保留该许可。
+
+如果禁用内置Plugin MCP，应将Plugin Skill视为不可用：重新启用MCP，或移除Plugin并改用CLI＋Skill-only。Plugin不是CLI fallback mode。
+
+#### CLI＋Skill-only
+
+```bash
+# Global CLI＋Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI＋Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Claude Code请将`codex`替换为`claude-code`。默认仍为dry-run。`--skill-only`不会读写MCP配置，也不能与`--runner`／`--command`组合使用。
+
+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 可用时运行。请在 `kyoso.toml` 中禁用缺失的 backend；示例见 `examples/claude-only.toml` 和 `examples/codex-only.toml`。
@@ -136,11 +184,13 @@ Nix dev shell 会 pin Node.js 24 和 nixpkgs 提供的 Bun version。确认 `.en
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
 kyoso security --goal "Review this auth diff" --diff changes.patch
-kyoso diff --base main --head HEAD
+kyoso diff --base main --head HEAD --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -203,9 +253,13 @@ MCP stdout 专用于 protocol messages。Logs 会写到 stderr 或 local audit t
 
 内置的 `kyoso-review` skill 有意保持范围很窄。只有当你明确请求 Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review 或 diff review 时，才应触发它。
 
-`npx @kyo-so/cli setup codex --write` 和 `bunx @kyo-so/cli setup codex --write` 默认将其复制到 `.agents/skills/kyoso-review/`。添加 `--global` 会复制到 `~/.agents/skills/kyoso-review/`。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。
+
+`kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
-`npx @kyo-so/cli setup claude-code --write` 和 `bunx @kyo-so/cli setup claude-code --write` 默认将其复制到 `.claude/skills/kyoso-review/`。添加 `--global` 会复制到 `~/.claude/skills/kyoso-review/`。
+`kyoso setup claude-code --write --skill-only`默认复制到`.claude/skills/kyoso-review/`。添加`--global`后复制到`~/.claude/skills/kyoso-review/`。
+
+managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`只替换该Skill directory，不会删除或覆盖MCP配置。
 
 ## Safety Model
 
@@ -219,6 +273,10 @@ Repository content、plans、diffs 和 selected files 在 backend prompts 中被
 
 Finding title 会为 aggregation 规范化为简洁英文；evidence、recommendations 和 summaries 可以继续使用用户的语言。
 
+Audit trace 写入受信任的 user state root，而不是由 workspace 控制的 path。在受支持的 POSIX runtime 上，Kyoso 会在可用时使用 absolute `$XDG_STATE_HOME`，否则使用 `$HOME/.local/state`；只有 owner、permission、containment 和 symlink 检查均成功时才会写入。验证或 safe open 失败时，它不会静默 fallback 到其他 location：会为该 review fail-close 禁用 Audit 写入，返回 sanitized warning，并继续 review。
+
+Windows，以及无法证明所需 filesystem capability 的环境，会 fail-close 禁用 Audit 写入。能够修改 trusted state root 或 rename 已验证 inode 的 same OS user hostile process 不在此保证范围内；防御该威胁需要 OS sandbox 或 native dirfd-based support。
+
 ## Agent Auth
 
 可用时，Codex 使用 local `codex` login。默认 subscription-backed path 不需要 API key。
@@ -264,15 +322,15 @@ effort 的工作方式不同：Kyoso 不会为它设置 env var，而是在每
 
 ## Audit
 
-Audit traces 写入：
+在受支持的 POSIX runtime 上，Audit traces 会写入 user state base（absolute `$XDG_STATE_HOME`，否则 `$HOME/.local/state`）下：
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output 和 raw file contents 默认禁用。
+`audit.directory`是 logical relative directory（默认：`.kyoso/traces`），不是 workspace 内的 directory。现有 workspace `.kyoso/traces`不会被自动迁移或删除。
 
-不要将 `.kyoso/traces/` 提交到 Git。`kyoso init` 会把 `.kyoso/` 添加到 `.gitignore`，本 repository 也同样如此。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 定期删除旧 traces。
+Raw agent output 和 raw file contents 默认禁用。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning。
 
 ## Config
 
@@ -281,7 +339,15 @@ 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
+- `--network` 等 CLI flags，以及 `--set agents.claude.effort=high` 等可重复的 overrides
+
+`plan`、`security` 和 `diff` 接受可重复的 `--set <key>=<value>` overrides。CLI 指定的值优先于 config files，也可以与 `--ignore-config` 一起使用。
+
+- Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`
+- Verification keys: `verification.<enabled|maxFindings|timeoutMs>`
+- Judge keys: `judge.<mode|provider|timeoutMs>`
+
+未知 key 会被拒绝。Boolean / numeric config keys 会转换为 schema 类型，string keys 保持字符串，然后重新验证完整 config。
 
 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。
 

package/dist/audit/safeTraceFile.d.ts

@@ -0,0 +1,20 @@
+import type { FileHandle } from "node:fs/promises";
+export declare const AUDIT_WARNING_UNSUPPORTED_OPEN_CAPABILITY = "AUDIT_DISABLED_UNSUPPORTED_CAPABILITY: Audit trace writing requires unavailable filesystem capabilities.";
+export type AuditOpenConstants = Partial<Record<"O_CREAT" | "O_EXCL" | "O_APPEND" | "O_WRONLY" | "O_NOFOLLOW" | "O_NONBLOCK", number>>;
+export type OpenVerifiedTraceFileOptions = {
+    kyosoRoot: string;
+    workspaceHash: string;
+    logicalDirectory: string;
+    date: string;
+    traceId: string;
+    uid: number;
+    workspaceRoot: string;
+    openConstants?: AuditOpenConstants;
+    beforeOpen?: (tracePath: string) => Promise<void> | void;
+};
+export type OpenedTraceFile = {
+    handle: FileHandle;
+    tracePath: string;
+};
+export declare function openVerifiedTraceFile(options: OpenVerifiedTraceFileOptions): Promise<OpenedTraceFile>;
+export declare function secureOpenFlags(provided?: AuditOpenConstants): number | undefined;

package/dist/audit/stateRoot.d.ts

@@ -0,0 +1,38 @@
+export declare const AUDIT_WARNING_DIRECTORY_IGNORED = "AUDIT_DIRECTORY_IGNORED: Audit directory is invalid; using the default logical directory.";
+export declare const AUDIT_WARNING_UNSUPPORTED_PLATFORM = "AUDIT_DISABLED_UNSUPPORTED_PLATFORM: Audit trace writing is unavailable on this platform.";
+export declare const AUDIT_WARNING_UNSUPPORTED_CAPABILITY = "AUDIT_DISABLED_UNSUPPORTED_CAPABILITY: Audit trace writing requires unavailable filesystem capabilities.";
+export declare const AUDIT_WARNING_UNSAFE_STATE_ROOT = "AUDIT_DISABLED_UNSAFE_STATE_ROOT: Audit state root could not be verified.";
+export type AuditRuntimeOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    getuid?: () => number | undefined;
+};
+export type ResolvedAuditStateRoot = {
+    stateBase: string;
+    kyosoRoot: string;
+    workspaceRoot: string;
+    workspaceHash: string;
+    logicalDirectory: string;
+    uid: number;
+    warnings: string[];
+};
+export type AuditStateRootResolution = ResolvedAuditStateRoot | {
+    warnings: string[];
+};
+export type AuditStateRootCapability = {
+    available: boolean;
+};
+export declare function resolveAuditStateRoot(options: {
+    cwd: string;
+    directory: string;
+} & AuditRuntimeOptions): Promise<AuditStateRootResolution>;
+export declare function inspectAuditStateRootCapability(options: {
+    cwd: string;
+} & AuditRuntimeOptions): Promise<AuditStateRootCapability>;
+export declare function ensureTrustedDirectory(options: {
+    root: string;
+    segments: string[];
+    uid: number;
+    workspaceRoot?: string;
+}): Promise<string>;
+export declare function isResolvedAuditStateRoot(resolution: AuditStateRootResolution): resolution is ResolvedAuditStateRoot;

package/dist/audit/trace.d.ts

@@ -1,12 +1,24 @@
+import type { FileHandle } from "node:fs/promises";
+import { type AuditRuntimeOptions } from "./stateRoot.js";
+import { type AuditOpenConstants } from "./safeTraceFile.js";
+export declare const AUDIT_WARNING_WRITE_FAILED = "AUDIT_WRITE_FAILED: Audit trace writing failed; no further audit events will be written.";
+export declare const AUDIT_WARNING_FINALIZE_FAILED = "AUDIT_FINALIZE_FAILED: Audit trace close failed.";
+export declare const AUDIT_WARNING_WRITE_AFTER_FINALIZE = "AUDIT_WRITE_AFTER_FINALIZE: Audit trace is already finalized.";
 export type TraceWriter = {
-    tracePath?: string;
+    readonly tracePath?: string;
     warnings: string[];
     write(event: Record<string, unknown>): Promise<void>;
+    finalize(): Promise<void>;
 };
-export declare function createTraceWriter(options: {
+export type TraceWriterOptions = {
     enabled: boolean;
     directory: string;
     traceId: string;
     cwd: string;
     includeRawAgentOutput?: boolean;
-}): TraceWriter;
+    openConstants?: AuditOpenConstants;
+    beforeOpen?: (tracePath: string) => Promise<void> | void;
+    closeHandle?: (handle: FileHandle) => Promise<void>;
+    writeChunk?: (handle: FileHandle, buffer: Buffer, offset: number) => Promise<number>;
+} & AuditRuntimeOptions;
+export declare function createTraceWriter(options: TraceWriterOptions): TraceWriter;