@sakanano-moe/agenthelm 6.8.0 → 6.11.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakanano-moe/agenthelm",
-  "version": "6.8.0",
+  "version": "6.11.0-rc.1",
   "description": "agenthelm CLI: install, check and update the agenthelm plugins for Claude Code, Codex and Cursor; a user-level runtime; and a project menu that works without any AI agent.",
   "license": "MIT",
   "bin": {

package/runtime/index.json

@@ -4,14 +4,14 @@
     "name": "agenthelm",
     "description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
     "version": "0.7.0",
-    "updated_at": "2026-10-27",
+    "updated_at": "2026-10-29",
     "homepage": "./index.html",
     "domain": "agenthelm.sakanano.moe",
     "legacy_domain": "skill.sakanano.moe"
   },
   "plugin": {
     "manifest": "./plugins/agents-init/plugin.json",
-    "version": "6.8.0",
+    "version": "6.11.0",
     "install_unit": "marketplace",
     "bundled_plugins": [
       "./plugins/project-orchestrator/plugin.json",
@@ -30,7 +30,7 @@
       "id": "agents-init",
       "name": "agents-init v6 / Project Profile initialization and migration",
       "description": "Create or migrate the project skeleton and root launcher; checks that project-orchestrator, agent-pack and opinion-manager from the same release are present before writing.",
-      "version": "6.7.0",
+      "version": "6.8.0",
       "status": "stable",
       "entrypoints": {
         "browser": "./plugins/agents-init/skills/agents-init/index.html",
@@ -43,7 +43,7 @@
       "id": "project-orchestrator",
       "name": "project-orchestrator / project lifecycle orchestration",
       "description": "Organizes Case workspaces or keeps existing Task/Case layouts; search, lossless migration, verification, scoped Git delivery, and a project menu that works without any AI agent.",
-      "version": "1.9.0",
+      "version": "1.11.1",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
@@ -55,7 +55,7 @@
       "id": "agent-pack",
       "name": "agent-pack / Agent extension capability management",
       "description": "Inventory, verify, install, sync, migrate and reconcile Plugins, Skills and MCP between projects and Codex / Cursor / Claude; the agenthelm command line and user-level runtime.",
-      "version": "1.9.0",
+      "version": "1.11.0",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
@@ -68,7 +68,7 @@
       "id": "opinion-manager",
       "name": "opinion-manager / Agent behavior rule management",
       "description": "Three first-run entry points plus optional memory candidates; one content confirmation, then Profile, body and lock are saved separately, with exact versions and protection of personal edits.",
-      "version": "0.4.2",
+      "version": "0.5.0",
       "status": "experimental",
       "entrypoints": {
         "agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",

package/runtime/plugins/agent-pack/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-pack",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Deterministic Agent-extension capability management for configured workspaces.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agent-pack/hooks/hooks.json

@@ -10,6 +10,38 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/runtime/agenthelm.py\" nudge hook --event session-start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/runtime/agenthelm.py\" nudge hook --event prompt-submit",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/runtime/agenthelm.py\" nudge hook --event stop",
+            "timeout": 10
+          }
+        ]
       }
     ]
   }

package/runtime/plugins/agent-pack/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agent-pack",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Deterministic Agent-extension capability management: inventory, doctor, bootstrap, sync, transfer, and reconcile Agent Plugins / Skills / MCP servers across Codex, Cursor, Claude Code, and project sources. Ships a stdio MCP.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agent-pack/references/local-only.md

@@ -0,0 +1,126 @@
+# 本机专属目录（local-only）
+
+项目放在 iCloud Drive、Dropbox、OneDrive、Google Drive 等同步目录里、在多台设备上使用时，`.venv`、`node_modules`、工具缓存这类**可重建的大目录**不该进同步盘：同步慢、产生冲突副本，不同系统或架构的二进制还会互相覆盖。`agenthelm local-only` 把它们放到每台设备自己的 `~/.local/share/agenthelm/local-only/` 下，在项目里留一个软链接；并能检查出“设备 A 装好了、设备 B 还没装”这类差异。
+
+不在同步目录里的项目不受影响：没有同步服务、也没有 local-only 配置时，`check` 直接返回空结果，不扫描。
+
+## 三条硬约束
+
+1. **链接文本必须在所有设备上相同。** 软链接本身会随项目同步，所以目标路径只由三样东西拼成：项目里记录的 `home`、`project_id`、项目内相对路径——`<home>/.local/share/agenthelm/local-only/<project_id>/<相对路径>`。不读 `XDG_DATA_HOME`。
+2. **各设备的 HOME 绝对路径必须一致**（例如都是 `/home/<同一个用户名>`）。`home` 记在项目配置里；不一致时 `check` 报“HOME 与项目约定不一致”，`fix` 拒绝建立或修改任何链接。
+3. **工具只给方案和预览，改文件必须 `--apply`。** 移动失败整体撤销；旧配置先备份到 `~/.agent-pack/recovery/<时间>-agenthelm-local-only/`。
+
+## 怎么处理每一类
+
+| 类别 | 例子 | 处理 |
+| --- | --- | --- |
+| 依赖安装物（可外置） | 含 `pyvenv.cfg` 的目录（不管叫什么）、`node_modules`（yarn 经典版、bun、未知管理器） | `fix` 移到本机目录，原位置建软链接 |
+| 依赖安装物（只报告） | `node_modules`（npm、pnpm、yarn 2+）、`.tox`、`.nox`、`.terraform`、`.gradle` | 报告；`.tox` 等没有实测过软链接，确认后可用 `--externalize` 指定 |
+| 工具缓存 | `__pycache__`、`.pytest_cache`、`.mypy_cache`、`.ruff_cache`、`.hypothesis`、`.cache`、`.eslintcache`、`.parcel-cache`、`.turbo`，以及任何带 `CACHEDIR.TAG` 的目录 | 报告并给出环境变量写法，不移动 |
+| 运行中进程的文件 | `*-wal`、`*-shm`、`*.pid`、`*.sock`（`*.lock` 是依赖锁，必须同步，不算） | 只报告 |
+| **默认保持同步** | `dist`、`build`、`out`（构建产物，别的设备不必重新构建）、`.claude`、`.cursor`、`.idea`、`.vscode`（本机工具状态） | 不报告；体积由阈值兜底；可用 `keep_synced` 调整 |
+| 不碰 | `.git`、`.svn`、`.hg` | 不进入 |
+
+识别靠**标记文件**，名字只作兜底：`pyvenv.cfg` 是虚拟环境，`CACHEDIR.TAG` 是工具声明的缓存。“被 git 忽略”只能作候选，不能自动归类——`.env` 也被忽略，但不可重建。
+
+## 实测兼容性
+
+2026-10-29，Linux 容器，软链接指向项目外目录：
+
+| 工具 | 结果 |
+| --- | --- |
+| uv 0.11.32 | 正常，链接保留；悬空链接时 `uv sync` 报 `File exists (os error 17)`，先建目标目录即可 |
+| 普通 venv + pip | 正常（脚本里的路径经过链接解析） |
+| yarn 1.22.22、bun 1.4.4 | 正常，重复安装后链接保留 |
+| **npm 10.9.4** | `install` 与 `ci` 都把链接**换成真实目录**（相对、绝对、无变化都一样） |
+| **pnpm 10.28.0** | 安装失败（退出码 236），并删掉了链接目标目录 |
+| `PYTHONPYCACHEPREFIX`、`RUFF_CACHE_DIR`、`MYPY_CACHE_DIR`、`pytest -o cache_dir`、`UV_CACHE_DIR` | 生效，项目内零残留 |
+
+结论：同步目录里的 Node 项目尽量用 **yarn（经典版）或 bun**；npm、pnpm 的 `node_modules` 没有已验证的外置办法，工具只报告，不替你换包管理器（那会改 lock 文件）。项目不在同步目录里时随便用。
+
+**未确认**（需要在真机核对，工具不依赖它们给结论）：iCloud、Dropbox、OneDrive 是否同步软链接本身；yarn 2+（PnP 或 node-modules 链接方式）；iCloud“桌面与文稿”同步的项目路径上看不出来（需要声明 `sync_service`）；各服务冲突副本的命名（目前只识别 Dropbox 的 `conflicted copy`、iCloud 的 `.icloud` 占位文件）；macOS 上同步状态（是否在同步、账号状态）没有找到可靠的检测办法，工具不报告。
+
+## 命令
+
+```bash
+agenthelm local-only check [--mode quick|standard|full] [--strict] [--output json]
+agenthelm local-only check --fingerprint [--explain 对方的.json]
+agenthelm local-only fix [--externalize 路径]… [--raise-limit 目录=MB[/文件数]]… [--service icloud|dropbox|onedrive|google-drive|syncthing|other|none] [--rebuild] [--apply]
+agenthelm local-only config [--output json]
+```
+
+- `check` 默认 `full`（最多 120 秒）；`standard`（6 秒预算）用于 `agenthelm check` / `health`；`quick`（浅层两级目录、不统计体积，1.5 秒）用于会话开始钩子。超过预算会在“说明”里标出只扫了一部分。
+- `check --strict`：有“需要处理”的项时退出码为 1。`agenthelm check --strict` 与会话开始的一行提示也把它们算作未处理。
+- `fix` 不带选项：处理所有推荐项（venv、可外置的 node_modules，以及这台设备上缺失的已声明条目）。首次会创建项目配置。
+- `fix --rebuild`：外置后在本机运行重建命令，由锁文件推断（`uv.lock`→`uv sync`，`poetry.lock`→`poetry install`，`yarn.lock`/`bun.lock(b)`→`install --frozen-lockfile`）。找不到锁文件或工具就跳过。重建失败不撤销外置。
+- 决定（不再提示）沿用 `agenthelm fix --skip <ID> --reason …`；`local:` 开头的 ID 只记在这台机器上。
+
+## 配置
+
+项目配置 `.agents/moe.sakanano.agent-pack/local-only.json`（随项目同步；`fix` 创建，之后你可以手改）：
+
+```json
+{
+  "schema_version": 1,
+  "project_id": "p-5bcae0a8ad",
+  "home": "/home/me",
+  "sync_service": "icloud",
+  "items": [{"path": ".venv", "kind": "venv"}],
+  "limits": {
+    "warn_ratio": 0.8,
+    "dir_mb": 200,
+    "dir_files": 20000,
+    "overrides": {"docs": {"dir_mb": 1000}}
+  },
+  "keep_synced": ["dist", "build", "out", ".claude", ".cursor", ".idea", ".vscode"],
+  "ignore": ["vendor"],
+  "extra_local_only": ["data/cache"]
+}
+```
+
+- `project_id`：由 `home` 与项目路径派生，预览与执行一致；两台设备同时初始化写出相同内容。
+- `sync_service`：声明后不再靠路径猜；`none` 表示不在同步盘里。
+- `limits`：每个**顶层目录**（及项目根的散文件）的体积与文件数阈值；`warn_ratio` 到达阈值的这个比例就开始提示。`overrides` 按目录覆盖。这些数字是默认的启发值，没有任何同步服务的官方限额作依据。
+- `keep_synced`：这些名字（或相对路径）永远不报告，覆盖标记判定。
+- `ignore`：完全不扫描。`extra_local_only`：额外当作本机专属的目录。
+- 用户级覆盖：`~/.config/agenthelm/config.json` 的 `local_only` 段，可写 `limits`、`keep_synced`、`ignore`。优先级：内置默认 < 用户配置 < 项目配置。项目配置优先，是因为阈值会影响各设备得出的结论，应当随项目走。
+
+## 体积快到阈值时
+
+达到 `warn_ratio` 的目录出现一条“接近阈值”的发现（达到阈值则是“需要处理”）。工具不替你选，列出：
+
+1. 确认这个体积正常，提高阈值（`fix --raise-limit 目录=MB/文件数 --apply`，写入项目配置，建议值为现值的 1.25 倍与旧阈值 2 倍中的较大者）；
+2. 不再提示（`fix --skip local:size:<目录> --reason …`，只记在这台机器；状态或阈值变化后会重新提示）；
+3. 在同步服务里把它设为不同步，或移出同步目录（工具不替你做）。
+
+不提供“外置”：普通内容外置后，其他设备看不到它。
+
+## 发现 ID
+
+| ID | 含义 | 级别 |
+| --- | --- | --- |
+| `local:sync-folder` | 项目位于同步盘（总览） | 建议 |
+| `local:home-mismatch` | HOME 与项目记录不一致 | 需要处理 |
+| `local:real:<路径>` | 同步目录里有真实的本机专属目录 | 需要处理 |
+| `local:link:<路径>` | 已声明条目的状态：未安装、尚未建立、又变回真实目录、指向别处、被文件占用 | 未安装与尚未建立为建议，其余需要处理 |
+| `local:pm:<目录>` | 同步目录里用 npm 或 pnpm | 建议 |
+| `local:cache` | 带环境变量写法的工具缓存目录（一组） | 建议 |
+| `local:size:<目录>` | 体积接近或超过阈值 | 接近为建议，超过需要处理 |
+| `local:runtime-files` | `-wal`/`-shm`/pid/socket 文件 | 建议 |
+| `local:conflict-copies` | 冲突副本 | 建议 |
+| `local:local-only-config` | 配置有错误（有错误的项不生效） | 建议 |
+
+“需要处理”在 `agenthelm check` 的汇总里让 `up_to_date` 变为 false（`--strict` 退出码 1）；`health` 里仍是“建议处理”，不改变 `health` 的退出码。
+
+## 多设备流程
+
+1. **设备 A（首次）**：`agenthelm local-only check` 查看；`agenthelm local-only fix` 预览；确认后 `fix --apply`。项目配置和软链接随同步盘到达其他设备。
+2. **设备 B**：同步完成后运行 `agenthelm local-only check`。软链接在、本机目录不在时报“这台机器还没有安装 …”（此时直接运行 `uv sync` 会报 `File exists`）；`fix --apply --rebuild` 建本机目录并按锁文件安装。同步服务不同步软链接时报“尚未建立”，同一条 `fix --apply` 补上。
+3. **对比**：两台设备各运行 `agenthelm local-only check --fingerprint --output json`，用 `--explain 对方的.json` 看差在哪里（有差异退出码 1）。`agenthelm check --fingerprint` 在项目配置了 local-only 时也带本机环境段，`--explain` 一并比较。指纹只含 HOME、链接状态与链接文本，不含平台和体积——macOS 与 Linux 不同属于正常。
+
+## 给 Agent 的协议
+
+- 用 MCP 工具 `agent_pack_cloud_sync_safety_check`（只读）获取发现；不要自己 `mv` / `ln -s` 项目里的目录。
+- `attention: true` 的发现需要告诉用户；每项的 `options` 里有可执行的命令，**移动目录与改配置要用户同意后**再运行 `agenthelm local-only fix … --apply`。
+- 体积类发现必须把选项交给用户决定，不要替用户提高阈值。
+- 项目没有同步服务、也没有配置时工具返回空发现，不要自己提示“需要外置”。

package/runtime/plugins/agent-pack/references/nudge.en.md

@@ -0,0 +1,58 @@
+# nudge: automatic opinion capture and reminders about unconfirmed items
+
+**English** · [简体中文](nudge.md)
+
+`agenthelm nudge` is called by the hooks of all three clients so that the opinion mechanism works even when the user does not bring it up: at session start it injects the protocol and the trial rules; during work it reminds the Agent to stash lasting preferences; when a task is done it asks the user to confirm candidates together; and when a new session starts it reports candidates that have been waiting too long, according to thresholds. It only reads and writes opinion-manager's inbox and local machine state, and never writes `OPINION.md`. The inbox and its status flow are described in opinion-manager's `references/inbox.en.md`.
+
+## Behavior per client
+
+- **Claude Code**: the plugin ships `hooks/hooks.json`, effective after installation. SessionStart (`startup|resume|clear|compact`) injects the protocol; UserPromptSubmit reminds when a keyword matches; Stop uses `additionalContext` to make the Agent confirm with the user when the conditions are met.
+- **Codex**: reads the same `hooks/hooks.json` (Codex also provides `CLAUDE_PLUGIN_ROOT`). By Codex's rules a plugin hook runs only after the user reviews and trusts it in `/hooks`. Stop uses `decision: "block"` with a `reason`, and the reason text becomes the next turn's continuation prompt.
+- **Cursor**: has no prompt-level injection (`beforeSubmitPrompt` can only allow or block). Run `agenthelm nudge install-hooks --client cursor` to preview and add `--apply` to write sessionStart and stop into `~/.cursor/hooks.json` (`--scope project` writes the project's `.cursor/hooks.json`; `--remove` undoes it and deletes only the entries agenthelm wrote). Cursor's `stop` prompt appears as a "user message", so it is off by default. The community reports cases where sessionStart's `additional_context` does not reach the model (see the Cursor forum), so the protocol is also written in opinion-manager's Skill and can be triggered on demand without the hook.
+
+All three clients share these properties: the hook always exits 0 and stays silent on any error; it produces output only in projects that use opinion-manager (the Project Profile's `opinion.provider` is `opinion-manager`, or `.opinion/` or `opinion.lock.json` exists), so other directories never notice it.
+
+## Triggers
+
+- **Session start**: always injects the protocol and the full text of trial candidates (up to 6000 characters); after `compact` it only re-injects. When the number of pending candidates reaches `pending_threshold`, or the oldest one is older than `stale_days`, and the last reminder is older than `reminder_repeat_hours`, the user also gets one visible line.
+- **User message**: the message is at most 1500 characters and contains any word from `keywords` (case-insensitive), at most `capture_hints_per_session` reminders per session. Keywords only raise the hit rate; the semantic judgement stays with the Agent. Long messages are mostly pasted content and are skipped.
+- **End of turn**: candidates from this session exist that have not been shown yet, `stop_prompt` allows it, `max_prompts_per_session` is not exceeded and (with `on-completion`) the last reply contains one of `completion_keywords`. Continuation turns (`stop_hook_active`, or Cursor's `loop_count`) never trigger it. The candidates are marked as shown when the request is sent.
+
+## Configuration
+
+Locations (later overrides earlier): built-in defaults → the Project Profile's `opinion.nudge` (synced with the project, shared by the team) → the user config `nudge` in `~/.config/agenthelm/config.json` (a personal override). Defaults apply when nothing is set, and the Profile does not need to declare anything. Invalid values are ignored and reported by `agenthelm nudge status`.
+
+- `enabled`: default `true`.
+- `language`: message language, `auto` / `zh` / `en`, default `auto`. See the next section.
+- `pending_threshold`: remind when at least this many candidates are pending, default `5`.
+- `stale_days`: remind when the oldest pending candidate is older than this, default `7`.
+- `max_prompts_per_session`: upper limit of end-of-turn confirmation requests per session, default `1`.
+- `capture_hints_per_session`: upper limit of keyword reminders per session, default `3`.
+- `trial_expire_days`: a trial not made formal within this many days returns to pending, default `30`.
+- `reminder_repeat_hours`: shortest interval between visible session-start reminders, default `24`.
+- `stop_prompt`: `off` / `on-completion` / `always`, or per client, default `{"claude": "on-completion", "codex": "on-completion", "cursor": "off"}`.
+- `keywords`, `completion_keywords`: arrays of strings that replace the built-in lists.
+
+The environment variable `AGENTHELM_NO_NUDGE=1` temporarily silences all output; `AGENTHELM_NUDGE_DEBUG=1` prints internal hook exceptions to stderr. `agenthelm nudge status [--project P]` shows the effective configuration, the current summary and whether a new session would remind.
+
+## Message language
+
+The messages shown to the user and the protocol injected into the model use the same language; Chinese (`zh`) and English (`en`) are supported. The language is decided in this order: the config `nudge.language` (when it is not `auto`) → the environment variable `AGENTHELM_LANG` → the `language` key of the user config `~/.config/agenthelm/config.json` (shared by every agenthelm command) → the system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`) → English. A Chinese locale gets Chinese; a locale of any other language gets English for now; `C` / `POSIX` / empty means "not specified", so the next variable is consulted, and English applies when none names a language. The user config's `nudge.language` overrides the Project Profile, so you can override the team's setting with your own language.
+
+- The resolved language is passed on to opinion-manager's `inbox` (`--lang`), so the protocol, the privacy notice, the pending list and the hook messages share one language. The protocol also tells the Agent to relay and confirm in the language the user is using, so the conversation language settles any mismatch with the system language.
+- A candidate's title, rule and the user's quote are the user's own words and are never translated. The keyword lists are data; they contain both Chinese and English by default and can be edited.
+- To add a language, add one entry per message in `MESSAGES` in `runtime/nudge_text.py` and in opinion-manager's `runtime/inbox_text.py`. The tests require every language in each file to have identical keys and placeholders, English text to contain no Chinese, and both files to resolve languages the same way.
+
+## Local machine state
+
+Session counters and reminder times are stored in `$XDG_STATE_HOME/agenthelm/nudge.json` (default `~/.local/state`). It holds only session ids and timestamps, for 14 days and at most 200 sessions. The candidates themselves live in the project.
+
+## Verification status
+
+Unit tests cover each client's output format, thresholds, rate limits, keywords, config merging and the Cursor hooks.json merge. The following is written from the official documentation and has not yet been verified in real clients: Codex's trust flow for plugin hooks and its `systemMessage` field; Cursor's sessionStart injection and the actual loading of `~/.cursor/hooks.json`; how Claude Code's `Stop` `additionalContext` behaves across versions.
+
+## Privacy: the inbox holds the user's own words
+
+The evidence for a candidate is the user's own words, stored in `.opinion/inbox.json` inside the project; they may contain sensitive information (customer names, internal systems, people's names, business details). Projects that use this feature should stay private, or at least stay out of public channels. If you want to make the repository public or place it in a synced or shared folder, whether to exclude `.opinion/` is the user's decision.
+
+nudge only reminds and never decides for the user: the first `inbox add` returns a `notice`, each project gets one visible line when its first session starts (nothing is shown when Git already ignores the file), and `agenthelm nudge status` shows the current state at any time. It never edits `.gitignore` and never deletes, rewrites or refuses to store anything.

package/runtime/plugins/agent-pack/references/nudge.md

@@ -0,0 +1,58 @@
+# nudge：自动采集观点候选与未决事项提示
+
+[English](nudge.en.md) · **简体中文**
+
+`agenthelm nudge` 由三个客户端的 hook 调用，让 opinion 机制在用户不主动提起时也能工作：会话开始注入协议与试行规则，工作中发现长期偏好时提醒 Agent 暂存，任务完成时请用户集中确认，开新会话时按阈值提示久未处理的候选。它只读写 opinion-manager 的收件箱和本机状态，从不写 `OPINION.md`。收件箱与状态流转见 opinion-manager 的 `references/inbox.md`。
+
+## 各客户端的行为
+
+- **Claude Code**：插件随附 `hooks/hooks.json`，安装后自动生效。SessionStart（`startup|resume|clear|compact`）注入协议；UserPromptSubmit 在命中关键词时提醒；Stop 在满足条件时用 `additionalContext` 让 Agent 向用户确认。
+- **Codex**：读取同一个 `hooks/hooks.json`（Codex 同时提供 `CLAUDE_PLUGIN_ROOT`）。按 Codex 的规则，插件 hook 需要用户在 `/hooks` 中审阅并信任后才会运行。Stop 使用 `decision: "block"` 加 `reason`，原因文本成为下一轮的续写提示。
+- **Cursor**：没有 prompt 级注入（`beforeSubmitPrompt` 只能放行或拦截）。运行 `agenthelm nudge install-hooks --client cursor` 预览，加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`（`--scope project` 写项目的 `.cursor/hooks.json`；`--remove` 撤销，只删除 agenthelm 写入的条目）。Cursor 的 `stop` 提示以“用户消息”的形式出现，默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈（见 Cursor 论坛），所以协议同时写在 opinion-manager 的 Skill 里，不依赖 hook 也能按需触发。
+
+三个客户端的共同点：hook 永远退出 0，任何异常都静默；只在项目启用了 opinion-manager（Project Profile 的 `opinion.provider` 为 `opinion-manager`，或存在 `.opinion/`、`opinion.lock.json`）时才有输出，其他目录完全无感。
+
+## 触发条件
+
+- **会话开始**：总是注入协议与试行候选全文（上限 6000 字符）；`compact` 后只重新注入。待确认候选数 ≥ `pending_threshold`，或最久一条超过 `stale_days`，且距上次提示超过 `reminder_repeat_hours` 时，另给用户一行可见提示。
+- **用户消息**：消息 ≤1500 字符且包含 `keywords` 中任一词（不区分大小写），每个会话最多提醒 `capture_hints_per_session` 次。关键词只是提高命中率的辅助，语义判断仍由 Agent 做；长消息多为粘贴内容，跳过。
+- **回合结束**：本会话暂存且没展示过的候选存在、`stop_prompt` 允许、未超过 `max_prompts_per_session`，且（`on-completion` 时）最后一条回复含 `completion_keywords` 之一。续写回合（`stop_hook_active` 或 Cursor 的 `loop_count`）不再触发。发出请求时把这些候选标记为已展示。
+
+## 配置
+
+位置（后者覆盖前者）：内置默认 → Project Profile 的 `opinion.nudge`（随项目同步，团队共享）→ 用户配置 `~/.config/agenthelm/config.json` 的 `nudge`（本人覆盖）。缺省即默认值，不要求在 Profile 里声明。非法值被忽略并在 `agenthelm nudge status` 里报告。
+
+- `enabled`：默认 `true`。
+- `language`：提示语言，`auto` / `zh` / `en`，默认 `auto`。见下一节。
+- `pending_threshold`：待确认候选 ≥ 此数就提示，默认 `5`。
+- `stale_days`：最久一条待确认候选超过此天数就提示，默认 `7`。
+- `max_prompts_per_session`：每会话回合结束的确认请求上限，默认 `1`。
+- `capture_hints_per_session`：每会话关键词提醒上限，默认 `3`。
+- `trial_expire_days`：试行超过此天数未转正退回待确认，默认 `30`。
+- `reminder_repeat_hours`：会话开始的可见提示最短间隔，默认 `24`。
+- `stop_prompt`：`off` / `on-completion` / `always`，或按客户端设置，默认 `{"claude": "on-completion", "codex": "on-completion", "cursor": "off"}`。
+- `keywords`、`completion_keywords`：字符串数组，替换内置列表。
+
+环境变量 `AGENTHELM_NO_NUDGE=1` 临时关闭全部输出；`AGENTHELM_NUDGE_DEBUG=1` 把 hook 内部异常打印到 stderr。`agenthelm nudge status [--project P]` 显示生效配置、当前汇总以及开新会话是否会提示。
+
+## 提示语言
+
+给用户看的提示和注入给模型的协议使用同一种语言，目前支持中文（`zh`）和英文（`en`）。按这个顺序决定：配置 `nudge.language`（不是 `auto` 时）→ 环境变量 `AGENTHELM_LANG` → 用户配置 `~/.config/agenthelm/config.json` 的 `language`（所有 agenthelm 命令共用）→ 系统 locale（`LC_ALL`、`LC_MESSAGES`、`LANG`）→ 英文。中文 locale 用中文；其他语言的 locale 暂用英文；`C` / `POSIX` / 空值视为未指定，继续看下一个变量，都没有就用英文。用户配置的 `nudge.language` 优先于项目 Profile，所以你可以按自己的语言覆盖团队的设置。
+
+- 解析出的语言会传给 opinion-manager 的 `inbox`（`--lang`），所以协议、隐私提醒、待确认列表与 hook 的提示是同一种语言。协议同时要求 Agent 向用户转告和确认时使用用户正在使用的语言，系统语言与对话语言不一致时由对话语言兜底。
+- 候选的标题、规则和用户原话是用户自己的话，从不翻译；关键词列表是数据，默认同时包含中文和英文，可自行增删。
+- 新增语言只需在 `runtime/nudge_text.py` 与 opinion-manager 的 `runtime/inbox_text.py` 的 `MESSAGES` 里为每条文案补一个语言；测试要求每个目录里各语言的键与占位符完全一致，英文文案不得含中文，两处的语言解析规则一致。
+
+## 本机状态
+
+会话计数与提示时间保存在 `$XDG_STATE_HOME/agenthelm/nudge.json`（缺省 `~/.local/state`），只含会话编号和时间戳，保留 14 天、最多 200 个会话。候选本身在项目内。
+
+## 验证状态
+
+单元测试覆盖各客户端的输出格式、阈值、限频、关键词、配置合并和 Cursor hooks.json 合并。以下依据官方文档编写，尚未在真实客户端里逐一验证：Codex 对插件 hook 的信任流程与 `systemMessage` 字段；Cursor 的 sessionStart 注入、`~/.cursor/hooks.json` 的实际加载；Claude Code `Stop` 的 `additionalContext` 在各版本的表现。
+
+## 隐私：收件箱含用户原话
+
+候选的证据是用户的原话，保存在项目内的 `.opinion/inbox.json`，可能含敏感信息（客户名、内部系统、人名、业务细节）。启用本功能的项目建议保持私有，至少不要放进公开渠道。若要公开仓库、放进同步盘或共享目录，是否排除 `.opinion/` 由用户决定。
+
+nudge 只提醒，不替用户决定：第一次 `inbox add` 的返回带 `notice`，每个项目第一次开会话时给一行可见提示（已被 Git 忽略则不提醒），`agenthelm nudge status` 随时显示当前状态。它不会修改 `.gitignore`，也不会删除、改写或拒绝保存任何内容。