odai-dsh-agent 0.1.1 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 orziz
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 orziz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,132 +1,134 @@
-# odai dsh agent
-
-`odai-dsh-agent` installs a selectable, session-scoped Odai Agent preset for DeepSeek Harness (`dsh`). It is independent from the profile-wide `odai-dsh-plugin`: installing this package does not edit any DSH profile or activate a global bundle.
-
-The installed preset is self-contained:
-
-```text
-$DSH_HOME/.agent-presets/odai/
-  agent.cordis.yml
-  preset.yml
-  runtime/*.mjs
-  skills/odai/**
-  .odai-agent.json
-```
-
-The composition preserves every capability row and setting from the `standard` agent surface in `@deepseek-ai/dsh@0.1.0-rc.6`, then adds the scoped Odai runtime in default `auto` mode. Release verification compares the complete derived composition against that exact DSH Standard source; a missing, added, reordered, or changed Standard row fails the probe. Host-owned persistence, sandbox, approval, registries, and base controller selection remain in the selected DSH profile. Ordinary requests stay on that controller. A complete contextual or explicit planning gap upgrades the same turn only when a planner mapping exists; the controller's durable `request/header` proves the actual route. Reviewer starts a verified child only from a complete hash-addressed evidence packet; without one it can run only as a read-only same-turn check and cannot claim independent acceptance. `execute` remains an explicit comparison mode: planner gaps delegate, while reviewer gaps delegate only from a complete hash-addressed evidence packet; an incomplete reviewer packet starts no child. `observe` changes no model and starts no child; it injects a local evidence-and-decision protocol and makes an unresolved high-impact turn read-only. For DSH compaction, an explicit user-selected summary reasoning effort overrides only that auxiliary call. When omitted, same-provider/model compaction inherits the session's current reasoning effort for cache compatibility; a cross-model target removes an effort matching that durable route, while a distinct preselected effort is preserved because the request envelope exposes no stronger provenance.
-
-The preset includes the same local long-term semantic memory runtime as the Plugin. Default `auto` mode performs no hidden model call: it automatically captures only high-confidence durable statements from the direct-human message authenticated by the latest open-turn session event, keeps ambiguous or conflicting candidates inert, and recalls only bounded active global/project records as untrusted historical context. The controller-only `odai_memory` tool provides inspection, search, confirmation, correction, physical forgetting, exact-phrase clearing, and `auto`/`off` mode changes. Recognized secrets, contact identifiers, sensitive personal categories, temporary instructions, hypotheses, quotes, and code are rejected; the current user and project authority always override memory. State lives at `$DSH_HOME/odai/memory/store.json`, outside `.agent-presets`, so install, update, and uninstall preserve it. An invalid or symlinked store fails closed. The matcher is not a replacement for protecting the underlying DSH session history from sensitive input.
-
-## Install
-
-With DSH already installed, run the single Agent package command below. The package already contains the canonical skill and shared runtime; it does not require the Plugin or a separate skill installation:
-
-```sh
-npx odai-dsh-agent install
-```
-
-The installer checks `dsh -V` and currently requires exactly `0.1.0-rc.6`; a preset built from one developer-preview composition is not silently installed into another version.
-
-`DSH_HOME` is honored. An explicit location can be supplied without changing the environment:
-
-```sh
-npx odai-dsh-agent install --dsh-home /path/to/dsh-home
-```
-
-Open a new DSH session and select `Odai` from the Agent preset picker. Existing sessions retain the preset they were composed with.
-
-In `dsh@0.1.0-rc.6`, the one-shot `--profile headless` driver creates a global agent directly and neither mounts nor accepts a session Agent preset. Automated Agent runs must create a Web session with `agentPreset: odai`; use the profile-wide Plugin for one-shot headless tasks.
-
-The installer copies through a mode-tightened staging directory and atomically publishes the preset. Updates verify every previously managed file first, refuse to overwrite local edits, and always change the composition generation key so new sessions in a running DSH process do not reuse stale runtime code. If install or update finds recognized historical Odai audit records, it refuses to change the preset until every DSH process is stopped and the command is rerun with `--yes`. The confirmed migration adds DSH's official `ignorable: true` envelope marker, covers both plaintext and concatenated-frame Zstandard session artifacts, verifies each replacement, and retains a content-addressed backup without deleting messages or evidence. Confirmation alone is insufficient: migration also refuses when local process inspection fails or finds any active DSH process. Keep DSH stopped until the installer exits because historical runtimes do not participate in a migration lock. An unknown unmarked `odai/*` type blocks the operation instead of being assumed safe to ignore.
-
-DSH classifies this as a `trust: user` preset. User presets have the same privileges as shell access, so install only reviewed package versions; the installer repeats this trust notice in both plain and JSON output.
-
-## Responsibility models
-
-The Agent ships no researcher, planner, executor, reviewer, or frontend model mapping. It stays quiet when an unconfigured responsibility is not needed. If a real task gap needs one, Odai says which responsibility is missing, confirms that no route ran, and asks for the provider, model, and optional reasoning effort in natural language. For example:
-
-```text
-证据调查用 provider-r/model-research，推理档 high。
-规划用 provider-x/model-plan，推理档 high。
-执行模型设为 provider-x/model-y。
-验收改用 provider-z/model-review，推理档 max。
-前端制作用 provider-f/model-frontend，输出上限 4096。
-```
-
-The controller calls `odai_routing_config` to persist that explicit choice. Researcher activation is task-gated but not price-aware: its mapping enables the narrow trigger and does not guarantee lower cost. The tool repeats that warning whenever a researcher mapping is shown; Odai must use authoritative provider prices and measured usage instead of inventing either. The user does not edit Agent files, YAML, or JSON and does not add trigger terms to later tasks. Mappings live in `$DSH_HOME/odai/routing.json`, outside the managed preset, so installer updates do not report them as drift. Audit evidence likewise lives under `$DSH_HOME/odai/session-evidence/` instead of using private DSH session-event types, so changing or removing the preset cannot make a session unreadable. Changes apply from the next user turn. Each controller turn receives a fresh merged effective-mapping snapshot, with persisted mappings preferred over deployment mappings and provenance shown even after compaction. The tool also exposes the latest current-session actual route receipt; configured targets alone never prove that a responsibility ran. If reasoning effort is omitted, the target provider/model uses its own default rather than inheriting the source controller's setting. Plugin and Agent read the same stores when both are deliberately present.
-
-Researcher and frontend are optional prefetch/production upgrades whose missing mappings keep the original route without claiming success. Planner, executor, and reviewer are independent optional responsibilities; if a needed one has no mapping, high-impact work fails closed and remains read-only, while lower-impact work continues only where it does not depend on the missing independent responsibility. Same-turn responsibility upgrades are verified against DSH's effective request header; mismatch or missing evidence is recorded and cannot silently authorize writes. A generic subagent is not a responsibility route. A manual responsibility child must use an `odai-<responsibility>` label and cannot finish successfully without a matching actual-route receipt. Odai never chooses a model or price on the user's behalf.
-
-## Controller output policy
-
-The Agent defaults to **soft concise** output and shares three controller output modes with the Plugin. A user can naturally ask to inspect or change the mode; `odai_output_config` persists an explicit override in `$DSH_HOME/odai/output.json`:
-
-| Mode | Policy | Behavior |
-|---|---|---|
-| normal | `concise: false`, no `maxTokens` | use the host's normal presentation and controller budget |
-| soft concise (default) | `concise: true`, no `maxTokens` | shorten only the final user-facing presentation without relaxing required results, evidence, risks, blockers, or verification |
-| economy (optional) | `concise: true`, positive `maxTokens` | add a provider output-ceiling request; default to `500` when the user names economy without another value, or use the user's supplied positive value |
-
-Natural requests include `use normal output`, `use soft concise output`, `enable economy mode`, and `set economy mode to 1200 tokens`. Removing the persisted override restores soft concise. Existing pre-mode stores that combined `concise: false` with a ceiling remain readable for compatibility, but new named-mode changes cannot create that legacy combination. The selected mode is stable within one turn and changes from the next user turn.
-
-An economy ceiling only tightens an existing lower host request value and is not a locally enforceable hard billing boundary. A provider may count hidden reasoning inside it, exceed or ignore it, or end before useful final text, especially at a high reasoning effort; strict compliance must be checked from per-request usage. Odai enables economy only when requested and never invents a non-default custom value. The mode does not alter child-agent role budgets, compaction, checkpoints, or other internal context; an incomplete token-capped compaction fails closed instead of replacing history.
-
-A same-provider/model compaction inherits controller reasoning while keeping its independent summary budget. Odai leaves prompt-cache retention unset by default; `ODAI_COMPACTION_CACHE_RETENTION` can explicitly select `short`, `long`, or `none`. `provider-default` means Odai adds no retention, while any explicit incoming retention remains authoritative; configured retention still applies when host routing has already supplied reasoning. Custom preset compositions can set the same value through runtime `compaction.cacheRetention`. The first controller request after a landed summary still rebuilds the changed summary prefix.
-
-## Compaction model
-
-The default compaction-summary model is `inherit`, which preserves the conversation's current provider/model behavior. A user can explicitly set a separate target and optional reasoning effort in natural language, such as `压缩模型用 provider-x/model-summary，推理档 high`; `odai_compaction_config` persists those explicit values in `$DSH_HOME/odai/compaction.json`. Removing the target restores inheritance. Agent and Plugin share the store when both are deliberately present.
-
-The target applies only to future `compaction` summary requests. It does not change the controller, researcher, planner, executor, reviewer, frontend, ordinary conversation, summary output budget, or cache-retention policy. An explicitly configured `reasoningEffort` overrides reasoning only for those summaries. When omitted, existing behavior remains: same-route summaries can inherit controller reasoning, while a cross-model target removes only reasoning proven by equality with the durable controller route and preserves a distinct preselected effort. Each configured target receives one provider-neutral integrity suffix that keeps current facts above superseded/rejected history, preserves continuation-critical opaque values exactly, and self-checks contradictions; duplicate Agent/Plugin runtime instances add it only once. Odai never chooses the provider, model, or reasoning effort on the user's behalf. An invalid store is reported by the tool while runtime requests inherit safely until `set` or `remove` repairs it. An unavailable route, provider error, or incomplete summary fails closed: DSH retains the original history rather than replacing it with a partial checkpoint.
-
-## Skill sources
-
-The Agent keeps the managed preset's complete skill copy as its `bundled` default, so existing installations do not change behavior. When the user explicitly asks to show, set, or reset the Odai skill source, the controller uses `odai_skill_source_config` and stores the choice in `$DSH_HOME/odai/source.json`, outside the managed preset:
-
-- `bundled`: use the skill shipped with this Agent release.
-- `auto`: allow a compatible current-project `.dsh/skills/odai` or `.agents/skills/odai` bundle, then DSH custom roots and newer user installs under `$DSH_HOME/skills/odai` or `$DSH_AGENTS_HOME/skills/odai` (default `~/.agents/skills/odai`), with bundled fallback.
-- `user`: ignore project roots and require a compatible custom or user-level bundle. An unusable source produces an explicit bundled fallback diagnostic so it can be repaired through the same tool.
-
-An independent install must be a complete directory bundle containing `SKILL.md`, `manifest.json`, and every manifest-declared file. The runtime checks SemVer 2.0.0 `skillVersion`, an exact supported `runtimeContract`, complete-file SHA-256 integrity, and same-version content conflicts. Prompt governance and routing role contracts are selected atomically for one agent turn; project sources are scoped by that session's cwd, and changes are reconsidered on the next user turn. Explicit deployment `skillPath` or `ODAI_SKILL_PATH` remains highest priority and requires a DSH restart.
-
-## Controlled skill evolution
-
-Explicit user governance refinements live in `$DSH_HOME/odai/skill-evolution`, outside `.agent-presets/odai`. Agent install, update, repair, and uninstall therefore leave them intact; the Plugin reads the same default store when both surfaces are deliberately installed. This overlay is independent of the selected `bundled`/`auto`/`user` source. A custom `governance.evolutionRoot` is a deployment override and must match across Agent and Plugin to remain shared.
-
-`odai_skill_evolution` can propose exact replacements only in existing governance Markdown: `SKILL.md`, `assets/task-state.md`, `assets/routing-roles/*.md`, and `references/*.md`. Manifest changes, executable/runtime files, undeclared paths, symlinks, stale hashes, and untracked edits are rejected. Candidates store immutable base/result snapshots and content-addressed provenance. The first `propose` call writes nothing and returns `PROPOSE ODAI EVOLUTION <proposal-digest>`, bound to the complete proposed input. Retrying that exact proposal writes a candidate only when the current open turn's latest direct-human message contains exactly one text block equal to the phrase, byte for byte.
-
-`propose` and `rebase` never activate. Validation returns a phrase bound to the exact generation. Any `SKILL.md` or `references/dao.md` change, including additive preamble or core-section text, is `breaking`; so is any replacement that does not preserve its old text. These require `ACTIVATE BREAKING ODAI EVOLUTION <generation-id>` instead of the standard activation phrase. Model text and arguments, synthetic messages, multi-block or whitespace-altered text, stale confirmations, and other action or generation phrases cannot authorize writes. Audit evidence is derived from the authenticated session event, not supplied by the model. The tool stays discoverable without an unconditional evolution system-prompt section.
-
-An active generation survives package updates. When its base differs from the newly bundled upstream, Odai keeps the active result visible with `rebaseRequired`; clean rebases produce another inactive candidate, while conflicts preserve base/ours/theirs evidence and do not change the pointer. Rebase is generation-bound. Rollback and deactivation phrases also bind the current active generation, preventing stale pointer authorization. `rollback` is limited to a previously active validated generation. Child agents cannot use this tool. Stop DSH before updating the Agent and restart it so the process loads the new bundled bytes. Explicit `skillPath`/`ODAI_SKILL_PATH` bypasses evolution, and `ODAI_DISABLE_EVOLUTION=1` provides an emergency startup bypass without deleting state.
-
-## Status and uninstall
-
-```sh
-npx odai-dsh-agent status
-npx odai-dsh-agent status --json
-npx odai-dsh-agent uninstall
-```
-
-`status` reports `absent`, `installed`, or `drifted`. Update and uninstall fail closed when managed files were changed or unmanaged files were added. Uninstall first checks for legacy Odai session events and, when any exist, requires the same stopped-DSH `--yes` confirmation before making them ignorable; a failed inspection or migration refuses removal. It also refuses while `agent-presets.default` still names `odai`; select another default first so the next session cannot fail on a missing preset. Stop DSH before install, update, or uninstall so session artifacts are not being written concurrently.
-
-## Plugin versus Agent
-
-Use only the surface that matches the desired scope:
-
-- `odai-dsh-plugin`: profile-wide governance for every preset in that profile.
-- `odai-dsh-agent`: selectable Odai governance for only sessions using this preset.
-- both: supported only for a deliberate combination of profile-wide and Agent-scoped behavior; normally redundant, so it is not the default recommendation.
-
-When both are deliberate, a process-shared per-agent/per-turn skill snapshot keeps prompt governance and role contracts identical, the compatibility-safe evidence store deduplicates tool and route records, and denials remain monotonic. Neither package installs or changes the provider-neutral `odai-cli`.
-
-## Development
-
-`dsh/runtime/` and `skills/odai/` remain the only editable sources. `npm pack` generates the preset's `runtime/` and `skills/` directories and removes them immediately afterward:
-
-```sh
-npm --prefix dsh/agent test
-npm --prefix dsh/agent run verify:dsh
-npm --prefix dsh/agent run pack:dry-run
-```
-
-The DSH verification uses a temporary home and one isolated Web process. It creates standard and Odai sessions, proves the canonical prompt appears only for Odai, dispatches `odai_routing_config` through the live Odai session and checks its persisted mapping, and proves the child write guard does not leak into the standard preset.
+# odai dsh agent
+
+`odai-dsh-agent` installs a selectable, session-scoped Odai Agent preset for DeepSeek Harness (`dsh`). It is independent from the profile-wide `odai-dsh-plugin`: installing this package does not edit any DSH profile or activate a global bundle.
+
+The installed preset is self-contained:
+
+```text
+$DSH_HOME/.agent-presets/odai/
+  agent.cordis.yml
+  preset.yml
+  runtime/*.mjs
+  skills/odai/**
+  .odai-agent.json
+```
+
+The source composition preserves every capability row and setting from the `standard` agent surface in `@deepseek-ai/dsh@0.1.0-rc.7`, then adds the scoped Odai runtime in default `auto` mode. For rc.6, the installer deterministically restores that release's two disabled optional-provider fields before hashing and publishing the managed preset. Release verification compares each rendered composition against its exact DSH Standard source; a missing, added, reordered, or changed Standard row fails the probe. Host-owned persistence, sandbox, approval, registries, and base controller selection remain in the selected DSH profile. Ordinary requests stay on that controller. Responsibility words are optional signals rather than commands: evidence-grounded task-state gaps route at any step, identical gaps are consumed once, and an identical planner/controller model remains inline without another model call. An original request that already authorizes implementation automatically continues from a frozen planner card to executor; plan-only, new-task, expanded-scope, and unknown authorization cannot do so. Reviewer children require a current hash-addressed evidence packet whose diff and latest successful test are newer than the last write. Every route is resolved before provider I/O; deterministic invalid persisted mappings are backed up and exact-match removed, while recoverable provider failures preserve them. Frontend route failure becomes an explicit local controller fallback without a routed receipt. `execute` remains an explicit comparison mode and `observe` changes no model or child while retaining fail-closed high-impact protection. Configured compaction streams are buffered so partial failed output cannot contaminate the inherited-route retry or replace original history.
+
+The preset includes the same local long-term semantic memory runtime as the Plugin. Default `auto` mode performs no hidden model call: it automatically captures only high-confidence durable statements from the direct-human message authenticated by the latest open-turn session event, keeps ambiguous or conflicting candidates inert, and recalls only bounded active global/project records as untrusted historical context. The controller-only `odai_memory` tool provides inspection, search, confirmation, correction, physical forgetting, exact-phrase clearing, and `auto`/`off` mode changes. Recognized secrets, contact identifiers, health/crisis content, temporary instructions, hypotheses, quotes, and code are rejected; the current user and project authority always override memory. State lives at `$DSH_HOME/odai/memory/store.json`, outside `.agent-presets`, so install, update, and uninstall preserve it. An invalid or symlinked store fails closed. The matcher is not a replacement for protecting the underlying DSH session history from sensitive input.
+
+Human-safety continuity is an independent explicit-consent store at `$DSH_HOME/odai/human-safety-continuity.json`, not a hidden health profile and not semantic memory. `odai_human_safety_continuity` accepts only the authenticated current direct user's request to save, inspect, export, correct, remove, or physically clear user-authored care preferences, signals they want noticed, support they say helps, and safety-plan steps. Added/replacement text must occur exactly in that message; credentials and contact details are rejected, and entries persist until the user removes or physically clears them. New controller sessions may use it as historical care preference, never as proof of current risk, diagnosis, or a score; children cannot inspect it or receive its prompt data. Any credible current self-harm or suicide inclination triggers timely care and a direct safety check even without a plan, while plan, means, and action determine emergency urgency rather than whether to intervene.
+
+## Install
+
+With DSH already installed, run the single Agent package command below. The package already contains the canonical skill and shared runtime; it does not require the Plugin or a separate skill installation:
+
+```sh
+npx odai-dsh-agent install
+```
+
+The installer checks `dsh -V` and currently accepts exactly `0.1.0-rc.6` or `0.1.0-rc.7`. It records the detected version in the managed manifest and renders that release's exact Standard composition; any other developer-preview version fails closed.
+
+`DSH_HOME` is honored. An explicit location can be supplied without changing the environment:
+
+```sh
+npx odai-dsh-agent install --dsh-home /path/to/dsh-home
+```
+
+Open a new DSH session and select `Odai` from the Agent preset picker. Existing sessions retain the preset they were composed with.
+
+In supported DSH rc.6 and rc.7 releases, the one-shot `--profile headless` driver creates a global agent directly and neither mounts nor accepts a session Agent preset. Automated Agent runs must create a Web session with `agentPreset: odai`; use the profile-wide Plugin for one-shot headless tasks.
+
+The installer copies through a mode-tightened staging directory and atomically publishes the preset. Updates verify every previously managed file first, refuse to overwrite local edits, and always change the composition generation key so new sessions in a running DSH process do not reuse stale runtime code. If install or update finds recognized historical Odai audit records, it refuses to change the preset until every DSH process is stopped and the command is rerun with `--yes`. The confirmed migration adds DSH's official `ignorable: true` envelope marker, covers both plaintext and concatenated-frame Zstandard session artifacts, verifies each replacement, and retains a content-addressed backup without deleting messages or evidence. Confirmation alone is insufficient: migration also refuses when local process inspection fails or finds any active DSH process. Keep DSH stopped until the installer exits because historical runtimes do not participate in a migration lock. An unknown unmarked `odai/*` type blocks the operation instead of being assumed safe to ignore.
+
+DSH classifies this as a `trust: user` preset. User presets have the same privileges as shell access, so install only reviewed package versions; the installer repeats this trust notice in both plain and JSON output.
+
+## Responsibility models
+
+The Agent ships no researcher, planner, executor, reviewer, or frontend model mapping. It stays quiet when an unconfigured responsibility is not needed. If a real task gap needs one, Odai says which responsibility is missing, confirms that no route ran, and asks for the provider, model, and optional reasoning effort in natural language. For example:
+
+```text
+证据调查用 provider-r/model-research，推理档 high。
+规划用 provider-x/model-plan，推理档 high。
+执行模型设为 provider-x/model-y。
+验收改用 provider-z/model-review，推理档 max。
+前端制作用 provider-f/model-frontend，输出上限 4096。
+```
+
+The controller calls `odai_routing_config` to persist that explicit choice. Researcher activation is task-gated but not price-aware: its mapping enables the narrow trigger and does not guarantee lower cost. The tool repeats that warning whenever a researcher mapping is shown; Odai must use authoritative provider prices and measured usage instead of inventing either. The user does not edit Agent files, YAML, or JSON and does not add trigger terms to later tasks. Mappings live in `$DSH_HOME/odai/routing.json`, outside the managed preset, so installer updates do not report them as drift. Audit evidence likewise lives under `$DSH_HOME/odai/session-evidence/` instead of using private DSH session-event types, so changing or removing the preset cannot make a session unreadable. Changes apply from the next user turn. Each controller turn receives a fresh merged effective-mapping snapshot, with persisted mappings preferred over deployment mappings and provenance shown even after compaction. The tool also exposes the latest current-session actual route receipt; configured targets alone never prove that a responsibility ran. If reasoning effort is omitted, the target provider/model uses its own default rather than inheriting the source controller's setting. Plugin and Agent read the same stores when both are deliberately present.
+
+Researcher and frontend are optional evidence/production upgrades whose missing mappings keep the original route without claiming success. A researcher child is limited to a bounded multi-source repository question; technical facts available through controller tools are investigated directly instead of manufacturing a role call. Planner, executor, and reviewer are independent optional responsibilities; if a needed one has no mapping, high-impact work fails closed and remains read-only, while lower-impact work continues only where it does not depend on the missing responsibility. Same-turn routes and child outputs require actual request-header evidence. Deterministic invalid persisted mappings are backed up and exact-match removed; credentials, quota, rate-limit, server, timeout, and transport failures preserve configuration and fall back only for the current call. A generic subagent is not a responsibility route. A manual responsibility child must use an `odai-<responsibility>` label and cannot finish successfully without a matching actual-route receipt. Odai never chooses a model or price on the user's behalf.
+
+## Controller output policy
+
+The Agent defaults to **soft concise** output and shares three controller output modes with the Plugin. A user can naturally ask to inspect or change the mode; `odai_output_config` persists an explicit override in `$DSH_HOME/odai/output.json`:
+
+| Mode | Policy | Behavior |
+|---|---|---|
+| normal | `concise: false`, no `maxTokens` | use the host's normal presentation and controller budget |
+| soft concise (default) | `concise: true`, no `maxTokens` | shorten only the final user-facing presentation without relaxing required results, evidence, risks, blockers, or verification |
+| economy (optional) | `concise: true`, positive `maxTokens` | add a provider output-ceiling request; default to `500` when the user names economy without another value, or use the user's supplied positive value |
+
+Natural requests include `use normal output`, `use soft concise output`, `enable economy mode`, and `set economy mode to 1200 tokens`. Removing the persisted override restores soft concise. Existing pre-mode stores that combined `concise: false` with a ceiling remain readable for compatibility, but new named-mode changes cannot create that legacy combination. The selected mode is stable within one turn and changes from the next user turn.
+
+An economy ceiling only tightens an existing lower host request value and is not a locally enforceable hard billing boundary. A provider may count hidden reasoning inside it, exceed or ignore it, or end before useful final text, especially at a high reasoning effort; strict compliance must be checked from per-request usage. Odai enables economy only when requested and never invents a non-default custom value. The mode does not alter child-agent role budgets, compaction, checkpoints, or other internal context; an incomplete token-capped compaction fails closed instead of replacing history.
+
+A same-provider/model compaction inherits controller reasoning while keeping its independent summary budget. Odai leaves prompt-cache retention unset by default; `ODAI_COMPACTION_CACHE_RETENTION` can explicitly select `short`, `long`, or `none`. `provider-default` means Odai adds no retention, while any explicit incoming retention remains authoritative; configured retention still applies when host routing has already supplied reasoning. Custom preset compositions can set the same value through runtime `compaction.cacheRetention`. The first controller request after a landed summary still rebuilds the changed summary prefix.
+
+## Compaction model
+
+The default compaction-summary model is `inherit`, which preserves the conversation's current provider/model behavior. A user can explicitly set a separate target and optional reasoning effort in natural language, such as `压缩模型用 provider-x/model-summary，推理档 high`; `odai_compaction_config` persists those explicit values in `$DSH_HOME/odai/compaction.json`. Removing the target restores inheritance. Agent and Plugin share the store when both are deliberately present.
+
+The target applies only to future `compaction` summary requests. It does not change the controller, researcher, planner, executor, reviewer, frontend, ordinary conversation, summary output budget, or cache-retention policy. An explicitly configured `reasoningEffort` overrides reasoning only for those summaries. When omitted, existing behavior remains: same-route summaries can inherit controller reasoning, while a cross-model target removes only reasoning proven by equality with the durable controller route and preserves a distinct preselected effort. Each configured target receives one provider-neutral integrity suffix that keeps current facts above superseded/rejected history, preserves continuation-critical opaque values exactly, and self-checks contradictions; duplicate Agent/Plugin runtime instances add it only once. Odai never chooses the provider, model, or reasoning effort on the user's behalf. An invalid store is reported by the tool while runtime requests inherit safely until `set` or `remove` repairs it. The configured stream is buffered until a valid terminal result. Partial failed chunks are discarded before one retry with the untouched inherited request; deterministic invalid persisted targets are backed up and exact-match removed, transient failures preserve them, and DSH retains original history until a complete summary lands.
+
+## Skill sources
+
+The Agent keeps the managed preset's complete skill copy as its `bundled` default, so existing installations do not change behavior. When the user explicitly asks to show, set, or reset the Odai skill source, the controller uses `odai_skill_source_config` and stores the choice in `$DSH_HOME/odai/source.json`, outside the managed preset:
+
+- `bundled`: use the skill shipped with this Agent release.
+- `auto`: allow a compatible current-project `.dsh/skills/odai` or `.agents/skills/odai` bundle, then DSH custom roots and newer user installs under `$DSH_HOME/skills/odai` or `$DSH_AGENTS_HOME/skills/odai` (default `~/.agents/skills/odai`), with bundled fallback.
+- `user`: ignore project roots and require a compatible custom or user-level bundle. An unusable source produces an explicit bundled fallback diagnostic so it can be repaired through the same tool.
+
+An independent install must be a complete directory bundle containing `SKILL.md`, `manifest.json`, and every manifest-declared file. The runtime checks SemVer 2.0.0 `skillVersion`, an exact supported `runtimeContract`, complete-file SHA-256 integrity, and same-version content conflicts. Prompt governance and routing role contracts are selected atomically for one agent turn; project sources are scoped by that session's cwd, and changes are reconsidered on the next user turn. Explicit deployment `skillPath` or `ODAI_SKILL_PATH` remains highest priority and requires a DSH restart.
+
+## Controlled skill evolution
+
+Explicit user governance refinements live in `$DSH_HOME/odai/skill-evolution`, outside `.agent-presets/odai`. Agent install, update, repair, and uninstall therefore leave them intact; the Plugin reads the same default store when both surfaces are deliberately installed. This overlay is independent of the selected `bundled`/`auto`/`user` source. A custom `governance.evolutionRoot` is a deployment override and must match across Agent and Plugin to remain shared.
+
+`odai_skill_evolution` can propose exact replacements only in existing governance Markdown: `SKILL.md`, `assets/task-state.md`, `assets/routing-roles/*.md`, and `references/*.md`. Manifest changes, executable/runtime files, undeclared paths, symlinks, stale hashes, and untracked edits are rejected. Candidates store immutable base/result snapshots and content-addressed provenance. The first `propose` call writes nothing and returns `PROPOSE ODAI EVOLUTION <proposal-digest>`, bound to the complete proposed input. Retrying that exact proposal writes a candidate only when the current open turn's latest direct-human message contains exactly one text block equal to the phrase, byte for byte.
+
+`propose` and `rebase` never activate. Validation returns a phrase bound to the exact generation. Any `SKILL.md` or `references/dao.md` change, including additive preamble or core-section text, is `breaking`; so is any replacement that does not preserve its old text. These require `ACTIVATE BREAKING ODAI EVOLUTION <generation-id>` instead of the standard activation phrase. Model text and arguments, synthetic messages, multi-block or whitespace-altered text, stale confirmations, and other action or generation phrases cannot authorize writes. Audit evidence is derived from the authenticated session event, not supplied by the model. The tool stays discoverable without an unconditional evolution system-prompt section.
+
+An active generation survives package updates. When its base differs from the newly bundled upstream, Odai keeps the active result visible with `rebaseRequired`; clean rebases produce another inactive candidate, while conflicts preserve base/ours/theirs evidence and do not change the pointer. Rebase is generation-bound. Rollback and deactivation phrases also bind the current active generation, preventing stale pointer authorization. `rollback` is limited to a previously active validated generation. Child agents cannot use this tool. Stop DSH before updating the Agent and restart it so the process loads the new bundled bytes. Explicit `skillPath`/`ODAI_SKILL_PATH` bypasses evolution, and `ODAI_DISABLE_EVOLUTION=1` provides an emergency startup bypass without deleting state.
+
+## Status and uninstall
+
+```sh
+npx odai-dsh-agent status
+npx odai-dsh-agent status --json
+npx odai-dsh-agent uninstall
+```
+
+`status` reports `absent`, `installed`, or `drifted`. Update and uninstall fail closed when managed files were changed or unmanaged files were added. Uninstall first checks for legacy Odai session events and, when any exist, requires the same stopped-DSH `--yes` confirmation before making them ignorable; a failed inspection or migration refuses removal. It also refuses while `agent-presets.default` still names `odai`; select another default first so the next session cannot fail on a missing preset. Stop DSH before install, update, or uninstall so session artifacts are not being written concurrently.
+
+## Plugin versus Agent
+
+Use only the surface that matches the desired scope:
+
+- `odai-dsh-plugin`: profile-wide governance for every preset in that profile.
+- `odai-dsh-agent`: selectable Odai governance for only sessions using this preset.
+- both: supported only for a deliberate combination of profile-wide and Agent-scoped behavior; normally redundant, so it is not the default recommendation.
+
+When both are deliberate, a process-shared per-agent/per-turn skill snapshot keeps prompt governance and role contracts identical, the compatibility-safe evidence store deduplicates tool and route records, and denials remain monotonic. Neither package installs or changes the provider-neutral `odai-cli`.
+
+## Development
+
+`dsh/runtime/` and `skills/odai/` remain the only editable sources. `npm pack` generates the preset's `runtime/` and `skills/` directories and removes them immediately afterward:
+
+```sh
+npm --prefix dsh/agent test
+npm --prefix dsh/agent run verify:dsh
+npm --prefix dsh/agent run pack:dry-run
+```
+
+The DSH verification uses a temporary home and one isolated Web process. It creates standard and Odai sessions, proves the canonical prompt appears only for Odai, dispatches `odai_routing_config` through the live Odai session and checks its persisted mapping, and proves the child write guard does not leak into the standard preset.