docs: explain owned Bash restrictions and host integration failures

docs/CHANGELOG.md

@@ -7,6 +7,9 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+- Document the owned Bash restriction boundary and publication switch (#380),
+  provider tool-change error ownership (#367), and scoped discovery troubleshooting (#346).
+- 说明 Bash 自有工具的掩码边界与发布开关、提供商工具变更错误的职责边界及 discovery 作用域排查方法。
 - Add macOS Intel (`darwin-x64`) as a first-class native target on macOS 13+: accept it in the resolver and profile commands, declare it in every component row, ship its Mach-O worker with a receipt, and add a non-blocking `macos-15-intel` CI leg plus the fourth release artifact. The Intel leg measured 318 s, so it follows the >300 s non-blocking rule. macOS 12 is not part of this support: its kernel lacks `CLONE_ACL`, so the write path fails closed; that fallback is a separate follow-up. See [macOS](macos.md).
 - 将 macOS Intel（`darwin-x64`）作为 macOS 13+ 的一等原生目标：解析器与 profile 命令接受它，所有组件行声明它，发布其 Mach-O worker 与收据，并新增非阻塞的 `macos-15-intel` CI leg 与第四个发布 artifact。Intel leg 实测 318 秒，因此按 >300 秒规则作为非阻塞信号。macOS 12 不在本次支持范围内：其内核缺少 `CLONE_ACL`，写路径会 fail closed；该回退是独立后续项。说明见 [macOS](macos.zh.md)。
 - Declare DSH 0.2.0-rc.2 and 0.2.1-rc.2 consistently in engines/peers, export every

docs/host-integration.md

@@ -0,0 +1,102 @@
+# Host integration troubleshooting
+
+English | [中文](宿主集成.md)
+
+These checks separate plugin configuration from host presentation and provider
+transport failures. They do not establish that an unobserved Desktop freeze or
+an old conversation has been repaired.
+
+## A whitelist does not hide `ops_bash` (#380)
+
+In the pinned DSH tools API, `tools.restrict()` masks inherited registrations.
+An agent's own registrations are resolved separately. OPS publishes Bash in the
+agent's scope so its definition follows that session's authority and services;
+an inherited-tool whitelist therefore cannot be assumed to remove `ops_bash`.
+The fact that the same whitelist hides a globally registered file tool does not
+prove it also hides the session's shell. A read-only sandbox is also a filesystem
+permission mode, not a promise that every command tool is absent.
+
+To stop OPS Bash publication, set `publishBashTool: false` in its owning shell
+row. Merge this setting into the existing config, preserving other keys:
+
+```yaml
+- id: dsh-ops-shell
+  name: dsh-ops/shell
+  config:
+    publishBashTool: false
+```
+
+Check every `dsh-ops/shell` row in the effective configuration: another enabled
+row can still publish its own tool. Apply the change through the host settings
+or profile lifecycle, then verify a new session's tool list. This switch controls
+OPS Bash; it does not disable independently installed command tools.
+
+Per-preset command denial requires a host execution policy that covers owned
+tools, or a verified scoped mounting arrangement. Merely moving a shell row into
+a preset is not established as an isolation guarantee: the component also
+enumerates already live agents when mounted. Before relying on such an arrangement,
+verify both allowed and disallowed presets, existing and newly created sessions,
+and actual invocation rejection. OPS does not rewrite the shared tool registry
+to make inherited restrictions act on owned tools.
+
+## A provider rejects `tool_addition` in an old conversation (#367)
+
+OPS publishes tool definitions through the host registry. DSH records changes
+to the available tool set and serializes provider messages; OPS does not construct
+`tool_addition` blocks or choose their wire-message roles. The reported
+`tool_addition blocks can only be in system messages` error is therefore a
+host/provider serialization boundary, even when an OPS discovery change triggers it.
+
+For a bounded diagnostic, choose the intended configuration before creating a
+fresh session, then keep the tool set stable during that run. Configure any
+`alwaysLoaded` discovery capabilities before session creation and avoid changing
+selections or component settings mid-conversation. Disabling discovery removes
+that progressive-publication trigger but also removes access to capabilities
+that were available only through discovery. This does not repair retained history
+or guarantee compatibility with every provider.
+
+If the rejection persists, retain the exact host/plugin versions, provider/model,
+request ID, added/removed tool names, and the smallest redacted message-role
+fragment that demonstrates the invalid block. The host/provider adapter needs
+that evidence; changing OPS tool names or editing historical message roles is
+not a plugin-side serializer fix. [Issue #367](https://github.com/T-Auto/dsh-ops/issues/367)
+tracks the reported trigger.
+
+## `ops_discover_tools` is missing (#346)
+
+First inspect the profile actually used by the application, using its own CLI.
+Desktop uses its bundled CLI; the ordinary CLI does not manage the reserved
+Desktop profile. For a non-Desktop test profile:
+
+```console
+dsh plugin --profile ops-test add dsh-ops@latest
+dsh --profile ops-test --dump-config
+dsh --profile ops-test --dump-config-schema
+```
+
+Replace `@latest` with the intended version or packed checkout when testing an
+unpublished fix. Put `--profile` before `add` and package-manager arguments. The
+effective configuration should contain an enabled `dsh-ops-discovery` row named
+`dsh-ops/discovery`, with `enabled: true`. Inspect saved overrides and duplicate
+rows before adding another row. A stale profile missing discovery is a different
+case from an enabled row whose publication stalls.
+
+Presentation matters: ordinary Native scopes use `ops_discover_tools`; PTC scopes
+use the PTC SDK loader under the host's `run_code` presentation. Check the scoped
+assembled tools and presentation, not just a global registry or a prompt section
+name. An empty discovery section alone does not identify the cause.
+
+Host support declarations and component resource exports are addressed in
+[PR #395](https://github.com/T-Auto/dsh-ops/pull/395), with explicit 0.2.0-rc.2 and
+0.2.1-rc.2 coverage. The text-only PTC hook adaptation in
+[PR #390](https://github.com/T-Auto/dsh-ops/pull/390) is not full 0.2.1-rc.3 support.
+[PR #383](https://github.com/T-Auto/dsh-ops/pull/383) and #390 address unnecessary
+session work and append-time Bash publication. Check whether the installed version
+actually contains these changes before attributing its behavior to them.
+
+The original #346 report also describes an enabled row and a stalled publication
+chain. The profile checks above do not prove that failure fixed. If the row is
+enabled and the expected scoped tool remains absent, capture a minimal profile,
+exact versions, Native/PTC mode, affected scoped schemas, and a timed lifecycle
+trace showing the pending publication. Restart/new-session results are useful
+comparisons, not proof that an indefinite hot-mount stall cannot recur.

docs/usage.md

@@ -143,6 +143,9 @@ the resulting warning fails the gate.
 
 ## Update
 
+For inherited whitelist limits, missing discovery rows and provider tool-change
+errors, see [host integration troubleshooting](host-integration.md).
+
 Repeat the same `npx --yes dsh-ops@latest install --profile ...` command, or use the official CLI's `add dsh-ops@latest`. Reload as requested by the application; restart it when replacing already-loaded code.
 
 ---

docs/使用指南.md

@@ -124,6 +124,8 @@ CI 清单校验使用同一个公开宿主 patch 合成器，将跳过 override
 
 ## 更新
 
+继承白名单限制、缺少 discovery 行及提供商工具变更错误，见[宿主集成排查](宿主集成.md)。
+
 重新运行相同的 `npx --yes dsh-ops@latest install --profile ...`，或用官方 CLI `add dsh-ops@latest`。按应用提示重载；替换已加载代码时重启应用。
 
 ---

docs/宿主集成.md

@@ -0,0 +1,80 @@
+# 宿主集成排查
+
+[English](host-integration.md) | 中文
+
+以下检查区分插件配置、宿主展示与提供商传输问题，不代表已修复未复现的 Desktop 卡死，
+也不代表已修复旧会话的历史记录。
+
+## 白名单无法隐藏 `ops_bash`（#380）
+
+固定版本的 DSH tools API 中，`tools.restrict()` 只遮蔽继承的注册项，agent 自有注册项
+单独解析。OPS 在 agent 作用域发布 Bash，使定义跟随该会话的权限与服务。因此不能认为
+继承工具白名单也会移除 `ops_bash`。同一白名单能隐藏全局注册的文件工具，并不能证明它
+能隐藏会话自身的 shell。只读沙箱也是文件系统权限模式，不承诺命令工具全部不可见。
+
+要停止 OPS Bash 发布，在拥有它的 shell 行设置 `publishBashTool: false`。
+把该字段合并进已有配置，保留其他键：
+
+```yaml
+- id: dsh-ops-shell
+  name: dsh-ops/shell
+  config:
+    publishBashTool: false
+```
+
+检查有效配置中的所有 `dsh-ops/shell` 行：另一条启用的行仍可能发布自己的工具。
+通过宿主设置或 profile 生命周期应用变更，再验证新会话的工具清单。该开关只控制 OPS
+Bash，不会禁用其他独立安装的命令工具。
+
+按 preset 禁止命令，需要能覆盖自有工具的宿主执行策略，或经过验证的作用域挂载方案。
+仅把 shell 行移入某个 preset，尚不能作为隔离保证：组件挂载时也会枚举已存活的 agent。
+依赖此方案前，应验证允许与禁止的 preset、已有与新建会话，以及实际调用被拒绝的结果。
+OPS 不会改写共享工具注册表，让继承掩码强行作用于自有工具。
+
+## 提供商拒绝旧会话中的 `tool_addition`（#367）
+
+OPS 通过宿主注册表发布工具定义；DSH 记录工具集变化并序列化提供商消息。OPS 不构造
+`tool_addition` 块，也不选择它在线路消息中的角色。因此，报告中的
+`tool_addition blocks can only be in system messages` 属于宿主/提供商序列化边界，
+即使触发条件是一次 OPS discovery 工具变化。
+
+进行有限诊断时，先确定配置，再新建会话，并在该次运行中保持工具集稳定。需要的
+`alwaysLoaded` discovery 能力应在创建会话前配置，运行中避免修改选择或组件设置。
+禁用 discovery 可以去掉该渐进发布触发器，但也会失去只能通过 discovery 获得的能力。
+这不会修复保留的历史，也不保证适配所有提供商。
+
+若仍被拒绝，保留准确的宿主/插件版本、提供商/模型、request ID、新增/移除工具名，
+以及能展示错误块的最小脱敏消息角色片段。宿主/提供商适配器需要这些证据；改 OPS 工具名
+或修改历史消息角色，不是插件侧序列化修复。
+[议题 #367](https://github.com/T-Auto/dsh-ops/issues/367) 记录了该触发场景。
+
+## 缺少 `ops_discover_tools`（#346）
+
+先用应用自己的 CLI 检查它实际使用的 profile。Desktop 使用自带 CLI；普通 CLI 不能管理
+保留的 Desktop profile。非 Desktop 测试 profile 的示例：
+
+```console
+dsh plugin --profile ops-test add dsh-ops@latest
+dsh --profile ops-test --dump-config
+dsh --profile ops-test --dump-config-schema
+```
+
+验证未发布修复时，将 `@latest` 换成目标版本或本地打包产物。把 `--profile` 放在 `add`
+及包管理器参数之前。有效配置中应有启用的 `dsh-ops-discovery` 行，名称为
+`dsh-ops/discovery`，且 `enabled: true`。先检查已保存的 override 与重复行，再决定是否
+补行。旧 profile 缺少 discovery，与启用的行发生发布停滞，是不同问题。
+
+展示模式也影响工具：普通 Native 作用域使用 `ops_discover_tools`；PTC 作用域通过宿主
+`run_code` 展示使用 PTC SDK loader。应检查具体作用域的装配工具和展示模式，不只查看
+全局注册表或提示词段名称。discovery 段为空本身不足以确定原因。
+
+[PR #395](https://github.com/T-Auto/dsh-ops/pull/395) 处理宿主兼容声明与组件资源导出，
+明确覆盖 0.2.0-rc.2 和 0.2.1-rc.2。
+[PR #390](https://github.com/T-Auto/dsh-ops/pull/390) 的纯文本 PTC hook 适配不代表完整
+支持 0.2.1-rc.3。[PR #383](https://github.com/T-Auto/dsh-ops/pull/383) 与 #390 处理会话
+重复工作及 append 期间 Bash 发布问题。判断行为前，先确认安装版本确实包含这些改动。
+
+#346 原始报告也包含“行已启用，但发布链停滞”的情况，上述 profile 检查不能证明它已被
+修复。若行已启用而预期的作用域工具仍缺失，应提供最小 profile、准确版本、Native/PTC
+模式、受影响作用域的 schemas，以及带时间信息的生命周期轨迹以定位尚未完成的发布。
+重启/新建会话结果可用于比较，但不能证明无限热挂载停滞不会再次发生。