dsh-root-planner-preset 1.0.3 → 1.0.4

package/README.md

@@ -18,26 +18,39 @@ 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** |
-| Subagents cannot delegate further | The same list cannot name the spawn tool, *and* the runtime depth cap | **Structural**, twice over — see below |
+| 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    <- the only one with write / edit / shell
-└── subagent  <- read-only, and cannot delegate further
+root agent  ──delegates──▶  subagent  ──delegates──▶  … until maxDepth
+   │                            │
+   └── the only one with write / edit / shell; every level stays read-only
 ```
 
-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.
+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.
@@ -89,9 +102,9 @@ Then **start a new session** and pick **Root Planner** in the preset selector. F
 
 **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.
+**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.
 
-**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.
+**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
 

package/README.zh.md

@@ -18,20 +18,28 @@
 |---|---|---|
 | 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
 | 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
-| 子代理不能再往下派 | 同一白名单无法写上 spawn 工具名，**且**运行时深度上限 | **双重结构性**，见下 |
+| 委派层数由配置决定 | 运行时深度上限（`subagent.maxDepth`，Host 设置） | **结构性**：超过上限直接抛 `SubagentDepthError` |
 | 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
-| 根 agent 默认委派阅读 | 人设规则 | 提示词级 |
+| 任务过重时拆分下发而非硬扛 | 人设规则 2 | 提示词级 |
 
-白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
+白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见——**但有一个例外，而正是它让递归得以成立**。
 
 ## 工作方式
 
 ```
-根 agent     ← 只有它有 write / edit / shell
-└── 子代理   ← 只读，且不能再往下派
+根 agent  ──委派──▶  子代理  ──委派──▶  … 直到 maxDepth
+   │                      │
+   └── 只有它有 write / edit / shell；每一层都保持只读
 ```
 
-树只有两层，而且是**双重强制**的：运行时深度上限挡一层，白名单再挡一层。因为 `subagent` 是注册在每个被组合 Agent **自身作用域**里的，而 `toolFilter` 只接受全局工具名——子代理连它的名字都写不上。本包早期版本确实把 `subagent` 写进了白名单，结果是**每一次子代理创建都失败**，报 `tools.restrict() names unknown global tool "subagent"`。所以调高深度设置也不会重新打开委派：已经没有可调用的工具了。
+有两个机制决定树有多深，方向一致：
+
+- **白名单**剥掉**每一层**、**每一个**子代理的所有写入入口——这个保证不随深度衰减。
+- **深度上限**（`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）、当前内容、建议替换、理由。
@@ -83,9 +91,9 @@ dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
 
 **已验证**：补丁可被 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 "subagent"`。根因是本包**设计上的错误**，不是配置错误——`subagent` 注册在每个被组合 Agent 自身的作用域里，而 `toolFilter` 只接受全局工具名，白名单写了一个它永远不可能合法包含的名字。现在白名单不再写它，`verify-patch.mjs` 会**按意图断言它必须缺席**，白名单也收敛到 `child-tools.mjs` 单一真源，生成器与校验脚本不可能再各说各话。
 
-**仍未验证**：还没有一次**成功**的子代理派出——上面那次失败是目前唯一的端到端证据。`verify-patch.mjs` 里的全局工具清单就是**从那次的运行时报错里抄下来的**；你的 profile 若注册了不同的集合，需要改的是白名单。
+**仍未验证**：**还没有一次成功的子代理派出。** 递归按上面的理由**应当**可用——子代理继承预设、因此拥有自己的作用域 `subagent`，而限制不会隐藏作用域注册——但这个推理恰好就是本包已经错过一次的那类推理。在有人报告"两层委派成功"之前，请当作未确认。
 
 ## 参与维护
 

package/child-tools.mjs

@@ -5,19 +5,25 @@
  * 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:
+ * `subagent` is deliberately NOT here, and cannot be — but that does NOT mean a
+ * subagent lacks it. Two separate facts:
  *
- *   Error: tools.restrict() names unknown global tool "subagent"; known global
- *   tools: ask_user_question, create_goal, edit, … subagent_fork, …
+ *  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.
  *
- * `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.
+ * 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',

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". 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).
-                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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.0.3",
+  "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",

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". 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).
-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