@sakanano-moe/agenthelm 6.12.0-rc.1 → 6.13.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/package.json +1 -1
  2. package/runtime/index.json +5 -5
  3. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  4. package/runtime/plugins/agent-pack/plugin.json +1 -1
  5. package/runtime/plugins/agent-pack/references/capability-config.md +32 -1
  6. package/runtime/plugins/agent-pack/references/nudge.en.md +1 -1
  7. package/runtime/plugins/agent-pack/references/nudge.md +1 -1
  8. package/runtime/plugins/agent-pack/runtime/agent_pack_claude.py +172 -20
  9. package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +286 -35
  10. package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +65 -2
  11. package/runtime/plugins/agent-pack/runtime/agenthelm.py +99 -9
  12. package/runtime/plugins/agent-pack/runtime/locale/en.json +15 -1
  13. package/runtime/plugins/agent-pack/runtime/mcp_env_launcher.py +26 -4
  14. package/runtime/plugins/agent-pack/runtime/mcp_server.py +15 -1
  15. package/runtime/plugins/agent-pack/runtime/nudge_text.py +17 -4
  16. package/runtime/plugins/agent-pack/runtime/user_settings.py +25 -6
  17. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  18. package/runtime/plugins/agents-init/plugin.json +1 -1
  19. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +25 -0
  20. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  21. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  22. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  23. package/runtime/plugins/opinion-manager/references/inbox.en.md +7 -2
  24. package/runtime/plugins/opinion-manager/references/inbox.md +7 -2
  25. package/runtime/plugins/opinion-manager/runtime/inbox.py +155 -7
  26. package/runtime/plugins/opinion-manager/runtime/inbox_text.py +19 -6
  27. package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md +4 -3
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sakanano-moe/agenthelm",
3
- "version": "6.12.0-rc.1",
3
+ "version": "6.13.0-rc.1",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "bin": {
@@ -4,14 +4,14 @@
4
4
  "name": "agenthelm",
5
5
  "description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
6
6
  "version": "0.7.0",
7
- "updated_at": "2026-11-07",
7
+ "updated_at": "2026-11-10",
8
8
  "homepage": "./index.html",
9
9
  "domain": "agenthelm.sakanano.moe",
10
10
  "legacy_domain": "skill.sakanano.moe"
11
11
  },
12
12
  "plugin": {
13
13
  "manifest": "./plugins/agents-init/plugin.json",
14
- "version": "6.12.0",
14
+ "version": "6.13.0",
15
15
  "install_unit": "marketplace",
16
16
  "bundled_plugins": [
17
17
  "./plugins/project-orchestrator/plugin.json",
@@ -30,7 +30,7 @@
30
30
  "id": "agents-init",
31
31
  "name": "agents-init v6 / Project Profile initialization and migration",
32
32
  "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.",
33
- "version": "6.9.0",
33
+ "version": "6.9.1",
34
34
  "status": "stable",
35
35
  "entrypoints": {
36
36
  "browser": "./plugins/agents-init/skills/agents-init/index.html",
@@ -55,7 +55,7 @@
55
55
  "id": "agent-pack",
56
56
  "name": "agent-pack / Agent extension capability management",
57
57
  "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.",
58
- "version": "1.12.0",
58
+ "version": "1.13.0",
59
59
  "status": "stable",
60
60
  "entrypoints": {
61
61
  "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
@@ -68,7 +68,7 @@
68
68
  "id": "opinion-manager",
69
69
  "name": "opinion-manager / Agent behavior rule management",
70
70
  "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.",
71
- "version": "0.5.2",
71
+ "version": "0.6.0",
72
72
  "status": "experimental",
73
73
  "entrypoints": {
74
74
  "agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-pack",
3
- "version": "1.12.0",
3
+ "version": "1.13.0",
4
4
  "description": "Deterministic Agent-extension capability management for configured workspaces.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "agent-pack",
4
- "version": "1.12.0",
4
+ "version": "1.13.0",
5
5
  "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.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -69,6 +69,12 @@ python3 /path/to/agent-pack/runtime/agent_pack_config.py --output json bootstrap
69
69
  - 按项目和 Claude 的 `mcp_client_policy` 单独生成一份包,放在 `~/.claude/agent-pack/packages/<name>/`;安装记录 `~/.claude/agent-pack/plugins/<name>` 改为指向它;Skill 链接与 MCP 条目都指向这份包。
70
70
  - `~/.claude/agent-pack/state/<name>.json` 记下本包装进 Claude 的 Skill 与 MCP。项目里新增的会加上,改了的会更新,删掉或被策略排除的会移除;**只动清单里的条目**,用户自己配置的条目从不改动。
71
71
  - 与用户自己的同名条目冲突时停止,加 `--replace` 才替换(旧内容进恢复目录)。本机认证默认保留,`--reset-overrides` 丢弃。
72
+ - **按类型同步(`--only`)与按类型替换(`--replace-mcp` / `--replace-skills`)**,`sync` 与 `reconcile` 共用,MCP Tool `agent_pack_sync` / `agent_pack_reconcile` 暴露同名参数 `only` / `replaceMcp` / `replaceSkills`:
73
+ - `--only mcp|skills|plugins`(可重复或逗号分隔,不带时为全部):`mcp` = `~/.claude.json` 里的用户级 MCP 条目;`skills` = `~/.claude/skills/` 里的 Skill 链接;`plugins` = 项目包与安装记录。没选中的类型不出现在 `operations`,不计入冲突,也不写入(包括 `~/.claude.json`);包是另外两类的载体,所以部分同步仍会安装包,但只替换所选类型对应的部分(`skills/`、`mcp.json` 与 `runtime/`、清单),其余保持已安装的内容。`state` 只更新所选类型的归属记录。
74
+ - `--replace` 仍替换全部类型的冲突;`--replace-mcp` 只放行 MCP 冲突,`--replace-skills` 只放行 Skill 冲突,没放行类型的冲突照常阻塞。
75
+ - 预览和结果在有冲突时给出 `conflicts`(按类型计数),并在 `warnings` 里提示:用户级 Skill 与 MCP 条目对所有项目生效,被替换的原件进恢复目录。
76
+ - 显式的 `--retire-skill` / `--retire-plugin` 不受 `--only` 过滤。Codex 与 Cursor 把 Skill、MCP 与清单装在同一个包里,只接受全部类型(`--only mcp,skills,plugins` 等价于不带);部分选择与 `--replace-skills` 会明确报错、不写入。`--replace-mcp` 在 Codex 等同于对原生远程 MCP 条目使用 `--replace`。`bootstrap` 已有按名称选择的 `--skill` / `--mcp`,不增加 `--only`。
77
+
72
78
  - 安装记录原来指向别的目录(旧做法:`bootstrap --plugin ~/.agents/plugins/plugins/<name> --client claude`)时,第一次同步自动迁移:旧记录指向写入恢复目录的 `record.json`,指向旧目录的 Skill 链接改为指向新包。此后 Codex 端的包怎么变、是否删除,都不影响 Claude。
73
79
  - 默认只预览;`--apply` 时整笔操作写入同一个恢复目录,任一步失败全部回滚。
74
80
 
@@ -116,6 +122,18 @@ python3 <plugin-root>/runtime/agent_pack_config.py --output json reconcile \
116
122
  --project /path/to/project --client cursor --retire-plugin project-runtime --retire-only --apply
117
123
  ```
118
124
 
125
+ ### 退役插件的完整清单(`--retire-plugin`)
126
+
127
+ 退役一个插件会同时处理它在该客户端的所有入口;预览(不带 `--apply`)逐项列出,`--apply` 先归档到 `--recovery-root`(默认 `~/.agent-pack/recovery/`)再移除,失败时整体回滚:
128
+
129
+ | 客户端 | 自动处理(`operations`) | 不自动处理(`residuals`,每项含 `path` 与 `manual`) |
130
+ | --- | --- | --- |
131
+ | Claude | `archive-plugin`(安装记录);`archive-skill`(`~/.claude/skills/` 中**仅指向该插件目录**的符号链接,其它链接、真实目录与项目包的链接不动) | 仍指向该插件的 `~/.claude.json` MCP 条目(`claude mcp remove --scope user <名称>`);由 Claude Code 管理的 `installed_plugins.json` 记录(`claude plugin uninstall`) |
132
+ | Codex | `archive-plugin`(缓存版本);`archive-plugin-copy`(`~/.agents/plugins/plugins/<名称>/`);`remove-marketplace-entry`(个人市场 `marketplace.json` 中该插件的条目,其它条目与缩进保持) | 缓存里的其它版本、`~/.codex/config.toml` 里的 `[plugins."<名称>@…"]` 表(用户配置,不自动编辑) |
133
+ | Cursor | `archive-plugin`(本地插件目录) | 无 |
134
+
135
+ 没有残留项时输出不含 `residuals`;有残留项时文本输出以 `! residual …` 逐行列出(不回显文件内容)。
136
+
119
137
  结果把组件分为 `exact`、`conflict`、`missing`、`native_only` 与 `blocked`。替换包和明确退役的组件移动到 `~/.agent-pack/recovery/`;事务失败时自动恢复。
120
138
 
121
139
  Codex 同步会写入 `~/.agents/plugins/plugins/<name>` 可移植包、`.codex-plugin` adapter 与 `~/.agents/plugins/marketplace.json` 的 `personal` 条目。之后需在 Codex 桌面版的插件设置里启用 / 重新同步 `<name>@personal`(并确认 `~/.codex/config.toml` 有 `[plugins."<name>@personal"] enabled = true`)来激活;同步只更新 marketplace 源,Codex 自身缓存 `~/.codex/plugins/cache/personal/` 要到下次激活或重启才追平。homebrew 版 `codex-cli` 无 `codex plugin` 子命令,`plugin` / `marketplace` 命令与 UI 随 Codex 版本变化,以当前 Codex 文档为准。Cursor 同步会在本地插件根目录安装真实的 Agent Plugin 目录。
@@ -144,7 +162,20 @@ Codex 同步会写入 `~/.agents/plugins/plugins/<name>` 可移植包、`.codex-
144
162
  - **stdio 的环境变量引用**:把 `credential_env_file` 设置为项目相对路径的 dotenv 文件,权限必须为 `0600`。生成包只保存 `${VAR}` 引用;本地 launcher 在 MCP 启动时读取值,禁止复制进 Git 或插件 manifest。
145
163
  - 使用 `mcp_client_policy.<server>.include` 或 `.exclude` 完成客户端路由(`codex`、`cursor`、`claude` 各自生效)。禁止在 MCP 定义中放入 adapter 专属 `_skip` 字段。
146
164
  - 客户端里本机才有的认证值(例如远程 MCP 的 `headers.Authorization`)不进入项目;同步与 bootstrap 默认保留它们,`--reset-overrides` 才丢弃。
147
- - `${PLUGIN_ROOT}` 用于不可变包文件,`${PLUGIN_DATA}` 用于客户端管理的可写状态。
165
+ - `${PLUGIN_ROOT}` 用于不可变包文件,`${PLUGIN_DATA}` 用于客户端管理的可写状态。项目合并包只含 Skill、`mcp.json` 与 launcher,详见下一节。
166
+
167
+ ## MCP 条目里的路径与变量占位符
168
+
169
+ | 写法 | 含义 | 何时解析 |
170
+ | --- | --- | --- |
171
+ | `${HOME}`、`${USER}`、`${LOGNAME}`、`${TMPDIR}`、`${XDG_CONFIG_HOME}`、`${XDG_DATA_HOME}`、`${XDG_CACHE_HOME}`、`${XDG_STATE_HOME}` | 系统变量,描述本机而不是凭据。`HOME` 取 `--home`(默认当前用户主目录),XDG 变量取进程环境,未设置时用 `HOME` 下的默认目录 | `sync` / `bootstrap` 生成包时展开为本机值;每台机器各自同步,所以是“用户主目录”的可移植写法,禁止写死绝对路径 |
172
+ | `__PROJECT_DIR__` | 该条目所在 MCP 来源文件的目录 | 生成包时展开 |
173
+ | `__REPO_ROOT__` | 项目根目录 | 生成包时展开 |
174
+ | `${PLUGIN_ROOT}/<路径>`(含被 launcher 包装的条目) | 该条目所在来源的插件目录(来源文件所在目录)里的文件 | 生成包时按**各自来源**解析;包内本来就有的(`skills/<名称>/…`)保持 `${PLUGIN_ROOT}`,其余指向来源目录里实际存在的文件的绝对路径;两处都没有则 `sync` 与 `doctor` 阻塞并给出条目名、来源文件与路径。launcher 按自身位置(`<包根>/runtime/`)推导 `PLUGIN_ROOT`,不从进程环境或 `credential_env_file` 读取 |
175
+ | `${PLUGIN_DATA}` | 客户端管理的可写状态目录 | 由客户端在启动时解析;被 launcher 包装的条目(含凭据键)引用它时,生成的 launcher 参数末尾追加 `--plugin-data ${PLUGIN_DATA}`,由客户端展开后传给 launcher,launcher 再代入其 config |
176
+ | 其他 `${NAME}` | 凭据键 | 必须在 `credential_env_file` 里存在;缺失时 `sync` 阻塞并只列出键名 |
177
+
178
+ 系统变量不要求出现在 `credential_env_file` 中;真正缺失的凭据键仍会被报告。预览与 `--apply` 使用同一套校验。
148
179
  - 客户端原生 adapter 只在安装阶段使用;Agent Plugins 1.0 文件保持权威源地位。
149
180
 
150
181
  ## 远程 HTTP 认证与更新项目声明
@@ -8,7 +8,7 @@
8
8
 
9
9
  - **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.
10
10
  - **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.
11
- - **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.
11
+ - **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). When run through `npx`, the hook commands never point into npx's temporary cache (`…/_npx/<hash>/…`; the hooks would break once the cache is cleaned). They use an installed stable entry instead: first `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`, then `<data dir>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py` after `agenthelm runtime install` (the temporary folders of pnpm dlx, yarn dlx and bunx are recognised too). If neither exists, the preview warns and `--apply` refuses to write, exiting with code 2; run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply` first. `--remove` is not affected. 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.
12
12
 
13
13
  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.
14
14
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  - **Claude Code**:插件随附 `hooks/hooks.json`,安装后自动生效。SessionStart(`startup|resume|clear|compact`)注入协议;UserPromptSubmit 在命中关键词时提醒;Stop 在满足条件时用 `additionalContext` 让 Agent 向用户确认。
10
10
  - **Codex**:读取同一个 `hooks/hooks.json`(Codex 同时提供 `CLAUDE_PLUGIN_ROOT`)。按 Codex 的规则,插件 hook 需要用户在 `/hooks` 中审阅并信任后才会运行。Stop 使用 `decision: "block"` 加 `reason`,原因文本成为下一轮的续写提示。
11
- - **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 也能按需触发。
11
+ - **Cursor**:没有 prompt 级注入(`beforeSubmitPrompt` 只能放行或拦截)。运行 `agenthelm nudge install-hooks --client cursor` 预览,加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`(`--scope project` 写项目的 `.cursor/hooks.json`;`--remove` 撤销,只删除 agenthelm 写入的条目)。经 `npx` 运行时,hook 命令不会指向 npx 的临时缓存(`…/_npx/<哈希>/…`,缓存被清理后 hook 会失效):改用已安装的稳定入口,先找 `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`,再找 `agenthelm runtime install` 之后的 `<数据目录>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py`(pnpm dlx、yarn dlx、bunx 的临时目录同样识别);两处都没有时预览给出警告,`--apply` 拒绝写入并以退出码 2 退出,请先运行 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。`--remove` 不受影响。Cursor 的 `stop` 提示以“用户消息”的形式出现,默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈(见 Cursor 论坛),所以协议同时写在 opinion-manager 的 Skill 里,不依赖 hook 也能按需触发。
12
12
 
13
13
  三个客户端的共同点:hook 永远退出 0,任何异常都静默;只在项目启用了 opinion-manager(Project Profile 的 `opinion.provider` 为 `opinion-manager`,或存在 `.opinion/`、`opinion.lock.json`)时才有输出,其他目录完全无感。
14
14
 
@@ -41,6 +41,60 @@ def record_path(home: Path, name: str) -> Path:
41
41
  return core._claude_plugin_records(home) / name
42
42
 
43
43
 
44
+ SYNC_TYPES = ("plugins", "skills", "mcp") # what ``--only`` can select; the default is all of them
45
+
46
+
47
+ def normalize_only(only: Iterable[str] | None) -> frozenset[str]:
48
+ """``--only`` values (repeatable or comma separated) as a set of types; empty or None means every type."""
49
+ types: set[str] = set()
50
+ for value in only or ():
51
+ for part in str(value).split(","):
52
+ part = part.strip()
53
+ if not part:
54
+ continue
55
+ if part not in SYNC_TYPES:
56
+ raise core.AgentPackError(f"unknown --only type: {part} (choose from {', '.join(SYNC_TYPES)})")
57
+ types.add(part)
58
+ return frozenset(types or SYNC_TYPES)
59
+
60
+
61
+ def _compose_package(existing: Path, built: Path, only: frozenset[str], scratch: Path) -> Path:
62
+ """The package tree a partial sync installs: what is already installed, with only the selected parts replaced.
63
+
64
+ ``skills`` owns ``skills/``; ``mcp`` owns ``mcp.json`` and ``runtime/`` (the launcher and its configs);
65
+ ``plugins`` owns everything else (the manifest). Unselected parts keep exactly what is installed.
66
+ """
67
+ composed = scratch / "composed" / built.name
68
+ composed.parent.mkdir(parents=True, exist_ok=True)
69
+ if existing.is_dir() and not existing.is_symlink():
70
+ shutil.copytree(existing, composed, symlinks=False)
71
+ else:
72
+ composed.mkdir()
73
+ parts = {"skills": ("skills",), "mcp": ("mcp.json", "runtime")}
74
+ owned = {name for names in parts.values() for name in names}
75
+
76
+ def replace(name: str) -> None:
77
+ target = composed / name
78
+ if target.is_dir():
79
+ shutil.rmtree(target)
80
+ elif target.exists():
81
+ target.unlink()
82
+ if (built / name).is_dir():
83
+ shutil.copytree(built / name, target, symlinks=False)
84
+ elif (built / name).is_file():
85
+ shutil.copy2(built / name, target)
86
+
87
+ for kind, names in parts.items():
88
+ if kind in only:
89
+ for name in names:
90
+ replace(name)
91
+ if "plugins" in only or not existing.is_dir():
92
+ for child in sorted(built.iterdir()):
93
+ if child.name not in owned:
94
+ replace(child.name)
95
+ return composed
96
+
97
+
44
98
  def state_path(home: Path, name: str) -> Path:
45
99
  return home / ".claude" / "agent-pack" / "state" / f"{name}.json"
46
100
 
@@ -151,6 +205,44 @@ def _inside(path: Path, root: Path) -> bool:
151
205
 
152
206
  # ---------------------------------------------------------------- plan
153
207
 
208
+ def _plugin_skill_links(home: Path, plugin_path: Path) -> list[Path]:
209
+ """User-level Skill links that point into the retired plugin's directory and nowhere else.
210
+
211
+ Only symlinks are considered; a real directory (the user's own Skill) and links to any other
212
+ place (project package, other plugins, hand-made links) are never returned.
213
+ """
214
+ skills_root = home / ".claude" / "skills"
215
+ if not skills_root.is_dir() or skills_root.is_symlink():
216
+ return []
217
+ roots = {plugin_path.resolve()}
218
+ found: list[Path] = []
219
+ for child in sorted(skills_root.iterdir(), key=lambda item: item.name):
220
+ target = _link_target(child)
221
+ if target is not None and any(_inside(target, root) for root in roots):
222
+ found.append(child)
223
+ return found
224
+
225
+
226
+ def _plugin_residuals(home: Path, plugin: str, plugin_path: Path, config: dict[str, Any]) -> list[dict[str, str]]:
227
+ """Entries a retirement leaves on purpose: files Claude Code owns or that may hold local credentials."""
228
+ residuals: list[dict[str, str]] = []
229
+ prefixes = {str(plugin_path), str(plugin_path.resolve())}
230
+ config_path = core._claude_user_config(home)
231
+ for server, entry in sorted(config.items()):
232
+ if any(text.startswith(prefix + os.sep) or text == prefix for text in _strings(entry) for prefix in prefixes):
233
+ residuals.append({
234
+ "client": "claude", "kind": "mcp", "name": server, "path": str(config_path),
235
+ "manual": f"MCP server {server} still points into the retired plugin; remove it with "
236
+ f"`claude mcp remove --scope user {server}` (the file may hold local credentials, so it is not edited automatically)"})
237
+ managed = home / ".claude" / "plugins"
238
+ if _inside(plugin_path, managed):
239
+ residuals.append({
240
+ "client": "claude", "kind": "installed-record", "name": plugin,
241
+ "path": str(managed / "installed_plugins.json"),
242
+ "manual": f"Claude Code owns this install record; run `claude plugin uninstall {plugin}`"})
243
+ return residuals
244
+
245
+
154
246
  def _render_package_mcps(package: Path, home: Path, name: str) -> dict[str, dict[str, Any]]:
155
247
  servers: dict[str, dict[str, Any]] = {}
156
248
  mcp_path = package / "mcp.json"
@@ -166,8 +258,15 @@ def _render_package_mcps(package: Path, home: Path, name: str) -> dict[str, dict
166
258
 
167
259
  def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: bool = False,
168
260
  retire_skills: Iterable[str] = (), retire_plugins: Iterable[str] = (),
169
- retire_only: bool = False) -> dict[str, Any]:
170
- """Every change a Claude sync would make, without writing; conflicts are listed, not raised."""
261
+ retire_only: bool = False, only: frozenset[str] = frozenset(SYNC_TYPES),
262
+ package_tree: Path | None = None) -> dict[str, Any]:
263
+ """Every change a Claude sync would make, without writing; conflicts are listed, not raised.
264
+
265
+ ``only`` limits the sync to those types (#68): ``plugins`` is the package and its install record,
266
+ ``skills`` the user-level Skill links, ``mcp`` the user-scope MCP entries. ``package_tree`` is the
267
+ tree that will be installed as the package (default: ``built``). Explicit retirements are never filtered.
268
+ """
269
+ package_tree = package_tree or built
171
270
  layout = core.load_project_layout(project)
172
271
  authority = core.inventory_project(layout.root)
173
272
  name = core._package_name(layout.root)
@@ -190,10 +289,14 @@ def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: boo
190
289
  operations: list[dict[str, Any]] = []
191
290
  conflicts: list[str] = []
192
291
  overrides: list[dict[str, Any]] = []
292
+ residuals: list[dict[str, str]] = []
193
293
 
294
+ sync_skills, sync_mcps = "skills" in only, "mcp" in only
194
295
  if not retire_only:
296
+ # The package is the carrier of the other two types, so a partial sync still installs it (composed
297
+ # from what is installed plus the selected parts); the record link follows the package.
195
298
  if package.exists() and not package.is_symlink():
196
- same = core._tree_fingerprint(package) == core._tree_fingerprint(built)
299
+ same = core._tree_fingerprint(package) == core._tree_fingerprint(package_tree)
197
300
  operations.append({"action": "keep-package" if same else "replace-package", "name": name, "to": str(package)})
198
301
  else:
199
302
  operations.append({"action": "install-package", "name": name, "to": str(package)})
@@ -206,7 +309,7 @@ def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: boo
206
309
  operations.append({"action": "link-record", "name": name, "to": str(record)})
207
310
 
208
311
  skills_root = home / ".claude" / "skills"
209
- for skill in sorted(desired_skills):
312
+ for skill in sorted(desired_skills if sync_skills else ()):
210
313
  path, target = skills_root / skill, package / "skills" / skill
211
314
  link = _link_target(path)
212
315
  ours = skill in owned_skills or (link is not None and (
@@ -221,18 +324,18 @@ def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: boo
221
324
  action = "conflict-skill"
222
325
  conflicts.append(f"skill {skill}: {path}")
223
326
  operations.append({"action": action, "name": skill, "to": str(path)})
224
- for skill in sorted(owned_skills - desired_skills):
327
+ for skill in sorted(owned_skills - desired_skills if sync_skills else ()):
225
328
  path = skills_root / skill
226
329
  if path.is_symlink() or path.exists():
227
330
  operations.append({"action": "remove-skill", "name": skill, "from": str(path)})
228
- if legacy_root is not None and skills_root.is_dir():
331
+ if sync_skills and legacy_root is not None and skills_root.is_dir():
229
332
  for path in sorted(skills_root.iterdir()):
230
333
  link = _link_target(path)
231
334
  if (path.name not in desired_skills and path.name not in owned_skills and link is not None
232
335
  and _inside(link, legacy_root)):
233
336
  operations.append({"action": "remove-skill", "name": path.name, "from": str(path)})
234
337
 
235
- for server, rendered in desired_mcps.items():
338
+ for server, rendered in (desired_mcps.items() if sync_mcps else ()):
236
339
  state_name, entry, kept = classify_mcp(rendered, existing.get(server), reset=reset_overrides)
237
340
  if state_name == "differ":
238
341
  if server in owned_mcps:
@@ -243,7 +346,7 @@ def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: boo
243
346
  if kept:
244
347
  overrides.append({"name": server, "keys": kept})
245
348
  operations.append({"action": f"{state_name}-mcp", "name": server, "keys": kept, "_entry": entry})
246
- for server in sorted(owned_mcps - set(desired_mcps)):
349
+ for server in sorted(owned_mcps - set(desired_mcps) if sync_mcps else ()):
247
350
  if server in existing:
248
351
  operations.append({"action": "remove-mcp", "name": server,
249
352
  "reason": "excluded for claude" if server in excluded else "no longer in project"})
@@ -266,13 +369,20 @@ def plan_project(project: Path, home: Path, *, built: Path, reset_overrides: boo
266
369
  if path is None:
267
370
  raise core.AgentPackError(f"retire plugin not installed: {plugin}")
268
371
  operations.append({"action": "archive-plugin", "name": plugin, "from": str(path)})
372
+ taken = {item["name"] for item in operations if item["action"].endswith("-skill")}
373
+ for link in _plugin_skill_links(home, path):
374
+ if link.name not in taken:
375
+ operations.append({"action": "archive-skill", "name": link.name, "from": str(link),
376
+ "reason": f"links into retired plugin {plugin}"})
377
+ residuals.extend(_plugin_residuals(home, plugin, path, existing))
269
378
  if retire_only and not (retire_skills or retire_plugins):
270
379
  raise core.AgentPackError("retire-only reconcile needs at least one --retire-skill or --retire-plugin")
271
380
 
272
381
  native = sorted(server for server in existing if server not in desired_mcps and server not in owned_mcps)
273
382
  return {"name": name, "layout": layout, "operations": operations, "conflicts": conflicts,
274
- "retire_only": retire_only,
275
- "overrides": overrides, "excluded": [server for server in excluded if server in existing],
383
+ "retire_only": retire_only, "residuals": residuals, "only": sorted(only),
384
+ "overrides": overrides if sync_mcps else [],
385
+ "excluded": [server for server in excluded if server in existing] if sync_mcps else [],
276
386
  "native": native, "legacy_root": str(legacy_root) if legacy_root else None,
277
387
  "desired_skills": sorted(desired_skills), "desired_mcps": sorted(desired_mcps)}
278
388
 
@@ -284,35 +394,71 @@ def _public(operations: list[dict[str, Any]]) -> list[dict[str, Any]]:
284
394
 
285
395
  # ---------------------------------------------------------------- apply
286
396
 
397
+ def _conflict_summary(conflicts: list[str]) -> dict[str, int]:
398
+ """Conflicts counted per type; a conflict string starts with ``skill`` or ``mcp``."""
399
+ counts = {"skills": sum(1 for item in conflicts if item.startswith("skill ")),
400
+ "mcp": sum(1 for item in conflicts if item.startswith("mcp "))}
401
+ return {key: number for key, number in counts.items() if number}
402
+
403
+
404
+ def _global_warnings(home: Path, summary: dict[str, int]) -> list[str]:
405
+ """What a replace reaches beyond this project: user-level Skills and MCP entries serve every project."""
406
+ warnings = []
407
+ if summary.get("skills"):
408
+ warnings.append(f"replaces {summary['skills']} user-level Skill(s) in {home / '.claude' / 'skills'}; "
409
+ "they apply to every project (the replaced originals go to recovery)")
410
+ if summary.get("mcp"):
411
+ warnings.append(f"replaces {summary['mcp']} user-scope MCP entr{'y' if summary['mcp'] == 1 else 'ies'} in "
412
+ f"{core._claude_user_config(home)}; they apply to every project (the replaced originals go to recovery)")
413
+ return warnings
414
+
415
+
287
416
  def sync_project(project: Path, *, home: Path | None = None, apply: bool = False, replace: bool = False,
288
417
  reset_overrides: bool = False, recovery_root: Path | None = None,
289
418
  retire_skills: Iterable[str] = (), retire_plugins: Iterable[str] = (),
290
- retire_only: bool = False) -> dict[str, Any]:
419
+ retire_only: bool = False, only: Iterable[str] | None = None,
420
+ replace_mcp: bool = False, replace_skills: bool = False) -> dict[str, Any]:
291
421
  home = (home or Path.home()).expanduser().resolve()
292
422
  retire_skills, retire_plugins = list(retire_skills), list(retire_plugins)
423
+ types = normalize_only(only)
293
424
  with tempfile.TemporaryDirectory(prefix="agent-pack-claude-") as temporary:
294
425
  layout = core.load_project_layout(project)
295
426
  authority = core.inventory_project(layout.root)
296
427
  name = core._package_name(layout.root)
297
- built = core._build_package(authority, name, Path(temporary), "claude")
428
+ built = core._build_package(authority, name, Path(temporary), "claude", home)
429
+ tree = built if types == frozenset(SYNC_TYPES) else _compose_package(
430
+ package_root(home, name), built, types, Path(temporary))
298
431
  plan = plan_project(project, home, built=built, reset_overrides=reset_overrides,
299
- retire_skills=retire_skills, retire_plugins=retire_plugins, retire_only=retire_only)
300
- if plan["conflicts"] and not replace:
432
+ retire_skills=retire_skills, retire_plugins=retire_plugins, retire_only=retire_only,
433
+ only=types, package_tree=tree)
434
+ blocking = [item for item in plan["conflicts"]
435
+ if not (replace or (replace_mcp and item.startswith("mcp ")) or
436
+ (replace_skills and item.startswith("skill ")))]
437
+ if blocking:
301
438
  raise core.AgentPackError("Claude client already has different content not installed by this package "
302
- "(use --replace; replaced items go to recovery): " + "; ".join(plan["conflicts"]))
439
+ "(use --replace, or --replace-mcp / --replace-skills for one type; "
440
+ "replaced items go to recovery): " + "; ".join(blocking))
303
441
  result: dict[str, Any] = {
304
442
  "ok": True, "applied": False, "client": "claude", "package": name,
305
443
  "operations": _public(plan["operations"]), "overrides": plan["overrides"],
306
444
  "excluded": plan["excluded"], "native": plan["native"],
307
445
  "notes": ["restart Claude Code to load changed Skills and MCP servers"],
308
446
  }
447
+ summary = _conflict_summary(plan["conflicts"])
448
+ if summary:
449
+ result["conflicts"] = summary
450
+ result["warnings"] = _global_warnings(home, summary)
451
+ if types != frozenset(SYNC_TYPES):
452
+ result["only"] = sorted(types)
453
+ if plan["residuals"]:
454
+ result["residuals"] = plan["residuals"]
309
455
  if plan["legacy_root"]:
310
456
  result["migrated_from"] = plan["legacy_root"]
311
457
  changes = [item for item in plan["operations"] if not item["action"].startswith("keep-")]
312
458
  if not apply or not changes:
313
459
  result["applied"] = apply and not changes
314
460
  return result
315
- result["recovery"] = str(_apply(plan, built, home, recovery_root))
461
+ result["recovery"] = str(_apply(plan, tree, home, recovery_root))
316
462
  result["applied"] = True
317
463
  return result
318
464
 
@@ -373,7 +519,8 @@ def _apply(plan: dict[str, Any], built: Path, home: Path, recovery_root: Path |
373
519
  link(Path(item["to"]), package / "skills" / item_name)
374
520
  if action == "archive-plugin":
375
521
  archive(Path(item["from"]), "plugins", item_name)
376
- servers = config.setdefault("mcpServers", {})
522
+ # A sync that does not include mcp never opens ~/.claude.json for writing (#68).
523
+ servers = config.setdefault("mcpServers", {}) if "mcp" in plan["only"] else {}
377
524
  replaced: dict[str, Any] = {}
378
525
  mcp_state: dict[str, str] = {}
379
526
  for item in plan["operations"]:
@@ -393,9 +540,14 @@ def _apply(plan: dict[str, Any], built: Path, home: Path, recovery_root: Path |
393
540
  core._write_json_atomic(config_path, config, mode=mode)
394
541
  config_written = True
395
542
  if not plan["retire_only"]:
543
+ # A partial sync records only the types it handled; the others keep their recorded ownership.
544
+ before = _read_state(home, name)
545
+ only = set(plan["only"])
396
546
  core._write_json_atomic(state_path(home, name), {
397
- "schema_version": STATE_SCHEMA, "package": name, "skills": plan["desired_skills"],
398
- "mcps": mcp_state, "updated_at": stamp}, mode=0o600)
547
+ "schema_version": STATE_SCHEMA, "package": name,
548
+ "skills": plan["desired_skills"] if "skills" in only else before.get("skills", []),
549
+ "mcps": mcp_state if "mcp" in only else before.get("mcps", {}),
550
+ "updated_at": stamp}, mode=0o600)
399
551
  except Exception as exc:
400
552
  if config_written:
401
553
  core._write_json_atomic(config_path, original_config, mode=0o600)
@@ -419,7 +571,7 @@ def drift(project: Path, home: Path | None = None) -> dict[str, Any]:
419
571
  with tempfile.TemporaryDirectory(prefix="agent-pack-claude-") as temporary:
420
572
  layout = core.load_project_layout(project)
421
573
  name = core._package_name(layout.root)
422
- built = core._build_package(core.inventory_project(layout.root), name, Path(temporary), "claude")
574
+ built = core._build_package(core.inventory_project(layout.root), name, Path(temporary), "claude", home)
423
575
  plan = plan_project(project, home, built=built)
424
576
  report: dict[str, Any] = {"client": "claude", "package": name, "missing": [], "different": [],
425
577
  "overrides": plan["overrides"], "stale": [], "native": plan["native"],