dsh-root-planner-preset 1.0.2 → 1.0.3

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,7 +18,7 @@ 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` |
+| Subagents cannot delegate further | The same list cannot name the spawn tool, *and* the runtime depth cap | **Structural**, twice over — see below |
 | 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 |
 
@@ -27,12 +27,18 @@ The mask is an **allow** list, not a deny list: a tool added by a future plugin
 ## 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    <- the only one with write / edit / shell
+└── subagent  <- read-only, and cannot delegate further
 ```
 
+The tree is two levels, enforced twice over. The runtime depth cap does it, and so
+does the mask: `subagent` is mounted inside each composed Agent's own scope rather
+than globally, while a `toolFilter` accepts global tool names only — so a child
+cannot even name 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"`. Raising the depth setting
+therefore does not re-open delegation; there is no tool left to call.
+
 - **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 +87,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. The mask no longer names it, `verify-patch.mjs` now 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 — the failure above is the only end-to-end evidence there is. The global-tool inventory in `verify-patch.mjs` was transcribed from that runtime error; if your profile registers a different set, the mask is what has to adapt.
 
 ## 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,7 +18,7 @@
 |---|---|---|
 | 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
 | 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
-| 任务不会被无限转派 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
+| 子代理不能再往下派 | 同一白名单无法写上 spawn 工具名，**且**运行时深度上限 | **双重结构性**，见下 |
 | 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
 | 根 agent 默认委派阅读 | 人设规则 | 提示词级 |
 
@@ -27,12 +27,12 @@
 ## 工作方式
 
 ```
-根 agent (depth 0)          ← 只有它有 write / edit / shell
-├── 子代理 (depth 1)        ← 只读；可以再派一层
-│   └── 孙代理 (depth 2)    ← 只读；叶子
-└── 子代理 (depth 1)
+根 agent     ← 只有它有 write / edit / shell
+└── 子代理   ← 只读，且不能再往下派
 ```
 
+树只有两层，而且是**双重强制**的：运行时深度上限挡一层，白名单再挡一层。因为 `subagent` 是注册在每个被组合 Agent **自身作用域**里的，而 `toolFilter` 只接受全局工具名——子代理连它的名字都写不上。本包早期版本确实把 `subagent` 写进了白名单，结果是**每一次子代理创建都失败**，报 `tools.restrict() names unknown global tool "subagent"`。所以调高深度设置也不会重新打开委派：已经没有可调用的工具了。
+
 - **根 agent**：先立计划（目标、成功判据、约束、任务清单），把阅读/搜索/定位默认派出去，自己只在「单个已知文件、一小段范围、或核实子代理的某个断言」时才亲自读。
 - **子代理**：只读、只定位、只总结。发现**需要改文件**时不动手，而是回报精确的改动方案——目标路径、位置（file:line）、当前内容、建议替换、理由。
 - **根 agent 收到方案后决策**，然后亲自落盘。
@@ -81,13 +81,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) 的故障排查。
+**仍未验证**：还没有一次**成功**的子代理派出——上面那次失败是目前唯一的端到端证据。`verify-patch.mjs` 里的全局工具清单就是**从那次的运行时报错里抄下来的**；你的 profile 若注册了不同的集合，需要改的是白名单。
 
 ## 参与维护
 
-**欢迎提 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,56 @@
+/**
+ * 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. With
+ * `modelSelectionSettings: true` that tool is registered per agent inside the
+ * composed Agent's own scope (`dsh-tool-subagent` mounts 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:
+ *
+ *   Error: tools.restrict() names unknown global tool "subagent"; known global
+ *   tools: ask_user_question, create_goal, edit, … subagent_fork, …
+ *
+ * `subagent_fork` is registered in the preset's own scope instead, so it IS
+ * visible to the mask and stays. Both names were in this list until a real
+ * subagent spawn failed, which is exactly the class of mistake no amount of
+ * reading the source had caught.
+ */
+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,7 +42,7 @@
                 ## 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".
+                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". A subagent does not have `subagent`; it reads for itself, or uses `subagent_fork` if the tree still allows one more level.
                 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).
@@ -179,7 +179,6 @@
                       - list_agents
                       - send_message
                       - interrupt_agent
-                      - subagent
                       - subagent_fork
               - id: tool-subagent-fork
                 name: '@deepseek-ai/dsh-tool-subagent'
@@ -207,7 +206,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.3",
   "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,7 +21,7 @@ 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".
+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". A subagent does not have `subagent`; it reads for itself, or uses `subagent_fork` if the tree still allows one more level.
 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).

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`);