fix(ptc): teach only the tool surface a scope publishes

docs/CHANGELOG.md

@@ -7,6 +7,8 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+- `batchingGuidance` no longer teaches `ops_load_sdk` in a scope that does not publish it. The guidance text and the `bypass` notice follow the published surface: with `dynamicTools: false` the load step and its table row are replaced by a direct-call section listing the published APIs, and a scope that publishes nothing says so. Every line of the notice names only what the scope can reach: a pool that cannot load `ops_edit_file` is no longer told to load it, and a resident name that is not a file API (such as the shell) is never offered as the way to do file work. A read-only session drops the mutating APIs from that list too. Previously every loader-less session spent a round trip calling `tools.ops_load_sdk` and failed with "is not a function".
+- `batchingGuidance` 不再在不发布加载器的作用域里教模型调用 `ops_load_sdk`：引导文本与 `bypass` 提醒改为跟随实际发布面，`dynamicTools: false` 时"先加载再调用"一步及其表格行被替换为列出现有 API 的直调一节，一个都不发布时明确说明。提醒里只点名该作用域真正可达的 API：可加载池里没有的（如 `ops_edit_file`）不再被告知去加载，常驻集合里的非文件 API（如 shell）也不会被当作做文件工作的手段；只读策略下还会去掉会改文件的 API（教学文本本身仍只在无加载器时替换，窄池不会改写随包的轨迹示例）。此前每个无加载器的会话都会白花一次往返并报 "is not a function"。
 - Native tool construction and the publication refusal queue no longer attach listeners or lifetime effects to the composition root. The evidence observer and result admission subscribe on the caller's context with global dispatch, and the refusal queue falls back to the caller lifetime when the root refuses an effect. dsh-tui 0.20 refuses `root.events.on` and `root.effect` from a plugin activation, and the native-tools row is one, so every `dsh-tui --resume` aborted with "cannot resume session" before the agent mounted.
 - 原生工具构造与发布拒绝队列不再向组合根挂监听或生命周期 effect：证据观察者与 result admission 改为在调用方上下文订阅并声明 global 分发，拒绝队列在 root 拒绝 effect 时回落到调用方生命周期。dsh-tui 0.20 会拒绝插件激活期内的 `root.events.on` 与 `root.effect`，而原生工具行正是插件激活，导致每次 `dsh-tui --resume` 都在 agent 挂载前报 "cannot resume session"。
 - The Bash tool description now states the parse contract of `stdout`/`stderr` where the model reads it: `text` may be a partial fragment, `truncated` marks one that must not be parsed as complete structured output, and `spillPath` is optional and not a completeness guarantee. The typed output schema is unchanged: repeating the contract there would cost every PTC request without saying anything the tool text does not. Command semantics, exit codes, result values, limits, spill files, permissions and rendering are unchanged.

docs/configuration-reference.md

@@ -92,7 +92,8 @@ external English Markdown file:
 - **Once at session start**: one plugin-context message joins the session's first accepted non-empty
   user-message batch (step-tail, source `dsh-ops:step-tail` / `batching-guidance`). It enters logged history,
   so the model's first request already sees the whole procedure: the first-line `// plan:` comment, the
-  dependency split, the load-before-call step and four copyable trajectories.
+  dependency split, the load-before-call step (only while dynamic loading publishes the loader) and four
+  copyable trajectories.
 - **On a thin program**: when a **root** `run_code` program breaks one of three latched categories, a short
   notice is appended to that call's own result as `additionalContexts`. The tool result keeps its value, its
   content and its existing contexts; the program is never blocked or rewritten.
@@ -109,6 +110,15 @@ external English Markdown file:
 - Everything is plugin-context history and the tool schema is untouched, so the system prompt and its cache
   survive. The lesson counts as spent only once it appears as a durable `user/message`; a batch withdrawn
   before admission (cancellation, rejection) leaves the next accepted batch free to teach it again.
+- The text follows the published surface. While dynamic loading publishes `ops_load_sdk`, the lesson ships
+  byte for byte, load step included. With `dynamicTools: false` the scope publishes no loader, so that step and
+  its table row are replaced by a direct-call section that lists the APIs this scope actually publishes; a
+  scope that publishes nothing says so and points at the official tools. The program-shape notices carry the
+  same surface, so `bypass` names neither a loader nor an API the scope cannot reach: its file-work line lists
+  only the file APIs that are loadable (or resident) here, and a shell tool that bypassed them is never offered
+  as the replacement. Two limits are deliberate: the shipped lesson itself is substituted only when the loader is
+  absent (a narrow pool narrows the notices, not the trajectories), and the lists follow the configured pool and the
+  read-only policy without the per-agent ownership narrowing.
 
 `batchingTelemetry` (same row, YAML-only, default `false`) emits one structured log line per delivered
 notice, for example `dsh-ops batching: turn=3 category=plan plan=1 bypass=0 shape=2 total=3`. It is

docs/配置参考.md

@@ -65,7 +65,7 @@ OPS 沿用单行插件页：bundle 只插入一个 `dsh-ops` 行。内置预设
 
 - **会话首轮一次**：在会话第一个被接受的非空用户消息批次里追加一条插件上下文（step-tail，来源
   `dsh-ops:step-tail` / `batching-guidance`），它进入会话历史，模型第一条请求即可看到完整范式：首行
-  `// plan:` 指令、按依赖拆分、先加载再调用，以及四条可照抄的轨迹。
+  `// plan:` 指令、按依赖拆分、先加载再调用（仅动态加载发布加载器时），以及四条可照抄的轨迹。
 - **薄程序触发**：**根** `run_code` 程序命中三类锁中的一类时，在该次调用的结果上以 `additionalContexts`
   追加一条短提醒。工具结果的值、正文与既有上下文都不变，程序既不阻断也不改写。
 - 三类分别是 `bypass`（用 shell 或 `node:fs` 做文件工作）、`plan`（第一物理行没有 `// plan:`）与 `shape`
@@ -77,6 +77,12 @@ OPS 沿用单行插件页：bundle 只插入一个 `dsh-ops` 行。内置预设
   提醒文案会说明这一点，不宣称实测的 dispatch 数；被取消或从未派发的调用不参与分析。
 - 全部都是插件上下文历史，tool schema 不变，系统提示词与其缓存因此不受影响。教学只有在真正出现持久
   `user/message` 时才算兑现；因取消或拒绝而撤回的批次不会消耗它，下一个被接受的批次仍会教学。
+- 文案跟随实际发布面。动态加载发布 `ops_load_sdk` 时，教学文本逐字节照发，含"先加载再调用"这一步；`dynamicTools:
+  false` 时该作用域没有加载器，这一步与其表格行会被替换成"直接调用"一节，并列出本作用域实际发布的 API；一个
+  OPS API 都不发布时则明确说明并指向官方工具。程序形状提醒同样带这一信息，`bypass` 既不指向不可达的加载器，
+  也不点名本作用域拿不到的 API：文件工作那句只列可加载（或常驻）中真实存在的文件类 API，shell 这类绕过的工具
+  不会被当作替代手段。两处是刻意取舍：随包教学文本本身只在无加载器时替换（窄池只收窄提醒，不改写轨迹
+  示例）；列表来自配置池与只读策略，不含按 agent 的归属收窄。
 
 `batchingTelemetry`（同一行、YAML-only、默认 `false`）每投递一条提醒打印一行结构化日志，例如
 `dsh-ops batching: turn=3 category=plan plan=1 bypass=0 shape=2 total=3`。它只做观测：不产生上下文、