dsh-root-planner-preset 1.0.2 → 1.0.4

package/.github/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for looking. This repository is meant to be maintained by more than its
+author — the license is [MIT](../LICENSE), and issues and pull requests are open
+to anyone.
+## The one thing to know first
+
+**`cordis.patch.yml` is generated. Do not edit it by hand.**
+
+It is produced from `persona.txt` by `build-patch.mjs`, and it has to be indented
+into a YAML block scalar exactly — a single mis-indented line silently truncates
+the ~6 KB persona, which is very hard to spot in review and easy to introduce by
+hand. That is the whole reason the generator exists.
+
+So to change what the agent is told:
+
+```sh
+$EDITOR persona.txt
+node build-patch.mjs      # regenerates cordis.patch.yml
+node verify-patch.mjs     # must print ALL CHECKS PASSED
+```
+
+Commit **both** files. CI re-runs the generator and fails if the committed patch
+does not match `persona.txt` byte for byte, so forgetting the second command is
+caught for you.
+
+## Setup
+
+The bundle itself ships no dependencies. The repository's scripts need one YAML
+parser, which `lib-yaml.mjs` resolves from your own DSH installation — or from a
+local install:
+
+```sh
+npm ci        # installs js-yaml, the only devDependency
+```
+
+## What the checks mean
+
+`node verify-patch.mjs` asserts, among other things:
+
+- the patch parses as loader YAML (including the `!!js` scalars, read as opaque);
+- the persona parsed out of the patch is **byte-identical** to `persona.txt`;
+- both delegation tools publish `subagent` / `subagent_fork`;
+- both `toolFilter.allow` masks exclude every mutation entry point
+  (`write`, `edit`, `ops_replace`, `ops_bash`, `pwsh`) and name **only tools that
+  exist** — a name that is not a registered global tool makes
+  `tools.restrict()` throw the first time a subagent is created.
+
+That last point is the most likely thing to need changing on your machine: the
+mask was written against the author's profile. If your profile registers a
+different set of global tools, the mask is what has to adapt — edit the list near
+the bottom of `verify-patch.mjs` in the same commit.
+
+`node verify-depth-override.mjs` checks the delegation depth override. Depth is a
+**Host setting, not part of this bundle**, so on a machine that never set it the
+script prints `SKIP` and explains why. That is a pass, not a failure.
+
+## Most valuable contributions, in order
+
+1. **Bug reports with real error text**, plus your DSH version and which global
+   tools your profile registers. The `Not verified` section of the
+   [README](../README.md) names exactly where this matters: no subagent has been
+   spawned under this preset in the author's environment to date.
+2. **Mask fixes for other environments** — see above.
+3. **Persona improvements** — the text itself, when you have an observed failure
+   it would have prevented.
+4. **Documentation and translations** — [README.zh.md](../README.zh.md) and
+   [INSTALL.md](../INSTALL.md) especially.
+
+## Ground rules
+
+- **One concern per pull request.** A persona change and a mask change are two
+  pull requests unless one requires the other.
+- Say which preset you tested with, and on which platform.
+- Do not weaken the read-only guarantee. `write`, `edit`, `ops_replace`,
+  `ops_bash` and `pwsh` must stay out of the child mask; that property is the
+  point of the preset, so a change that removes it will be declined.
+- Keep `main` linear — the branch protection refuses merge commits, so rebase
+  rather than merge.
+
+## How `main` is protected
+
+`main` requires the `verify` status check (strict: the branch must be up to date),
+refuses force pushes and deletions, requires linear history, and requires
+conversations to be resolved. The repository owner can bypass these for a direct
+push in an emergency; **collaborators cannot** — send a pull request and let CI
+run.
+
+If you are added as a collaborator and want to be able to merge your own pull
+requests without waiting for the owner, say so: review requirements are off
+deliberately, because a single-maintainer repository that requires an approval it
+cannot get would deadlock.

package/.github/workflows/verify.yml

@@ -0,0 +1,51 @@
+# Verifies the bundle on every push and pull request.
+#
+# Two failure modes this exists to catch, both of which are silent locally:
+#
+#  1. `cordis.patch.yml` is generated from `persona.txt`. Someone edits the
+#     generated file by hand (or edits persona.txt and forgets to regenerate), and
+#     the persona the preset actually ships no longer matches the source. The
+#     generator is deterministic, so re-running it and diffing the result catches
+#     exactly that drift.
+#  2. A change to the child tool mask names a tool that is not a registered global
+#     tool. `tools.restrict()` throws on an unknown name at child-creation time, so
+#     this only surfaces the first time a subagent is actually spawned — never in a
+#     local syntax check.
+#
+# The bundle itself ships no dependencies; `js-yaml` is a devDependency of this
+# repository only, and `lib-yaml.mjs` picks it up from the checkout.
+
+name: verify
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install the local YAML parser
+        run: npm ci --ignore-scripts
+
+      - name: The committed patch matches persona.txt
+        run: |
+          node build-patch.mjs
+          if ! git diff --exit-code -- cordis.patch.yml; then
+            echo "::error file=cordis.patch.yml::cordis.patch.yml is out of date. Run 'node build-patch.mjs' and commit the result instead of editing it by hand."
+            exit 1
+          fi
+
+      - name: Patch structure, persona byte-identity and the child tool mask
+        run: node verify-patch.mjs

package/INSTALL.md

@@ -107,7 +107,7 @@ git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
 |---|---|---|
 | 预设列表里**没有 Root Planner** | bundle 没装上，或预设行激活失败（会带诊断留在名册上） | 看 DSH 的插件/加载诊断；多半是第 1 条前置不满足——本包的补丁引用了随包预设里不存在的工具行 |
 | DSH **启动失败**（进程直接退出） | DSH 启动是全有全无，一个插件加载失败整个进程就退出 | 用插件市场的「**调整插件**」恢复界面：DSH 点名的插件会标红并默认取消勾选，勾好再启动。找不到该界面时，手工编辑 profile 的 `cordis.patch.yml` 把对应行设为 `disabled: true` |
-| 子代理创建失败，报 **`tools.restrict() names unknown global tool …`** | 白名单里有你的环境**没注册**的工具名 | 按报错里点出的名字，从 `cordis.patch.yml` 两个 `toolFilter.allow` 里删掉该行，重装或重开会话 |
+| 子代理创建失败，报 **`tools.restrict() names unknown global tool …`** | 白名单里有**不是全局工具**的名字。注意有两种情况：①你的环境根本没注册该工具；②它是**agent 作用域**工具（如 `subagent`，它注册在每个被组合 Agent 自身的作用域里），而 `toolFilter` **只接受全局工具名** | 报错里会列出该环境全部的全局工具名，照着它删掉白名单里那几个不存在的名字。白名单在 `cordis.patch.yml` 的两个 `toolFilter.allow` 处（或在 `child-tools.mjs` 里改后重跑生成器），改完必须重开会话 |
 | 委派立刻返回**深度错误** | `maxDepth` 没设或设得太小 | 见第三节，设为 `2` |
 | 子代理**什么都不能读** | 白名单过窄（比如你删过头了） | 至少保留 `read`、`glob`、`grep`、`ops_inspect_local_file`、`ops_glob`、`ops_grep` |
 | 子代理**还是能改文件** | 白名单被改坏了 | 确认 `cordis.patch.yml` 里两处 `toolFilter.allow` 都**不含** `write`、`edit`、`ops_replace`、`ops_bash`、`pwsh`；改完必须重开会话 |

package/README.md

@@ -18,21 +18,40 @@ This preset turns both of those into structural constraints rather than good int
 |---|---|---|
 | Subagents **cannot** create, modify or delete files | A `toolFilter.allow` list on both delegation tools, without `write`, `edit`, `ops_replace` | **Structural**: an absent tool cannot be called |
 | Subagents **have no shell** to work around it | The same list, without `ops_bash`, `pwsh` | **Structural** |
-| Work cannot be passed down without limit | The runtime delegation depth limit (`subagent.maxDepth`) | **Structural**: past the cap it throws `SubagentDepthError` |
+| Delegation depth is bounded by configuration | The runtime depth cap (`subagent.maxDepth`, a Host setting) | **Structural**: past the cap it throws `SubagentDepthError` |
 | The root agent owns every mutation | Persona rules (the mask applies to children only) | Prompt-level |
-| The root agent delegates reading by default | Persona rules | Prompt-level |
+| A heavy task is decomposed rather than ground through | Persona rule 2 | Prompt-level |
 
-The mask is an **allow** list, not a deny list: a tool added by a future plugin is invisible to subagents until it is added here.
+The mask is an **allow** list, not a deny list: a tool added by a future plugin is invisible to subagents until it is added here — **with one exception, and it is what makes recursion work.**
 
 ## How it works
 
 ```
-root agent (depth 0)        <- the only one with write / edit / shell
-├── subagent (depth 1)      <- read-only; may delegate one more level
-│   └── grandchild (depth 2) <- read-only; a leaf
-└── subagent (depth 1)
+root agent  ──delegates──▶  subagent  ──delegates──▶  … until maxDepth
+   │                            │
+   └── the only one with write / edit / shell; every level stays read-only
 ```
 
+Two mechanisms decide how deep the tree goes, and they pull in the same direction:
+
+- **The mask** strips every mutation entry point from *every* subagent, at *every*
+  level — the guarantee does not weaken with depth.
+- **The depth cap** (`subagent.maxDepth`, a Host setting you control) decides how
+  many levels exist. `2` means root → child → grandchild; raise it and the tree
+  deepens, set it to `1` and children become leaves.
+
+A `toolFilter` is a mask of **global** tools, and `subagent` is not one: with
+`modelSelectionSettings: true` it is mounted inside each composed Agent's own
+scope, so a mask can never name it. That is why it is absent from
+`child-tools.mjs` — **not** because children lack it. Scoped registrations stay
+visible through a restriction, and every child inherits this preset, so each level
+gets its own `subagent` and can delegate onward until the depth cap stops it.
+
+An earlier version of this bundle did list `subagent` in the mask, and **every
+subagent creation failed** with
+`tools.restrict() names unknown global tool "subagent"` — the mask rejecting a
+name it could never legally contain, not the tool being missing.
+
 - **Root agent**: plans first (goal, success criteria, constraints, ordered task list), delegates reading, searching and locating by default, and reads directly only for one known file, a short targeted range, or to check a claim a subagent made.
 - **Subagent**: reads, locates and summarizes. On finding that a file **needs changing** it does not act; it reports the exact change — target path, location (`file:line`), current content, proposed replacement, and why.
 - **The root agent decides** on that proposal and then makes the change itself.
@@ -81,13 +100,15 @@ Then **start a new session** and pick **Root Planner** in the preset selector. F
 
 ## Verified / not verified
 
-**Verified**: the patch parses as loader YAML; the parsed persona is **byte-identical** to `persona.txt`; both delegation masks exclude every mutation entry point and name only tools this profile actually registers; a clean checkout passes verification (`.gitattributes` pins LF, without which a Windows clone breaks the byte-identity check); the depth override reached the composed profile.
+**Verified**: the patch parses as loader YAML; the parsed persona is **byte-identical** to `persona.txt`; both delegation masks exclude every mutation entry point and name only tools the runtime reports as global; a clean checkout passes verification (`.gitattributes` pins LF, without which a Windows clone breaks the byte-identity check); the depth override reached the composed profile.
+
+**Fixed after a real failure**: a subagent spawn on a live `root-planner` session failed with `tools.restrict() names unknown global tool "subagent"`. The cause was a design error in this bundle, not a misconfiguration — `subagent` is registered inside each composed Agent's own scope, and a `toolFilter` takes global names only, so the mask was naming something it could never contain. The mask no longer names it, `verify-patch.mjs` asserts its absence by intent, and the mask is defined once in `child-tools.mjs` so the generator and the verifier cannot drift apart.
 
-**Not verified**: **no subagent has actually been spawned under the `root-planner` preset yet.** The tool names in the mask were cross-checked against the author's environment, not exercised at runtime. If your environment lacks one of those global tool names, child creation fails with `tools.restrict() names unknown global tool …`. See the troubleshooting section of [INSTALL.md](INSTALL.md).
+**Still not verified**: **no subagent has been spawned successfully under this preset yet.** Recursion is expected to work for the reason given above — the child inherits the preset and therefore its own scoped `subagent`, and a restriction does not hide scoped registrations — but that reasoning is exactly the kind that this bundle has already been wrong about once. Treat it as unconfirmed until someone reports a two-level delegation working.
 
 ## Contributing
 
-Issues and pull requests are welcome — this repository is meant to be maintained by more than its author. The license is [MIT](LICENSE), so forking, modifying and redistributing are all permitted.
+Issues and pull requests are welcome — this repository is meant to be maintained by more than its author. The license is [MIT](LICENSE), so forking, modifying and redistributing are all permitted. **[CONTRIBUTING.md](.github/CONTRIBUTING.md) has the workflow, the checks, and the ground rules** — read it before changing the persona.
 
 Useful contributions, roughly in order of value:
 

package/README.zh.md

@@ -18,21 +18,29 @@
 |---|---|---|
 | 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
 | 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
-| 任务不会被无限转派 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
+| 委派层数由配置决定 | 运行时深度上限（`subagent.maxDepth`，Host 设置） | **结构性**：超过上限直接抛 `SubagentDepthError` |
 | 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
-| 根 agent 默认委派阅读 | 人设规则 | 提示词级 |
+| 任务过重时拆分下发而非硬扛 | 人设规则 2 | 提示词级 |
 
-白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
+白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见——**但有一个例外，而正是它让递归得以成立**。
 
 ## 工作方式
 
 ```
-根 agent (depth 0)          ← 只有它有 write / edit / shell
-├── 子代理 (depth 1)        ← 只读；可以再派一层
-│   └── 孙代理 (depth 2)    ← 只读；叶子
-└── 子代理 (depth 1)
+根 agent  ──委派──▶  子代理  ──委派──▶  … 直到 maxDepth
+   │                      │
+   └── 只有它有 write / edit / shell；每一层都保持只读
 ```
 
+有两个机制决定树有多深，方向一致：
+
+- **白名单**剥掉**每一层**、**每一个**子代理的所有写入入口——这个保证不随深度衰减。
+- **深度上限**（`subagent.maxDepth`，由你控制的 Host 设置）决定有几层。`2` 就是根 → 子 → 孙；调大则更深，设成 `1` 则子代理变叶子。
+
+`toolFilter` 是**全局**工具的掩码，而 `subagent` 不是全局工具：因为 `modelSelectionSettings: true`，它被注册进每个被组合 Agent **自身的作用域**，掩码永远写不上它的名字。所以它不在 `child-tools.mjs` 里——**不是**因为子代理没有它。作用域注册**不受限制影响**，而每个子代理都继承本预设，于是每一层都拿到自己的 `subagent`，可以一直往下派到深度上限为止。
+
+本包早期版本确实把 `subagent` 写进了白名单，结果是**每一次子代理创建都失败**，报 `tools.restrict() names unknown global tool "subagent"`——那是白名单在拒绝一个它永远不可能合法包含的名字，不是工具缺失。
+
 - **根 agent**：先立计划（目标、成功判据、约束、任务清单），把阅读/搜索/定位默认派出去，自己只在「单个已知文件、一小段范围、或核实子代理的某个断言」时才亲自读。
 - **子代理**：只读、只定位、只总结。发现**需要改文件**时不动手，而是回报精确的改动方案——目标路径、位置（file:line）、当前内容、建议替换、理由。
 - **根 agent 收到方案后决策**，然后亲自落盘。
@@ -81,13 +89,15 @@ dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
 
 ## 已验证 / 未验证
 
-**已验证**：补丁可被 loader 解析；解析出的人设与 `persona.txt` **逐字节相同**；两个委派工具的白名单排除了所有写入入口、且只包含本机实际注册的工具名；干净检出后校验通过（`.gitattributes` 已钉死 LF，否则 Windows 克隆会破坏逐字节校验）；深度覆盖已落到合成配置。
+**已验证**：补丁可被 loader 解析；解析出的人设与 `persona.txt` **逐字节相同**；两个委派工具的白名单排除了所有写入入口、且只包含**运行时报告的全局工具**；干净检出后校验通过（`.gitattributes` 已钉死 LF，否则 Windows 克隆会破坏逐字节校验）；深度覆盖已落到合成配置。
+
+**因一次真实故障而修复**：在跑着 `root-planner` 的会话里创建子代理失败，报 `tools.restrict() names unknown global tool "subagent"`。根因是本包**设计上的错误**，不是配置错误——`subagent` 注册在每个被组合 Agent 自身的作用域里，而 `toolFilter` 只接受全局工具名，白名单写了一个它永远不可能合法包含的名字。现在白名单不再写它，`verify-patch.mjs` 会**按意图断言它必须缺席**，白名单也收敛到 `child-tools.mjs` 单一真源，生成器与校验脚本不可能再各说各话。
 
-**未验证**：**尚未在 `root-planner` 预设下真正派出过一个子代理。** 白名单里的工具名是按作者环境的实际工具清单交叉核对出来的，不是运行时实测。若你的环境缺少其中某个全局工具名，子代理创建会失败并报 `tools.restrict() names unknown global tool …`。详见 [INSTALL.md](INSTALL.md) 的故障排查。
+**仍未验证**：**还没有一次成功的子代理派出。** 递归按上面的理由**应当**可用——子代理继承预设、因此拥有自己的作用域 `subagent`，而限制不会隐藏作用域注册——但这个推理恰好就是本包已经错过一次的那类推理。在有人报告"两层委派成功"之前，请当作未确认。
 
 ## 参与维护
 
-**欢迎提 issue 和 PR——这个仓库本来就打算由作者之外的人一起维护。** 许可证是 [MIT](LICENSE)，fork、修改、再分发都是允许的。
+**欢迎提 issue 和 PR——这个仓库本来就打算由作者之外的人一起维护。** 许可证是 [MIT](LICENSE)，fork、修改、再分发都是允许的。**[CONTRIBUTING.md](.github/CONTRIBUTING.md) 写清了流程、校验项和底线要求**，改人设之前请先读它。
 
 按价值排序，有用的贡献大概是这样：
 

package/build-patch.mjs

@@ -10,6 +10,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHILD_TOOLS } from './child-tools.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -44,32 +45,10 @@ function allowList(names, keyDepth) {
 }
 
 /**
- * The child mask: the only global tools a subagent may call. Everything absent
- * is invisible to the child, including every mutation entry point.
+ * The child mask lives in `child-tools.mjs` so this generator and
+ * `verify-patch.mjs` cannot disagree about it. See that file for why `subagent`
+ * cannot appear in the list.
  */
-const CHILD_TOOLS = [
-  'read',
-  'glob',
-  'grep',
-  'ops_inspect_local_file',
-  'ops_glob',
-  'ops_grep',
-  'web_search',
-  'web_fetch',
-  'read_image',
-  'skill',
-  'todo_write',
-  'ask_user_question',
-  'get_goal',
-  'create_goal',
-  'update_goal',
-  'list_agents',
-  'send_message',
-  'interrupt_agent',
-  'subagent',
-  'subagent_fork',
-];
-
 const persona = readPersona();
 
 /** The delegation group is shared by both shapes of child, so the mask is declared once. */

package/child-tools.mjs

@@ -0,0 +1,62 @@
+/**
+ * The child tool mask — the single source of truth shared by the generator and
+ * the verifier, so the two cannot disagree about what a subagent may call.
+ *
+ * These are the only GLOBAL tools a subagent may call. Everything absent is
+ * invisible to the child, including every mutation entry point.
+ *
+ * `subagent` is deliberately NOT here, and cannot be — but that does NOT mean a
+ * subagent lacks it. Two separate facts:
+ *
+ *  1. With `modelSelectionSettings: true` the tool is mounted inside each composed
+ *     Agent's own scope (`dsh-tool-subagent` registers it through
+ *     `installScoped`), and `tools.restrict()` takes a mask of *global* tools
+ *     only. It throws on a scope-local name exactly as it throws on an unknown
+ *     one, which is how this bundle broke: every subagent creation failed with
+ *     `tools.restrict() names unknown global tool "subagent"`.
+ *  2. Restrictions only filter globals — "scoped registrations remain visible".
+ *     A child inherits this preset, so it gets its own scoped `subagent` and can
+ *     delegate onward until the runtime depth cap stops it.
+ *
+ * So the mask is not what makes a child a leaf; `subagent.maxDepth` is. Listing
+ * `subagent` here rejected a name the mask can never legally contain. Do not add
+ * it back; `verify-patch.mjs` asserts its absence on purpose.
+ *
+ * `subagent_fork` IS registered in the preset's own scope and is observable as a
+ * global, so it stays in the list.
+ */
+export const CHILD_TOOLS = [
+  'read',
+  'glob',
+  'grep',
+  'ops_inspect_local_file',
+  'ops_glob',
+  'ops_grep',
+  'web_search',
+  'web_fetch',
+  'read_image',
+  'skill',
+  'todo_write',
+  'ask_user_question',
+  'get_goal',
+  'create_goal',
+  'update_goal',
+  'list_agents',
+  'send_message',
+  'interrupt_agent',
+  'subagent_fork',
+];
+
+/**
+ * Tools that are agent-scoped rather than global, so a mask can never name them.
+ * Kept separate so the verifier can assert their absence by intent rather than
+ * by accident.
+ */
+export const SCOPE_LOCAL_TOOLS = ['subagent'];
+
+/**
+ * The mutation entry points this bundle promises a subagent cannot reach. The
+ * verifier asserts each one is absent; `ops_bash` and `bash` are included even
+ * when a profile registers neither, because their absence is the property.
+ */
+export const MUTATION_TOOLS = ['write', 'edit', 'ops_replace', 'ops_bash', 'pwsh', 'bash'];

package/cordis.patch.yml

@@ -42,13 +42,14 @@
                 ## Root agent rules
 
                 1. Plan first. Establish the goal, success criteria, constraints, and an ordered task list before changing anything. Revise the plan when evidence contradicts it.
-                2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
-                3. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
-                4. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
-                5. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).
-                6. You own every mutation. Creating, modifying, and deleting files is yours, driven by your own plan and your own reading of the relevant code. Never delegate it and never infer it from a summary alone.
-                7. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
-                8. Answer a subagent that reports a needed file change. Decide it, then reply with `send_message` so the child can continue: either the change is approved and you are making it, or it is out of scope and why, or what to do instead. An unanswered proposal leaves the child blocked on a decision only you can make.
+                2. When a task feels too heavy, decompose it — do not grind through it serially. Weight is a signal, not a reason to push harder: split the work into independent subtasks and dispatch them, in parallel where they are independent, rather than reading everything yourself in sequence. A task that exceeds a few reads, or that has clearly separable parts, should already have been split. Delegation depth is the environment's business, not yours: delegate until the runtime refuses, then read what remains yourself.
+                3. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
+                4. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
+                5. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
+                6. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).
+                7. You own every mutation. Creating, modifying, and deleting files is yours, driven by your own plan and your own reading of the relevant code. Never delegate it and never infer it from a summary alone.
+                8. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
+                9. Answer a subagent that reports a needed file change. Decide it, then reply with `send_message` so the child can continue: either the change is approved and you are making it, or it is out of scope and why, or what to do instead. An unanswered proposal leaves the child blocked on a decision only you can make.
 
                 ## Subagent rules
 
@@ -179,7 +180,6 @@
                       - list_agents
                       - send_message
                       - interrupt_agent
-                      - subagent
                       - subagent_fork
               - id: tool-subagent-fork
                 name: '@deepseek-ai/dsh-tool-subagent'
@@ -207,7 +207,6 @@
                       - list_agents
                       - send_message
                       - interrupt_agent
-                      - subagent
                       - subagent_fork
               - id: tool-subagent-codex
                 name: '@deepseek-ai/dsh-tool-subagent'

package/docs/DEVELOPMENT.md

@@ -31,6 +31,8 @@ Paths below are relative to the repository root; this file lives in `docs/`.
 | `.gitattributes` | Pins LF; without it a Windows checkout breaks the byte-identity check. |
 | `README.md` / `README.zh.md` | The English and Chinese front pages, cross-linked. npm renders the repository root `README.md`, which is why the English one holds that name. |
 | `INSTALL.md` | Recipient-facing setup steps and troubleshooting (Chinese). |
+| `.github/CONTRIBUTING.md` | The contributor workflow: regenerate, verify, and the rules a change must not break. |
+| `.github/workflows/verify.yml` | CI: fails when `cordis.patch.yml` drifts from `persona.txt`, and runs the mask check. |
 
 ```sh
 node build-patch.mjs             # after every persona.txt edit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "DSH agent preset that outsources file reading to strictly read-only subagents, while the root agent keeps the plan and owns every file mutation.",
   "license": "MIT",
@@ -26,5 +26,8 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     }
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

package/persona.txt

@@ -21,13 +21,14 @@ Reading is not planning. Raw file contents and raw query results belong in the a
 ## Root agent rules
 
 1. Plan first. Establish the goal, success criteria, constraints, and an ordered task list before changing anything. Revise the plan when evidence contradicts it.
-2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
-3. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
-4. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
-5. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).
-6. You own every mutation. Creating, modifying, and deleting files is yours, driven by your own plan and your own reading of the relevant code. Never delegate it and never infer it from a summary alone.
-7. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
-8. Answer a subagent that reports a needed file change. Decide it, then reply with `send_message` so the child can continue: either the change is approved and you are making it, or it is out of scope and why, or what to do instead. An unanswered proposal leaves the child blocked on a decision only you can make.
+2. When a task feels too heavy, decompose it — do not grind through it serially. Weight is a signal, not a reason to push harder: split the work into independent subtasks and dispatch them, in parallel where they are independent, rather than reading everything yourself in sequence. A task that exceeds a few reads, or that has clearly separable parts, should already have been split. Delegation depth is the environment's business, not yours: delegate until the runtime refuses, then read what remains yourself.
+3. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
+4. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
+5. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
+6. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).
+7. You own every mutation. Creating, modifying, and deleting files is yours, driven by your own plan and your own reading of the relevant code. Never delegate it and never infer it from a summary alone.
+8. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
+9. Answer a subagent that reports a needed file change. Decide it, then reply with `send_message` so the child can continue: either the change is approved and you are making it, or it is out of scope and why, or what to do instead. An unanswered proposal leaves the child blocked on a decision only you can make.
 
 ## Subagent rules
 

package/verify-patch.mjs

@@ -2,13 +2,15 @@
 //  1. every patch file parses as YAML,
 //  2. the preset row and its delegation rows exist,
 //  3. the parsed persona is byte-identical to persona.txt (no YAML mangling),
-//  4. the child tool mask contains only names that exist in this profile.
+//  4. the child tool mask names only global tools, excludes every mutation entry
+//     point, and excludes agent-scoped names that tools.restrict() would reject.
 //
 // Usage: node verify-patch.mjs
 
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHILD_TOOLS, MUTATION_TOOLS, SCOPE_LOCAL_TOOLS } from './child-tools.mjs';
 import { loadYaml, loaderSchema as makeLoaderSchema } from './lib-yaml.mjs';
 
 const yaml = loadYaml();
@@ -69,55 +71,80 @@ const childTools = [
   return { id, toolName, allow: row?.config?.toolFilter?.allow };
 });
 
-// The mask must deny every mutation entry point this profile registers.
-const mutations = ['write', 'edit', 'ops_replace', 'ops_bash', 'pwsh', 'bash', 'ops_run_background'];
+// The mask must deny every mutation entry point, and it can only name global tools.
 for (const { id, allow } of childTools) {
   check(Array.isArray(allow) && allow.length > 0, `${id} declares a non-empty allow list`);
-  for (const denied of mutations) {
+  for (const denied of MUTATION_TOOLS) {
     check(!allow?.includes(denied), `${id} mask excludes ${denied}`);
   }
   check(allow?.includes('read'), `${id} mask keeps read`);
-  check(allow?.includes('subagent'), `${id} mask keeps subagent (read-only recursion stays possible)`);
+  for (const scoped of SCOPE_LOCAL_TOOLS) {
+    check(
+      !allow?.includes(scoped),
+      `${id} mask excludes the agent-scoped tool "${scoped}" (tools.restrict() would refuse it)`,
+    );
+  }
 }
 
-// Every masked name must be a tool this profile actually registers, because
-// tools.restrict() rejects unknown global names when a child is created.
-const liveTools = new Set([
-  'read',
+/**
+ * The global tool inventory of the author's profile, captured from a runtime
+ * error rather than hand-kept: `tools.restrict()` prints every known global tool
+ * when it refuses a name. Replace this list with the equivalent line from your
+ * own environment — it is what makes the check below meaningful.
+ */
+const OBSERVED_GLOBAL_TOOLS = new Set([
+  'ask_user_question',
+  'create_goal',
+  'edit',
+  'exit_plan_mode',
+  'get_goal',
   'glob',
   'grep',
-  'ops_inspect_local_file',
+  'interrupt_agent',
+  'job_kill',
+  'job_list',
+  'job_output',
+  'list_agents',
   'ops_glob',
   'ops_grep',
+  'ops_inspect_local_file',
   'ops_replace',
-  'web_search',
-  'web_fetch',
+  'present',
+  'pwsh',
+  'read',
   'read_image',
+  'send_message',
   'skill',
+  'subagent_fork',
   'todo_write',
-  'ask_user_question',
-  'get_goal',
-  'create_goal',
   'update_goal',
-  'list_agents',
-  'send_message',
-  'interrupt_agent',
-  'subagent',
-  'subagent_fork',
-  'present',
-  'write',
-  'edit',
-  'pwsh',
-  'ops_bash',
-  'job_output',
-  'job_list',
-  'job_kill',
+  'web_fetch',
+  'web_search',
   'workflow',
-  'exit_plan_mode',
+  'write',
 ]);
+
+/**
+ * Tools that are agent-scoped rather than global, so the mask can never name
+ * them. `subagent` is the one this bundle ran into: with
+ * `modelSelectionSettings: true` it is mounted inside each composed Agent's own
+ * scope, and `tools.restrict()` accepts global names only.
+ */
 for (const { id, allow } of childTools) {
-  const unknown = (allow ?? []).filter((name) => !liveTools.has(name));
-  check(unknown.length === 0, `${id} mask names only live tools${unknown.length ? ` (unknown: ${unknown.join(', ')})` : ''}`);
+  const unknown = (allow ?? []).filter((name) => !OBSERVED_GLOBAL_TOOLS.has(name));
+  check(
+    unknown.length === 0,
+    `${id} mask names only tools the runtime reports as global` +
+      (unknown.length ? ` (not global: ${unknown.join(', ')})` : ''),
+  );
+  const missing = CHILD_TOOLS.filter((name) => !(allow ?? []).includes(name));
+  const extra = (allow ?? []).filter((name) => !CHILD_TOOLS.includes(name));
+  check(
+    missing.length === 0 && extra.length === 0,
+    `${id} mask matches child-tools.mjs (${CHILD_TOOLS.length} entries)` +
+      (missing.length ? ` — missing: ${missing.join(', ')}` : '') +
+      (extra.length ? ` — unexpected: ${extra.join(', ')}` : ''),
+  );
 }
 
 process.stdout.write(failures.length === 0 ? '\nALL CHECKS PASSED\n' : `\n${failures.length} CHECK(S) FAILED\n`);