@kyo-so/cli 0.11.0 → 0.13.0

package/README.md

@@ -48,11 +48,9 @@ When in doubt, pick the Marketplace Plugin: two commands install the Skill and t
 
 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 `kyoso setup ... --with-openrouter` output and manual setup examples remain user-managed client-registration templates. Marketplace Plugin `0.4.0` is pinned to `@kyo-so/cli@0.10.0`.
-
 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. 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.
 
-Marketplace Plugin `0.4.0` exposes the `OPENROUTER_API_KEY` variable name to its MCP process; it does not store a credential value. Kyoso forwards the value only to a Codex child that explicitly selects OpenRouter, and treats an unexpanded placeholder as missing.
+For OpenRouter key forwarding through the Plugin, see [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in).
 
 #### CLI plus Skill-only
 
@@ -159,7 +157,7 @@ Manual setup examples are kept in `examples/codex-config.toml` and `examples/cla
 ```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 --set agents.claude.effort=high
+kyoso diff --base main --head HEAD --focus architecture --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
@@ -179,7 +177,7 @@ kyoso plan \
   --file src/auth/callback.ts
 ```
 
-Read the result from the top down: `Decision` is the deterministic gate outcome, `Findings` are the required changes, and `Tests to Add` are the regression checks Kyoso expects before approval.
+Read the result from the top down: `Decision` is the deterministic gate outcome, `Coverage` shows which required lenses and perspectives ran, and each finding's `disposition` says whether it blocks or only informs the review (see [Review contract and finding admission](#review-contract-and-finding-admission)).
 
 Run a CISA Secure by Design security review against a patch:
 
@@ -190,7 +188,7 @@ kyoso security \
   --json
 ```
 
-In JSON output, `cisaSecureByDesign` shows the four gate dimensions. A `fail` in customer security outcomes blocks the review; warning-level dimensions usually produce `approve_with_changes`.
+In JSON output, `cisaSecureByDesign` shows the configured dimensions and whether gate enforcement is enabled. Raw backend dimension statuses are ignored for computation and decision; accompanying notes remain advisory. Kyoso computes statuses from admitted findings. An enforced `fail` in customer security outcomes blocks the review.
 
 Register Kyoso with Codex or Claude Code as an MCP server, then call `plan_review` from the client:
 
@@ -228,7 +226,7 @@ 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.
 
-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.
+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. If a typed [review contract](#review-contract-and-finding-admission) contains non-goals or accepted risks and MCP is unavailable, the Skill stops because the CLI fallback can preserve only `focus`.
 
 `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/`.
 
@@ -236,6 +234,40 @@ The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` o
 
 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.
 
+## Review contract and finding admission
+
+Every review includes a non-removable safety floor: correctness, regression, security boundaries, secrets/injection, data integrity, and public contract. Kyoso also adds supply-chain, privacy, and resource-amplification lenses when the review shape calls for them. User-global `reviewPolicy.additionalLenses` can add more lenses; it cannot remove the floor.
+
+MCP and library callers can pass a typed `reviewContract`; CLI callers can add repeatable `--focus <lens>` values:
+
+```json
+{
+  "reviewContract": {
+    "focus": ["architecture"],
+    "nonGoals": ["Do not redesign the public CLI in this change"],
+    "acceptedRisks": [
+      {
+        "findingFingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "rationale": "Tracked for the next release"
+      }
+    ]
+  }
+}
+```
+
+Only explicit caller-owned values may define non-goals and accepted risks. Repository constraints, plans, diffs, and files remain untrusted context and cannot change review policy. Non-goals bound optional scope but never change disposition through agent-supplied policy labels. Accepted risks affect Medium findings only by exact validated fingerprint. Neither suppresses Critical or High safety findings.
+
+Kyoso recalculates every finding's evidence quality, relation to the reviewed change, stable fingerprint, and disposition:
+
+| Disposition  | Meaning                                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `gate`       | Concrete Critical/High issue introduced or worsened by the change.                                                                        |
+| `actionable` | Concrete Medium issue introduced or worsened by the change.                                                                               |
+| `advisory`   | Optional/Low/Info, accepted Medium, or Medium that is pre-existing, partial, or insufficiently proven.                                    |
+| `disputed`   | Critical/High that is refuted, low-confidence, insufficiently proven, pre-existing, or independently unresolved; requires human judgment. |
+
+Only `gate` and `actionable` findings affect the deterministic decision. A `disputed` finding makes completion incomplete and must not be auto-fixed. `coverage` records required/attempted lenses, required/completed perspectives, and whether independent cross-model review occurred. `Tests to Add` contains at most three concrete regression tests; generic commands and broad test-suite requests are omitted.
+
 ## Configuration
 
 ### Files and precedence
@@ -251,7 +283,9 @@ Kyoso loads config in this order:
 
 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`, and the Codex-only `provider` or a model override while OpenRouter is inherited after user-global authorization, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network settings.
+Project `kyoso.toml` is declarative and does not require trust approval. It can set safe project-scoped keys such as agent `enabled` / `model` / `effort` / `role` / `timeoutMs`, the Codex-only `provider` or a model override while OpenRouter is inherited after user-global authorization, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network/CISA settings.
+
+`entrypoints.*`, `tools.*`, and `reviewPolicy.*` are user-global policy. A disabled entrypoint or tool returns a structured policy block before agents start. `firstClassClient = "codex"`, `workspace.readOnly = true`, `network.mediatedWeb.enabled = false`, and `audit.includeFileContents = false` are fixed or reserved values; unsupported values are rejected instead of acting as no-ops.
 
 Global TOML is for user-owned settings that can launch commands or forward environment variables:
 
@@ -259,9 +293,6 @@ Global TOML is for user-owned settings that can launch commands or forward envir
 [agents.codex]
 command = "bunx"
 args = ["@agentclientprotocol/codex-acp"]
-# Authorize only this exact project directory to select `provider` or override
-# a model while OpenRouter is inherited.
-allowProjectProvider = ["/absolute/path/to/project"]
 
 [agents.codex.env]
 CODEX_CONFIG = '{"model":"gpt-5.5"}'
@@ -271,7 +302,7 @@ CODEX_CONFIG = '{"model":"gpt-5.5"}'
 
 ### Agents
 
-Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`. Codex also supports `agents.codex.provider`: `"openrouter"` selects the external provider, while `"default"` resets an inherited OpenRouter selection to normal Codex behavior; Claude has no provider setting. `agents.codex.allowProjectProvider` is a global-config-only allowlist of absolute project directories: it authorizes only an exact matching project TOML to select `provider` or override `model` while OpenRouter is inherited, with no descendant or glob matching. Project config and `--set` cannot change it, and legacy boolean values are rejected. The `command`, `args`, and `env` keys are also global-config-only (see [Files and precedence](#files-and-precedence)).
+Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`. Codex also supports `agents.codex.provider`: `"openrouter"` selects the external provider, while `"default"` resets an inherited OpenRouter selection to normal Codex behavior; Claude has no provider setting. Selecting the provider from a project requires the global-config-only `agents.codex.allowProjectProvider` allowlist; see [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in) for the full rules. The `command`, `args`, and `env` keys are also global-config-only (see [Files and precedence](#files-and-precedence)).
 
 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` (or `$CODEX_HOME/config.toml` when `CODEX_HOME` is set); Claude uses the adapter default.
 
@@ -315,7 +346,7 @@ model = "openai/o4-mini"
 
 `model` is required and must not be blank when `provider = "openrouter"`. It is an OpenRouter model ID; Kyoso does not validate the catalog or whether that model supports tool calling, so confirm tool support with the provider.
 
-`allowProjectProvider` applies to a project `provider` and to a project `model` override while OpenRouter is inherited; its list must contain the absolute canonical directory containing the resolved project configuration file, not the invocation cwd or a lexical path. A project configuration file (including trusted `kyoso.config.ts`) and an allowlist entry that resolve through symlinks to that directory match; entries resolving elsewhere, or unresolvable paths, fail closed. A user-global `provider = "openrouter"` needs no allowlist entry. An explicit CLI pair of `--set agents.codex.provider=openrouter` and `--set agents.codex.model=<model>` in the same invocation is also allowed without it; a project model cannot supply the CLI override's model. `allowProjectProvider` is not a `--set` path and legacy boolean values are rejected.
+`allowProjectProvider` applies to a project `provider` and to a project `model` override while OpenRouter is inherited; its list must contain the absolute canonical directory containing the resolved project configuration file, not the invocation cwd or a lexical path, with no descendant or glob matching. A project configuration file (including trusted `kyoso.config.ts`) and an allowlist entry that resolve through symlinks to that directory match; entries resolving elsewhere, or unresolvable paths, fail closed. A user-global `provider = "openrouter"` needs no allowlist entry. An explicit CLI pair of `--set agents.codex.provider=openrouter` and `--set agents.codex.model=<model>` in the same invocation is also allowed without it; a project model cannot supply the CLI override's model. `allowProjectProvider` is not a `--set` path and legacy boolean values are rejected.
 
 When a user-global config selects OpenRouter, a project can explicitly opt out with `provider = "default"`. This reset needs neither a model nor authorization, clears the inherited OpenRouter model unless the same layer explicitly supplies a normal Codex model, and prevents OpenRouter key forwarding for that project.
 
@@ -327,9 +358,9 @@ export OPENROUTER_API_KEY="<secret>"
 
 The key is never stored in `kyoso.toml`, Git-managed configuration, Audit traces, or review output. Kyoso forwards it only to the Codex child when this provider is selected, whether it comes from the Kyoso process or explicit `agents.codex.env`. When `provider` is omitted or `provider = "default"`, Kyoso deliberately withholds both sources; a non-empty explicit `agents.codex.env.OPENROUTER_API_KEY` also produces a sanitized warning that it was withheld. The same warning is emitted for a non-empty key in another child configuration, such as `agents.claude.env`, because only the selected Codex OpenRouter child can receive it. Omitting `provider` preserves the existing Codex login, `OPENAI_API_KEY`, `CODEX_API_KEY`, and `CODEX_CONFIG` behavior; removing the line returns to that behavior.
 
-GUI clients may not inherit a shell export. Create a new manual MCP registration with `kyoso setup <client> --write --with-openrouter`, restart the client, then run `kyoso doctor` to confirm that the Kyoso process can detect the key. `kyoso setup` preserves an existing MCP entry instead of rewriting it, so existing registrations need the opt-in allowlist updated manually from [the examples](examples/codex-config.toml).
+The Marketplace Plugin exposes the `OPENROUTER_API_KEY` variable name to its MCP process without storing a credential value. GUI clients may not inherit a shell export. Create a new manual MCP registration with `kyoso setup <client> --write --with-openrouter`, restart the client, then run `kyoso doctor` to confirm that the Kyoso process can detect the key. `kyoso setup` preserves an existing MCP entry instead of rewriting it, so existing registrations need the opt-in allowlist updated manually from [the examples](examples/codex-config.toml).
 
-New manual MCP registrations omit `OPENROUTER_API_KEY` by default. Add it only with `--with-openrouter` after intentionally selecting the provider; existing registrations are never rewritten. In a Claude Code registration, `${OPENROUTER_API_KEY}` must be expanded by the client; Kyoso ignores only a whole unexpanded credential placeholder — `${NAME}`, `$NAME`, or `%NAME%`, with optional surrounding whitespace — and emits a sanitized warning containing only the variable name. Values with any other text are preserved. The same rule applies to custom credential-like names ending in `_KEY`, `_TOKEN`, `_SECRET`, or `_PASSWORD`; non-credential templates are preserved.
+New manual MCP registrations omit `OPENROUTER_API_KEY` by default. Add it only with `--with-openrouter` after intentionally selecting the provider; existing registrations are never rewritten. The `kyoso setup ... --with-openrouter` output and the manual setup examples remain user-managed client-registration templates. In a Claude Code registration, `${OPENROUTER_API_KEY}` must be expanded by the client; Kyoso ignores only a whole unexpanded credential placeholder — `${NAME}`, `$NAME`, or `%NAME%`, with optional surrounding whitespace — and emits a sanitized warning containing only the variable name. Values with any other text are preserved. The same rule applies to custom credential-like names ending in `_KEY`, `_TOKEN`, `_SECRET`, or `_PASSWORD`; non-credential templates are preserved.
 
 Prefer this user-authorized project-scoped opt-in. A global `provider = "openrouter"` is inherited by projects until a project sets `provider = "default"`; merely omitting `provider` does not unset it. The fixed OpenRouter Responses API preset is beta; custom endpoints, provider routing, fallbacks, and judge integration are not exposed. To keep the key bound to that preset, OpenRouter mode rejects a `CODEX_CONFIG` with a top-level `profile` or `profiles` field and rejects a non-object `model_providers` value before launching the child. For an object value, it replaces `model_providers` with only the fixed `kyoso-openrouter` entry and emits a sanitized warning with the discarded-entry count only; provider IDs and configuration values never appear. Apart from those rejected fields, it preserves unrelated `CODEX_CONFIG` fields outside `model`, `model_provider`, and `model_providers`, so no foreign provider configuration can select an endpoint with the key. Claude remains on its configured provider, and the judge does not use `OPENROUTER_API_KEY`.
 
@@ -380,26 +411,46 @@ Team admins should also check organization Usage credits. If credits are enabled
 
 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.
+In single-agent mode, the remaining backend runs once as `combined_reviewer` and covers both implementation and architecture/security perspectives. JSON output includes `reviewMode: "single_agent"`, `agentsUsed`, and `coverage.independentReview: false`; Markdown output states that cross-model verification was not performed. Set user-global `reviewPolicy.multiAgentRequired = true` to make this degraded coverage incomplete and block.
 
 This mode does not provide independent cross-model validation and may retain self-review bias. It still provides a separate read-only review process, temporary snapshots, adversarial review prompts, secret scanning, and deterministic gates.
 
 ### Execution budget and review stopping
 
-Every review has a user-global hard ceiling for model calls, total wall time, streamed agent text (message and thought chunks), and findings per agent:
+Every review has user-global hard ceilings for model calls, total wall time, and streamed agent text (message and thought chunks). Streamed text also has a lower soft-warning threshold, while findings per agent is a soft target:
 
 ```toml
 [reviewBudget]
 maxModelCalls = 4
-maxTotalWallTimeMs = 480000
-maxAgentOutputBytes = 65536
+maxTotalWallTimeMs = 660000
+warnAgentOutputBytes = 524288
+maxAgentOutputBytes = 1048576
 maxFindingsPerAgent = 10
-skipOptionalPhasesWhenTokenUsageUnknown = true
+skipOptionalPhasesWhenTokenUsageUnknown = false
 ```
 
-`reviewBudget` is user-global only: project `kyoso.toml` and `--set` cannot change it. MCP and library requests may lower a ceiling through `options.reviewBudget`, never raise it. Kyoso reserves both primary reviewers before starting either one, uses any residual calls for verification, and treats the LLM judge as advisory. The default judge mode is `deterministic_only`.
+`reviewBudget` is user-global only: project `kyoso.toml` and `--set` cannot change it. MCP and library requests may lower a ceiling through `options.reviewBudget`, never raise it. The 512 KiB warning is non-blocking, the 1 MiB limit cancels the call, and the ten-finding target does not discard additional material findings. Unknown token usage warns and continues by default; an explicit user-global `true` preserves strict optional-phase skipping. Kyoso reserves both primary reviewers before starting either one, uses any residual calls for verification, and treats the LLM judge as advisory. The default judge mode is `deterministic_only`.
 
-The result includes `completion`, `executionBudget`, and `requestFingerprint`; Markdown and Audit show call counts, wall time, output bytes, and reported or unknown token usage. If `completion.status` is `incomplete`, Kyoso returns a normal `block` result with `retryable: false`: the block means review coverage is incomplete, not that a code defect was established. Do not automatically retry the same fingerprint. At one review checkpoint, the bundled Skill permits one initial pass and one confirmation pass only after material fixes; a third pass requires explicit user approval.
+The result includes `completion`, `executionBudget`, and `requestFingerprint`; Markdown and Audit show call counts, wall time, message/thought/total output bytes, and reported, partial, or unknown token usage. Each completed model call can also expose `executionIdentity`, separating the Kyoso route and requested model from provider-reported identity; requested-only values are never presented as provider reports. If `completion.status` is `incomplete`, Kyoso returns a normal `block` result with `retryable: false`: the block means review coverage is incomplete, not that a code defect was established. Do not automatically retry the same fingerprint. At one review checkpoint, the bundled Skill permits one initial pass and one confirmation pass only after material fixes; a third pass requires explicit user approval.
+
+### Timeouts
+
+Default agent timeouts are 600 seconds for both Codex and Claude; the verification round defaults to 90 seconds. The review-wide deadline defaults to 660 seconds (`reviewBudget.maxTotalWallTimeMs`), leaving the standard 60-second finalization margin after the default parallel primary phase. Each phase uses the remaining deadline rather than extending it. `kyoso doctor` reports the configured sequential phase time and a recommended review-wide deadline with a 10% or 60-second margin, whichever is larger. It includes an LLM judge timeout only when the judge mode permits it and a direct-provider credential is available.
+
+This repository's 15-minute primary plus 15-minute verification dogfooding preset uses the following user-global override:
+
+```toml
+[reviewBudget]
+maxTotalWallTimeMs = 2100000
+```
+
+The Codex Plugin and newly generated manual Codex registrations use `tool_timeout_sec = 2160`, leaving 60 seconds beyond that 35-minute Kyoso deadline. Existing manual registrations are preserved by `kyoso setup` and must be updated manually. The Claude Code Plugin manifest does not set a client tool timeout; launch Claude Code with the equivalent millisecond value, then restart the client:
+
+```bash
+MCP_TOOL_TIMEOUT=2160000 claude
+```
+
+Increasing the client timeout does not extend Kyoso's internal review-wide deadline. For other presets, keep the client timeout longer than `reviewBudget.maxTotalWallTimeMs`.
 
 ### Verification
 
@@ -414,7 +465,7 @@ timeoutMs = 90000
 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. A skipped, failed, budget-exhausted, or overflowed verification leaves the finding marked `not_verified` and returns incomplete coverage. `allowDemotion` is reserved for a future opt-in phase and is currently a no-op.
+When enabled, Kyoso asks the agent that did not report each high/critical single-source finding to try to refute it. Verification is annotate-only: it can update confidence and notes, but never changes severity. A refuted or otherwise unresolved material finding becomes `disputed`; skipped, failed, budget-exhausted, or overflowed verification leaves it `not_verified` and returns incomplete coverage. This preserves the original risk signal instead of letting a second model silently demote it. `allowDemotion` is accepted for compatibility but reserved; either value has no demotion effect.
 
 ### Judge
 
@@ -426,10 +477,6 @@ Judge keys: `judge.<mode|provider|timeoutMs>`. Judge LLMs are optional and defau
 
 Judge defaults intentionally use lightweight models. For a stronger judge, set `KYOSO_ANTHROPIC_JUDGE_MODEL` to a Sonnet-class model such as `claude-sonnet-5`.
 
-### Timeouts
-
-Default agent timeouts are Codex 120 seconds and Claude 300 seconds; the verification round defaults to 90 seconds. The review-wide deadline defaults to 480 seconds, and each phase uses the remaining deadline rather than extending it. MCP clients should allow at least 480 seconds for tool calls.
-
 ### Audit
 
 On supported POSIX runtimes, Audit traces are written below the user state base (`$XDG_STATE_HOME` when absolute, otherwise `$HOME/.local/state`):
@@ -440,7 +487,21 @@ On supported POSIX runtimes, Audit traces are written below the user state base
 
 `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.
 
-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 (see [Safety Model](#safety-model)).
+Generate a read-only budget report from the installed package by supplying an absolute trusted trace directory explicitly:
+
+```bash
+kyoso-budget-report --trace-dir /absolute/path/to/traces --json
+```
+
+From a source checkout, use the package script:
+
+```bash
+bun run audit:budget-report -- --trace-dir /absolute/path/to/traces --json
+```
+
+The report recursively reads regular `.jsonl` files only, skips symlinks, and never infers a trace path. It groups calls by agent, kind, provider route, requested model, and requested/reported identity status; reports separate all-call and normal-path nearest-rank p50/p95/p99/max byte distributions, token-usage reporting rates, output-warning/limit rates, and completion/skip reasons; and never converts bytes into estimated tokens or cost. A normal-path call explicitly has `resultStatus = "completed"` and no `errorCode`; ambiguous historical events remain in all-call statistics only. Top-level byte distributions and output-warning/hard-limit call rates use primary and verifier calls; judge calls remain in all-call and per-execution totals but do not dilute recalibration metrics. Warning call rates include only warning events correlated to a completed call with the same trace, kind, and agent; duplicate or orphan warning events are reported separately. The JSON exposes fixed ingestion bounds as `inputLimits`, and the command aborts instead of truncating when file, byte, line, event, call, review, warning, group, reason, or directory bounds are exceeded. Traversal runs in a dedicated worker whose validated current directory is bound to the supplied root's device and inode; recursive descent revalidates each directory identity, so replacing and restoring the lexical root cannot redirect reads. File reads use no-follow, non-blocking opens and never consume beyond the discovered size; the report aborts when the platform cannot provide those open capabilities. Metadata sanitization is defense in depth, so supply only an operator-trusted trace directory. For recalibration, keep a soft warning at least twice the normal-path p99, place the hard breaker well above the warning so its normal trigger rate stays near zero, and inspect unknown token-usage rates by provider/model before changing policy.
+
+Raw agent output is disabled by default. `audit.includeFileContents` is reserved and fixed to `false`; file contents are never persisted through that setting. 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 (see [Safety Model](#safety-model)).
 
 ## Safety Model
 
@@ -460,6 +521,12 @@ Windows, and environments where the required filesystem capabilities cannot be p
 
 ## Migration
 
+### Upgrade notes
+
+- Move any project `tools.*` settings from `kyoso.toml` to user-global config. Project-owned tool availability is now rejected so repository content cannot disable reviews.
+
+### Switching integration modes
+
 - 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`.
@@ -467,7 +534,7 @@ Windows, and environments where the required filesystem capabilities cannot be p
 
 ## Troubleshooting
 
-- MCP timeout: set client tool timeouts to at least 360 seconds, or at least 480 seconds when `verification.enabled` is true. See [Timeouts](#timeouts) for the Kyoso defaults.
+- MCP timeout: keep the client timeout longer than the review-wide deadline. For the 35-minute preset, use 2160 seconds in Codex or `MCP_TOOL_TIMEOUT=2160000` in Claude Code. See [Timeouts](#timeouts).
 - Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx @kyo-so/cli` resolution after publish.
 - Deprecated TypeScript config: untrusted `kyoso.config.ts` is skipped unless you pass `--trust-config`; prefer `kyoso.toml`.
 - OpenRouter key missing: confirm a non-empty Codex `model`, an `OPENROUTER_API_KEY` forwarded to the Kyoso process, and a restarted client; run `kyoso doctor`. Marketplace Plugin `0.4.0` and later forward this variable name to the Kyoso process; earlier versions do not. Existing MCP registrations are not rewritten by setup.

package/README.zh-CN.md

@@ -50,11 +50,9 @@ Kyoso 不会应用代码更改。
 
 Plugin包含Skill和pin到已发布Kyoso CLI精确版本的MCP定义，但不包含CLI本体。MCP首次启动需要访问npm网络。已缓存的package可能可以offline启动，但不作保证。manifest中的`Read` capability仅是显示metadata，不会授予额外filesystem权限。
 
-`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例仍是用户管理的客户端注册模板。Marketplace Plugin `0.4.0` pin 到 `@kyo-so/cli@0.10.0`。
-
 Plugin中的Skill将内置的`kyoso` MCP server声明为dependency，因此显式Kyoso review会通过MCP而不是CLI fallback。如果禁用内置Plugin MCP，应将Plugin Skill视为不可用：重新启用MCP，或移除Plugin并改用CLI＋Skill-only。Plugin不是CLI fallback mode。
 
-Marketplace Plugin `0.4.0` 向 MCP process 暴露 `OPENROUTER_API_KEY` 变量名，但不保存 credential 值。Kyoso 仅将该值传给显式选择 OpenRouter 的 Codex child，并将未展开的 placeholder 视为未设置。
+关于通过 Plugin 转发 OpenRouter key，请参阅 [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in)。
 
 #### CLI＋Skill-only
 
@@ -161,7 +159,7 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 ```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 --set agents.claude.effort=high
+kyoso diff --base main --head HEAD --focus architecture --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
@@ -181,7 +179,7 @@ kyoso plan \
   --file src/auth/callback.ts
 ```
 
-按从上到下的顺序阅读结果：`Decision` 是 deterministic gate outcome，`Findings` 是 required changes，`Tests to Add` 是 Kyoso 在 approval 前期望的 regression checks。
+按从上到下的顺序阅读结果：`Decision` 是 deterministic gate outcome，`Coverage` 显示已执行的必需 lenses 和 perspectives，每个 finding 的 `disposition` 说明它会 block 还是仅供参考（参见 [Review contract 与 finding admission](#review-contract-与-finding-admission)）。
 
 对 patch 运行 CISA Secure by Design security review：
 
@@ -192,7 +190,7 @@ kyoso security \
   --json
 ```
 
-在 JSON output 中，`cisaSecureByDesign` 会显示四个 gate dimensions。customer security outcomes 中的 `fail` 会 block review；warning-level dimensions 通常会产生 `approve_with_changes`。
+在 JSON output 中，`cisaSecureByDesign` 会显示已配置 dimensions 以及 gate enforcement 是否启用。backend 返回的 raw dimension status 不参与计算或 decision；附带的 notes 仅作为 advisory 保留。Kyoso 根据 admitted findings 计算 status。enforcement 启用时，customer security outcomes 的 `fail` 会 block review。
 
 将 Kyoso 注册为 Codex 或 Claude Code 的 MCP server，然后从 client 调用 `plan_review`：
 
@@ -230,7 +228,7 @@ 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 时，才应触发它。
 
-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。
+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。如果 typed [review contract](#review-contract-与-finding-admission) 包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
 
 `kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
@@ -238,6 +236,40 @@ Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装
 
 managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`只替换该Skill directory，不会删除或覆盖MCP配置。
 
+## Review contract 与 finding admission
+
+每次 review 都包含不可移除的 safety floor：correctness、regression、security boundaries、secrets/injection、data integrity 和 public contract。Kyoso 还会根据 review 形状添加 supply chain、privacy 和 resource amplification lenses。user-global `reviewPolicy.additionalLenses` 可以添加观点评审，但不能移除 floor。
+
+MCP / library caller 可以传入 typed `reviewContract`；CLI caller 可以重复指定 `--focus <lens>`：
+
+```json
+{
+  "reviewContract": {
+    "focus": ["architecture"],
+    "nonGoals": ["本次变更不重新设计 public CLI"],
+    "acceptedRisks": [
+      {
+        "findingFingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "rationale": "在下一版本中继续跟踪"
+      }
+    ]
+  }
+}
+```
+
+只有 caller 明确提供的 user-owned values 才能定义 non-goals 和 accepted risks。repository constraints、plans、diffs 和 files 仍是 untrusted context，不能改变 review policy。non-goals 只限定 optional scope，不会通过 agent 提供的 policy label 改变 disposition。accepted risks 仅在 validated fingerprint 完全匹配时影响 Medium finding。两者都不会抑制 Critical / High safety findings。
+
+Kyoso 会重新计算每个 finding 的 evidence quality、与被审查变更的关系、stable fingerprint 和 disposition：
+
+| Disposition  | 含义                                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| `gate`       | 由变更引入或加剧，且具有具体证据的 Critical / High 问题。                                          |
+| `actionable` | 由变更引入或加剧，且具有具体证据的 Medium 问题。                                                   |
+| `advisory`   | optional / Low / Info、accepted Medium，或属于pre-existing、partial、证据不足的Medium。            |
+| `disputed`   | refuted、low-confidence、证据不足、pre-existing或独立review未解决的Critical / High；需要人工判断。 |
+
+只有 `gate` 和 `actionable` findings 会影响 deterministic decision。`disputed` finding 会使 completion incomplete，且不得自动修复。`coverage` 记录 required/attempted lenses、required/completed perspectives，以及是否完成 independent cross-model review。`Tests to Add` 最多包含3个具体 regression tests；generic commands 和宽泛的 test-suite 请求会被省略。
+
 ## Configuration
 
 ### Files and precedence
@@ -253,7 +285,9 @@ Kyoso 按以下顺序 load config：
 
 未知 key 会被拒绝。Boolean / numeric config keys 会转换为 schema 类型，string keys 保持字符串，然后重新验证完整 config。
 
-Project `kyoso.toml` 是 declarative config，不需要 trust approval。它可以设置 tools toggles、agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、经过 user global authorization 的 Codex `provider` 或继承 OpenRouter 时的 model 覆盖、workspace byte limits 和 additive `workspace.deny`、verification settings、advisory judge settings，以及 tightening-only security/network settings。
+Project `kyoso.toml` 是 declarative config，不需要 trust approval。它可以设置 agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、经过 user global authorization 的 Codex `provider` 或继承 OpenRouter 时的 model 覆盖、workspace byte limits 和 additive `workspace.deny`、verification settings、advisory judge settings，以及 tightening-only security/network/CISA settings。
+
+`entrypoints.*`、`tools.*` 和 `reviewPolicy.*` 是 user-global policy。entrypoint 或 tool 被禁用时，Kyoso 会在启动 agents 前返回 structured policy block。`firstClassClient = "codex"`、`workspace.readOnly = true`、`network.mediatedWeb.enabled = false` 和 `audit.includeFileContents = false` 是 fixed / reserved values；不支持的值会被拒绝，而不是成为 no-op。
 
 Global TOML 用于 user-owned settings，包括 command 启动和 env forwarding。
 
@@ -261,9 +295,6 @@ Global TOML 用于 user-owned settings，包括 command 启动和 env forwarding
 [agents.codex]
 command = "bunx"
 args = ["@agentclientprotocol/codex-acp"]
-# 仅授权此精确 project directory 选择 `provider`，或在继承 OpenRouter 时
-# 覆盖 model。
-allowProjectProvider = ["/absolute/path/to/project"]
 
 [agents.codex.env]
 CODEX_CONFIG = '{"model":"gpt-5.5"}'
@@ -273,7 +304,7 @@ CODEX_CONFIG = '{"model":"gpt-5.5"}'
 
 ### Agents
 
-Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`。Codex 还支持 `agents.codex.provider`：`"openrouter"` 选择 external provider，而 `"default"` 会将继承的 OpenRouter 选择重置为正常 Codex behavior；Claude 没有 provider 设置。`agents.codex.allowProjectProvider` 只能在 global config 中设置，它是 absolute project directory allowlist：只有完全匹配的 project TOML 能选择 `provider`，或在继承 OpenRouter 时覆盖 `model`；不匹配子目录或 glob。不能通过 project config 或 `--set` 修改，legacy boolean 值会被拒绝。`command` / `args` / `env` 也只能在 global config 中设置（参见 [Files and precedence](#files-and-precedence)）。
+Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`。Codex 还支持 `agents.codex.provider`：`"openrouter"` 选择 external provider，而 `"default"` 会将继承的 OpenRouter 选择重置为正常 Codex behavior；Claude 没有 provider 设置。从 project 选择 provider 需要只能在 global config 中设置的 `agents.codex.allowProjectProvider` allowlist；完整规则请参阅 [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in)。`command` / `args` / `env` 也只能在 global config 中设置（参见 [Files and precedence](#files-and-precedence)）。
 
 省略 `agents.<name>.model` 或 `agents.<name>.effort` 时，会使用各 agent 自身的 default。Codex 使用 local Codex config，例如 `~/.codex/config.toml`（若已设置`CODEX_HOME`，则为`$CODEX_HOME/config.toml`）；Claude 使用 adapter default。
 
@@ -317,7 +348,7 @@ model = "openai/o4-mini"
 
 当 `provider = "openrouter"` 时，`model` 必须存在且不能是空白。它是 OpenRouter model ID；Kyoso 不会 validate model catalog 或该 model 是否支持 tool calling，请向 provider 确认 tool support。
 
-`allowProjectProvider` 适用于 project `provider`，以及继承 OpenRouter 时 project 对 `model` 的覆盖；list 必须完全匹配包含已解析 project config file 的 canonical directory 的 absolute path，而不是 invocation cwd 或 lexical path。project config file（包括受信任的 `kyoso.config.ts`）与 allowlist entry 都会通过 symlink 解析到该 directory；解析到同一 directory 的 entry 会匹配，解析到其他位置或无法解析的 path 会 fail closed。user-global `provider = "openrouter"` 不需要 allowlist entry。直接选择 CLI 时，必须在同一 invocation 中同时使用 `--set agents.codex.provider=openrouter` 和 `--set agents.codex.model=<model>`；project model 不能为该 CLI provider override 补足 model。`allowProjectProvider` 不是 `--set` path，legacy boolean 值会被拒绝。
+`allowProjectProvider` 适用于 project `provider`，以及继承 OpenRouter 时 project 对 `model` 的覆盖；list 必须完全匹配包含已解析 project config file 的 canonical directory 的 absolute path，而不是 invocation cwd 或 lexical path。不匹配子目录或 glob。project config file（包括受信任的 `kyoso.config.ts`）与 allowlist entry 都会通过 symlink 解析到该 directory；解析到同一 directory 的 entry 会匹配，解析到其他位置或无法解析的 path 会 fail closed。user-global `provider = "openrouter"` 不需要 allowlist entry。直接选择 CLI 时，必须在同一 invocation 中同时使用 `--set agents.codex.provider=openrouter` 和 `--set agents.codex.model=<model>`；project model 不能为该 CLI provider override 补足 model。`allowProjectProvider` 不是 `--set` path，legacy boolean 值会被拒绝。
 
 当 user-global config 选择 OpenRouter 时，project 可以用 `provider = "default"` 显式 opt-out。这个 reset 不需要 model 或 authorization；除非同一 layer 明确提供普通 Codex model，它还会清除继承的 OpenRouter model，并且不会为该 project forward OpenRouter key。
 
@@ -329,9 +360,9 @@ export OPENROUTER_API_KEY="<secret>"
 
 key 不会存入 `kyoso.toml`、Git 管理的 config、Audit trace 或 review output。无论它来自 Kyoso process 还是显式 `agents.codex.env`，只有选中该 provider 时，Kyoso 才会将它 forward 给 Codex child。当省略 `provider` 或设为 `provider = "default"` 时，Kyoso 会有意阻止这两种来源；非空的显式 `agents.codex.env.OPENROUTER_API_KEY` 还会产生说明其未被 forward 的 sanitized warning。由于只有被选中的 Codex OpenRouter child 能接收 key，另一个 child configuration（例如 `agents.claude.env`）中的非空 key 也会产生相同 warning。省略 `provider` 会保留现有 Codex login、`OPENAI_API_KEY`、`CODEX_API_KEY` 和 `CODEX_CONFIG` 行为；删除该行即可回到这些行为。
 
-GUI client 可能不会继承 shell export。使用 `kyoso setup <client> --write --with-openrouter` 创建新的 manual MCP registration，重启 client 后再运行 `kyoso doctor` 检查 Kyoso process 能否检测到 key。`kyoso setup` 会保留已有 MCP entry 而不会重写，因此已有 registration 需要根据[示例](examples/codex-config.toml)手动更新 opt-in allowlist。
+Marketplace Plugin 会向其 MCP process 暴露 `OPENROUTER_API_KEY` 变量名，但不保存 credential 值。GUI client 可能不会继承 shell export。使用 `kyoso setup <client> --write --with-openrouter` 创建新的 manual MCP registration，重启 client 后再运行 `kyoso doctor` 检查 Kyoso process 能否检测到 key。`kyoso setup` 会保留已有 MCP entry 而不会重写，因此已有 registration 需要根据[示例](examples/codex-config.toml)手动更新 opt-in allowlist。
 
-新的 manual MCP registration 默认不包含 `OPENROUTER_API_KEY`。仅在有意选择 provider 后使用 `--with-openrouter` 添加它；已有 registration 永不重写。Claude Code registration 中的 `${OPENROUTER_API_KEY}` 必须由 client 展开；Kyoso 只会忽略完全由 `${NAME}`、`$NAME` 或 `%NAME%`（允许前后空白）构成的未展开 credential placeholder，并且只输出含变量名的 sanitized warning。含有其他文字的值会被保留。对于以 `_KEY`、`_TOKEN`、`_SECRET` 或 `_PASSWORD` 结尾的 custom credential-like name，也适用同一规则；非 credential template 会被保留。
+新的 manual MCP registration 默认不包含 `OPENROUTER_API_KEY`。仅在有意选择 provider 后使用 `--with-openrouter` 添加它；已有 registration 永不重写。`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例仍是用户管理的客户端注册模板。Claude Code registration 中的 `${OPENROUTER_API_KEY}` 必须由 client 展开；Kyoso 只会忽略完全由 `${NAME}`、`$NAME` 或 `%NAME%`（允许前后空白）构成的未展开 credential placeholder，并且只输出含变量名的 sanitized warning。含有其他文字的值会被保留。对于以 `_KEY`、`_TOKEN`、`_SECRET` 或 `_PASSWORD` 结尾的 custom credential-like name，也适用同一规则；非 credential template 会被保留。
 
 推荐使用这种经过 user authorization 的 project-scoped opt-in。global `provider = "openrouter"` 会被 project 继承，直到 project 设置 `provider = "default"`；仅省略 `provider` 不会将其 unset。固定的 OpenRouter Responses API preset 为 beta；不开放 custom endpoint、provider routing、fallback 或 judge integration。为将 key 绑定到该 preset，OpenRouter mode 会拒绝含 top-level `profile` 或 `profiles` 的 `CODEX_CONFIG`，并会在启动 child 前拒绝非 object 的 `model_providers` value。对于 object，它会将 `model_providers` 替换为仅含固定 `kyoso-openrouter` entry 的对象，并发出只包含已丢弃 entry 数量的 sanitized warning；不会显示 provider ID 或 config value。除这些被拒绝的 field 外，它会保留 `model`、`model_provider` 和 `model_providers` 之外无关的 `CODEX_CONFIG` field，因此 foreign provider configuration 无法选择使用该 key 的 endpoint。Claude 仍使用已配置的 provider，judge 不会使用 `OPENROUTER_API_KEY`。
 
@@ -382,26 +413,46 @@ Team admins 还应检查 organization Usage credits。如果启用了 credits，
 
 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。
+在 single-agent mode 中，剩余 backend 会以 `combined_reviewer` 运行一次，同时覆盖 implementation 和 architecture/security 两个 perspectives。JSON output 包含 `reviewMode: "single_agent"`、`agentsUsed` 和 `coverage.independentReview: false`；Markdown output 会说明未执行 cross-model verification。设置 user-global `reviewPolicy.multiAgentRequired = true` 后，这种 degraded coverage 会变为 incomplete 并 block。
 
 该 mode 不提供独立的 cross-model validation，仍可能有 self-review bias。它仍保留独立只读 review process、temporary snapshots、adversarial review prompts、secret scanning 和 deterministic gates。
 
 ### Execution budget and review stopping
 
-每次 review 都有 user-global hard ceiling，用于限制 model call 数、总 wall time、streaming agent text（message 和 thought chunk）以及每个 agent 的 finding 数量。
+每次 review 都有 user-global hard ceiling，用于限制 model call 数、总 wall time和streaming agent text（message 和 thought chunk）。streaming text还设有更低的soft warning threshold，而每个agent的finding数是soft target。
 
 ```toml
 [reviewBudget]
 maxModelCalls = 4
-maxTotalWallTimeMs = 480000
-maxAgentOutputBytes = 65536
+maxTotalWallTimeMs = 660000
+warnAgentOutputBytes = 524288
+maxAgentOutputBytes = 1048576
 maxFindingsPerAgent = 10
-skipOptionalPhasesWhenTokenUsageUnknown = true
+skipOptionalPhasesWhenTokenUsageUnknown = false
 ```
 
-`reviewBudget` 只能在 user-global 配置中设置；project `kyoso.toml` 和 `--set` 都不能修改它。MCP / library request 只能通过 `options.reviewBudget` 降低 ceiling，不能提高。Kyoso 会先同时预留两个 primary reviewer，再将剩余 call 用于 verification，并把 LLM Judge 作为 advisory。默认 Judge mode 是 `deterministic_only`。
+`reviewBudget` 只能在 user-global 配置中设置；project `kyoso.toml` 和 `--set` 都不能修改它。MCP / library request 只能通过 `options.reviewBudget` 降低 ceiling，不能提高。512 KiB warning不会block，1 MiB limit会cancel call，超过10条finding target的material finding也不会被丢弃。token usage未知时默认warning并继续；只有user-global显式设为`true`时才保持严格的optional-phase skip。Kyoso 会先同时预留两个 primary reviewer，再将剩余 call 用于 verification，并把 LLM Judge 作为 advisory。默认 Judge mode 是 `deterministic_only`。
 
-结果包含 `completion`、`executionBudget` 和 `requestFingerprint`。Markdown 与 Audit 会显示 call 数、wall time、output bytes，以及 reported 或 unknown token usage。若 `completion.status` 为 `incomplete`，Kyoso 返回普通的 `block` 结果且 `retryable: false`：该 block 表示 review coverage 未完成，而不是已经确认 code defect。不要自动重试相同 fingerprint。对于一个 review checkpoint，bundled Skill 只允许首次评审与 material fix 后的确认评审各1次；第三次需要用户明确批准。
+结果包含 `completion`、`executionBudget` 和 `requestFingerprint`。Markdown 与 Audit 会显示 call 数、wall time、message / thought / total output bytes，以及reported / partial / unknown token usage。已完成的model call还可显示`executionIdentity`，将Kyoso route和requested model与provider-reported identity分开；requested-only value绝不会显示为provider报告值。若 `completion.status` 为 `incomplete`，Kyoso 返回普通的 `block` 结果且 `retryable: false`：该 block 表示 review coverage 未完成，而不是已经确认 code defect。不要自动重试相同 fingerprint。对于一个 review checkpoint，bundled Skill 只允许首次评审与 material fix 后的确认评审各1次；第三次需要用户明确批准。
+
+### Timeouts
+
+Codex 和 Claude 的default agent timeout均为600秒；verification round 默认90秒。review-wide deadline 默认660秒(`reviewBudget.maxTotalWallTimeMs`)，在default并行primary phase后保留标准的60秒finalization余量。各 phase 使用剩余 deadline 而不会延长它。`kyoso doctor` 会显示已配置的顺序phase时间，以及加入10%或60秒（取较大值）余量后的review-wide建议值。只有当judge mode允许且direct provider credential可用时，才会计入LLM judge timeout。
+
+本repository的primary 15分钟＋verification 15分钟dogfooding preset使用以下user-global override：
+
+```toml
+[reviewBudget]
+maxTotalWallTimeMs = 2100000
+```
+
+Codex Plugin和新生成的manual Codex registration使用`tool_timeout_sec = 2160`，比Kyoso的35分钟deadline多保留60秒。`kyoso setup`会保留已有manual registration，因此需要手动更新。Claude Code Plugin manifest不设置client tool timeout；请用等效的毫秒值启动Claude Code，然后重启client：
+
+```bash
+MCP_TOOL_TIMEOUT=2160000 claude
+```
+
+延长client timeout不会延长Kyoso内部的review-wide deadline。对于其他preset，请确保client timeout大于`reviewBudget.maxTotalWallTimeMs`。
 
 ### Verification
 
@@ -416,7 +467,7 @@ timeoutMs = 90000
 allowDemotion = false
 ```
 
-启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。Phase 1 是 annotate-only：verification 可以更新 finding confidence 和 notes，但不会改变 severity。若 verification 被 skip、失败、预算耗尽或 overflow，finding 会保留为 `not_verified`，并返回 incomplete coverage。`allowDemotion` 为未来的 opt-in phase 保留，目前是 no-op。
+启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。verification 是 annotate-only：可以更新 confidence 和 notes，但永远不会改变 severity。被反驳或仍未解决的 material finding 会成为 `disputed`；若 verification 被 skip、失败、预算耗尽或 overflow，finding 会保留为 `not_verified`，并返回 incomplete coverage。这样可防止第二个 model 静默降低原始 risk signal。`allowDemotion` 为 compatibility 保留并被接受，但任一值都没有 demotion effect。
 
 ### Judge
 
@@ -428,10 +479,6 @@ Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs 是 optional，默认
 
 Judge defaults 有意使用 lightweight models。若需要更强的 judge，请将 `KYOSO_ANTHROPIC_JUDGE_MODEL` 设置为 Sonnet-class model，例如 `claude-sonnet-5`。
 
-### Timeouts
-
-Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round 默认 90 秒。review-wide deadline 默认480秒，各 phase 使用剩余 deadline 而不会延长它。MCP clients 应允许 tool calls 至少运行480秒。
-
 ### Audit
 
 在受支持的 POSIX runtime 上，Audit traces 会写入 user state base（absolute `$XDG_STATE_HOME`，否则 `$HOME/.local/state`）下：
@@ -442,7 +489,21 @@ Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round
 
 `audit.directory`是 logical relative directory（默认：`.kyoso/traces`），不是 workspace 内的 directory。现有 workspace `.kyoso/traces`不会被自动迁移或删除。
 
-Raw agent output 和 raw file contents 默认禁用。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning（参见 [Safety Model](#safety-model)）。
+通过installed package显式指定absolute trusted trace directory，生成read-only budget report：
+
+```bash
+kyoso-budget-report --trace-dir /absolute/path/to/traces --json
+```
+
+在source checkout中使用package script：
+
+```bash
+bun run audit:budget-report -- --trace-dir /absolute/path/to/traces --json
+```
+
+report仅递归读取regular `.jsonl`文件，skip symlink，且不会推测trace path。它按agent、kind、provider route、requested model以及requested / reported identity status统计call，分别显示all-call与normal-path的nearest-rank p50 / p95 / p99 / max byte分布、token usage reporting率、output warning / limit率和completion / skip原因。只有明确具有`resultStatus = "completed"`且没有`errorCode`的event才属于normal-path；有歧义的historical event仅保留在all-call统计中。top-level byte分布和output warning / hard limit的call率仅统计primary与verifier；judge call仍保留在all-call总数及execution分组中，但不会稀释重新校准指标。warning call率只包含与相同trace / kind / agent的completed call相关联的warning event；重复或孤立的warning event会单独显示。JSON通过`inputLimits`公开固定输入上限；当file、byte、line、event、call、review、warning、group、reason或directory超限时，命令会中止而不是截断。遍历在专用worker中执行，其经过验证的current directory绑定到指定root的device / inode；recursive descent也会重新验证每个directory identity，因此替换并恢复lexical root不会改变读取目标。file使用不跟随symlink的non-blocking open，并且读取量不会超过discovery时的size；如果platform无法提供这些open capability，report会中止。metadata sanitize属于defense in depth，因此只能指定operator信任的trace directory。report不会把bytes换算为估算token或cost。重新校准时，将soft warning保持在正常路径p99的至少2倍，将hard breaker放在warning之上足够远的位置，使正常触发率接近0，并在调整policy前按provider / model检查token usage unknown率。
+
+Raw agent output 默认禁用。`audit.includeFileContents` 是 reserved value，固定为 `false`；不会通过该设置保存 file contents。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning（参见 [Safety Model](#safety-model)）。
 
 ## Safety Model
 
@@ -462,6 +523,12 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 
 ## 迁移
 
+### 升级注意事项
+
+- 将 project `kyoso.toml` 中的 `tools.*` 移到 user-global config。project-owned tool availability 现在会被拒绝，避免 repository content 禁用 review。
+
+### 切换集成模式
+
 - 从手动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`。
@@ -469,7 +536,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 
 ## Troubleshooting
 
-- MCP timeout: 将 client tool timeouts 设置为至少 360 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 请参阅 [Timeouts](#timeouts)。
+- MCP timeout: client timeout应长于review-wide deadline。35分钟preset在Codex中使用2160秒，在Claude Code中使用`MCP_TOOL_TIMEOUT=2160000`。请参阅[Timeouts](#timeouts)。
 - Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
 - Deprecated TypeScript config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip；新配置请使用 `kyoso.toml`。
 - OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。Marketplace Plugin `0.4.0` 及更高版本会将此变量名 forward 给 Kyoso process，旧版本不会。setup 也不会重写已有 MCP registration。

package/dist/acp/ndJsonLineLimit.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_ACP_NDJSON_LINE_BYTES: number;
+export declare class AcpNdJsonLineLimitError extends Error {
+    readonly maxLineBytes: number;
+    constructor(maxLineBytes: number);
+}
+export declare function limitAcpNdJsonLineBytes(input: ReadableStream<Uint8Array>, maxLineBytes?: number): ReadableStream<Uint8Array>;

package/dist/acp/normalize.d.ts

@@ -1,3 +1,4 @@
 import type { AgentName, AgentRole, NormalizedAgentOpinion } from "../core/types.js";
 export declare function normalizeAgentOutput(agent: AgentName, role: AgentRole, rawText: string): NormalizedAgentOpinion;
+export declare function parseAgentOutputStrict(agent: AgentName, role: AgentRole, rawText: string): NormalizedAgentOpinion | undefined;
 export declare function extractFirstJsonObject(text: string): string | undefined;

package/dist/acp/prompts.d.ts

@@ -1,3 +1,9 @@
-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;
+import type { AgentName, AgentRole, KyosoFinding, KyosoReviewRequest, ReviewLens, ReviewTool } from "../core/types.js";
+export declare function buildAgentPrompt(tool: ReviewTool, request: KyosoReviewRequest, agent: AgentName, role: AgentRole, policy?: {
+    requiredLenses?: ReviewLens[];
+    cisaEnabled?: boolean;
+    maxFindingsTarget?: number;
+}): string;
+export declare function buildFindingVerifierPrompt(tool: ReviewTool, request: KyosoReviewRequest, verifier: AgentName, findings: KyosoFinding[], policy?: {
+    requiredLenses?: ReviewLens[];
+}): string;

package/dist/aggregate/aggregateFindings.d.ts

@@ -3,6 +3,7 @@ export type AggregatedReview = {
     findings: KyosoFinding[];
     testsToAdd: string[];
     residualRisks: string[];
+    openQuestions: string[];
     disagreements: Array<{
         topic: string;
         positions: Array<{