dsh-root-planner-preset 1.1.4 → 1.1.6

package/README.md

@@ -21,10 +21,26 @@ This preset takes the middle line: **workers with tools, bounded by their task.*
 | Nobody runs an unbounded service | Persona rules for the root and for subagents | Prompt-level, covering what a schema cannot (`ops_bash` has no job registry) |
 | A subagent stays inside the task it was given | Persona rules: named files only, no drive-by fixes, no racing siblings | Prompt-level |
 | Delegation depth is the user's setting | The runtime depth cap (`subagent.maxDepth`) | **Structural**: past the cap it throws `SubagentDepthError` |
+| Live children are capped as well | `subagent.maxActiveSubagents` | **Structural**: past the cap a delegation fails with `subagent limit reached`, and it does not queue |
 | The root decides; workers execute | Persona rules | Prompt-level |
 
 The mask is an **allow** list: a tool added by a future plugin is invisible to subagents until it is added here.
 
+### Two limits you will meet on a broad task
+
+Both are Host settings, both are structural, and both are documented because they read
+like defects the first time:
+
+- **`subagent limit reached (active child limit: N)`** — a delegated child is
+  *resident*, not merely running: a slot returns only after its turn ends, its inbox
+  is empty, and its own children are disposed. A wide fan-out therefore holds every
+  slot until that work actually finishes, and the batch does not queue behind the
+  cap. Raise `maxActiveSubagents` (**Settings → Subagents**) if the machine can
+  carry more live agents, or dispatch a batch you can finish and collect it before
+  opening the next. The author's own profile carries 16 for this reason.
+- **`subagent depth N exceeds maxDepth M`** — a delegation from a leaf. That is the
+  cap working, not a failure; the child reads the material itself.
+
 ## How it works
 
 ```
@@ -106,9 +122,27 @@ 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, 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.
+**Verified end to end on a real task** — a 24-descendant run over a large reverse-engineering directory tree. Every line below was read from the session logs' own persisted tool schemas, which are the registry's output rather than a model's recollection:
 
-**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.
+| Property | Evidence |
+|---|---|
+| The mask reaches every child | The root is offered **31** tools; depth-1 and depth-2 agents are offered **25**. The difference is exactly the six the mask omits: `workflow`, `present`, `job_output`, `job_list`, `job_kill`, `exit_plan_mode`. |
+| Subagents really are workers | `write`, `edit`, `ops_replace` and `pwsh` are present at every depth and were used: 10 `write` and 60 `edit` from the root, 14 `write` from one depth-1 agent, 20 `write` from a depth-2 agent. |
+| No subagent can leave a process running | `run_in_background` is absent from the `pwsh` schema at all three depths. (A naive log search says otherwise — the phrase also occurs in `ops_bash`'s own description, which is why `tools/check-pwsh-background.mjs` inspects the schema window instead.) |
+| Recursion works | 12 direct children, 4 of which delegated onward to 12 grandchildren; the root itself made 14 `subagent` calls. |
+| The depth cap holds | The tree stops at depth 2; no depth-3 session exists anywhere in the log directory. |
+| The live-child cap is soft, not fatal | One `subagent limit reached (active child limit: 8)` during an 8-wide fan-out. Settlements returned slots as children finished, and every later delegation succeeded. |
+
+**Corrected after the fact**: an earlier version of this file claimed the mask made
+children leaf agents. It does not. `subagent` is registered per composed agent rather
+than globally, so the mask can never name it — and because a restriction filters
+globals only, a child keeps it. Recursion is bounded by `maxDepth`, not by the mask.
+
+**How to check it yourself**: `tools/verify-session.mjs` proves which preset each
+session ran and at what depth, but it does not read tool schemas. Use
+`tools/extract-offered-tools.mjs` for the per-level tool list,
+`tools/check-pwsh-background.mjs` for the process bound, and
+`tools/count-tool-calls.mjs` for what a level actually called.
 
 ## Contributing
 

package/README.zh.md

@@ -21,10 +21,18 @@
 | 谁都不跑无界服务 | 根与子代理的人设规则 | 提示词级，覆盖 schema 管不到的部分（`ops_bash` 没有任务注册表） |
 | 子代理不越出被交代的任务 | 人设规则：只动点名文件、不顺手修、不与兄弟抢文件 | 提示词级 |
 | 委派层数由用户配置 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
+| 在世子代理数也有上限 | `subagent.maxActiveSubagents` | **结构性**：超过上限时委派直接失败并报 `subagent limit reached`，**不会排队** |
 | 根决策、工人执行 | 人设规则 | 提示词级 |
 
 白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
 
+### 大任务上你会撞到的两个上限
+
+两个都是 Host 设置、都是结构性的，也都列在这里——因为它们第一次出现时看着像 bug：
+
+- **`subagent limit reached (active child limit: N)`** —— 子代理是**驻留**的，不只是"在跑"：只有它的轮次结束、收件箱清空、它自己的子代理也销毁之后，槽位才归还。所以宽扇出会把槽位一直占着，直到那批活真正做完；而且**超额的那批不会排队**。机器扛得住就把 `maxActiveSubagents`（**设置 → 子智能体**）调大，否则只派一批你能做完的、收完结果再开下一批。作者自己的 profile 因此设为 16。
+- **`subagent depth N exceeds maxDepth M`** —— 叶子层发起委派。这是上限在正常工作，不是故障；子代理自己读就是了。
+
 ## 工作方式
 
 ```
@@ -94,9 +102,20 @@ 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` 单一真源，生成器与校验脚本不可能再各说各话。
+**已在真实任务上端到端验证**——那次运行在一个大型逆向工程目录树上产生了 **24 个后代会话**。下面每一条都读自**会话日志自己持久化的工具 schema**，那是注册表的输出，不是模型的回忆：
+
+| 性质 | 证据 |
+|---|---|
+| 白名单覆盖每一层 | 根被提供 **31** 个工具；深度 1 与深度 2 的 agent 都是 **25** 个。差额正好是白名单排除的那 6 个：`workflow`、`present`、`job_output`、`job_list`、`job_kill`、`exit_plan_mode`。 |
+| 子代理确实是工人 | `write`、`edit`、`ops_replace`、`pwsh` 在每一层都在，而且真的被用了：根 10 次 `write` + 60 次 `edit`，某个深度 1 的子代理 14 次 `write`，某个深度 2 的孙代理 20 次 `write`。 |
+| 子代理留不下运行中的进程 | `run_in_background` 在三个层级的 `pwsh` schema 里**都不存在**。（朴素的全日志搜索会给出相反答案——`ops_bash` 自己的描述里也有这个词，所以要用 `tools/check-pwsh-background.mjs` 看 schema 窗口。） |
+| 递归成立 | 12 个直接子代理，其中 4 个继续派出了 12 个孙代理；根自己做了 14 次 `subagent` 调用。 |
+| 深度上限有效 | 树停在深度 2；整个日志目录里不存在任何深度 3 的会话。 |
+| 在世上限是软拒绝而非致命 | 8 路扇出时出现一次 `subagent limit reached (active child limit: 8)`；子代理完结时结算通知归还了槽位，此后每次委派都成功。 |
+
+**一处事后更正**：本文件早期版本称"白名单让子代理成为叶子"。**并非如此。** `subagent` 是按每个被组合 Agent 注册、而非全局注册，所以白名单**永远无法写下它的名字**；而限制只过滤全局工具，因此子代理**保有此工具**。递归的边界是 `maxDepth`，不是白名单。
 
-**仍未验证**：**还没有一次成功的子代理派出。** 递归按上面的理由**应当**可用——子代理继承预设、因此拥有自己的作用域 `subagent`，而限制不会隐藏作用域注册——但这个推理恰好就是本包已经错过一次的那类推理。在有人报告"两层委派成功"之前，请当作未确认。
+**想自己核**：`tools/verify-session.mjs` 能证明每个会话跑的是哪个预设、深度多少，但它不读工具 schema。逐层工具清单用 `tools/extract-offered-tools.mjs`，进程边界用 `tools/check-pwsh-background.mjs`，实际调用用 `tools/count-tool-calls.mjs`。
 
 ## 参与维护
 

package/cordis.patch.yml

@@ -42,17 +42,18 @@
                 ## 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. Decompose heavy work; do not delegate light work. Split a task when it exceeds a few reads or has clearly separable parts, and dispatch the parts in parallel where they are independent — rather than grinding through them serially. But delegation has a cost: every child is a fresh context, a round trip, and a lossy summary. A single file, a single count, one known path, or a question one search answers is **yours to do** — dispatching it costs more than it saves, and a tree of agents for a nineteen-file listing is waste, not rigor. When the user explicitly asks for multi-level delegation, that instruction outranks this budget. Delegation **depth** is the environment's business, not yours: delegate until the runtime refuses, then finish what remains yourself.
-                3. Delegate research by default — within that budget. 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. **Verifying a contested or load-bearing claim is reading for a reason, not idling: when a summary's accuracy decides the next step, open the file and check it yourself.** Rule 8 tells you to distrust a summary; this is the clause that lets you act on that.
-                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 the decisions about mutation; subagents carry out the ones you hand them. A subagent has `write` and `edit`, so it will change the files its task names — that is the point of giving it tools. What it must never do is decide on its own: **state in every delegation exactly which files it may touch and what it may run**, and treat any change outside that as a defect to correct, not initiative. Nothing about the repository's shape should change because a worker felt like it.
-                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. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
-                10. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
-                11. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
-                12. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+                2. Decompose heavy work; do not delegate light work. Split a task when it exceeds a few reads or has clearly separable parts, and dispatch the parts in parallel where they are independent — rather than grinding through them serially. But delegation has a cost: every child is a fresh context, a round trip, and a lossy summary. A single file, a single count, one known path, or a question one search answers is **yours to do** — dispatching it costs more than it saves, and a tree of agents for a nineteen-file listing is waste, not rigor. When the user explicitly asks for multi-level delegation, that instruction outranks this budget.
+                3. **Mind the live capacity, not just the work.** Delegated children are resident: a slot returns only after a child's turn ends, its inbox is empty, and its own children are gone. A wide fan-out therefore holds every slot until the work actually finishes, and starting more than the environment allows fails outright with a limit error — the batch does not queue. So dispatch a batch you can finish, collect its results before opening the next, and when a delegation is refused for capacity, that is information about your scheduling rather than a reason to retry: use the agents you already have, or finish what is in flight first. Neither the depth limit nor this capacity is yours to change; plan inside them.
+                4. Delegate research by default — within that budget. 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".
+                5. 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.
+                6. 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. **Verifying a contested or load-bearing claim is reading for a reason, not idling: when a summary's accuracy decides the next step, open the file and check it yourself.** Rule 9 tells you to distrust a summary; this is the clause that lets you act on that.
+                7. 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).
+                8. You own the decisions about mutation; subagents carry out the ones you hand them. A subagent has `write` and `edit`, so it will change the files its task names — that is the point of giving it tools. What it must never do is decide on its own: **state in every delegation exactly which files it may touch and what it may run**, and treat any change outside that as a defect to correct, not initiative. Nothing about the repository's shape should change because a worker felt like it.
+                9. 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.
+                10. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
+                11. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
+                12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
+                13. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
 
                 ## Subagent rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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,17 +21,18 @@ 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. Decompose heavy work; do not delegate light work. Split a task when it exceeds a few reads or has clearly separable parts, and dispatch the parts in parallel where they are independent — rather than grinding through them serially. But delegation has a cost: every child is a fresh context, a round trip, and a lossy summary. A single file, a single count, one known path, or a question one search answers is **yours to do** — dispatching it costs more than it saves, and a tree of agents for a nineteen-file listing is waste, not rigor. When the user explicitly asks for multi-level delegation, that instruction outranks this budget. Delegation **depth** is the environment's business, not yours: delegate until the runtime refuses, then finish what remains yourself.
-3. Delegate research by default — within that budget. 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. **Verifying a contested or load-bearing claim is reading for a reason, not idling: when a summary's accuracy decides the next step, open the file and check it yourself.** Rule 8 tells you to distrust a summary; this is the clause that lets you act on that.
-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 the decisions about mutation; subagents carry out the ones you hand them. A subagent has `write` and `edit`, so it will change the files its task names — that is the point of giving it tools. What it must never do is decide on its own: **state in every delegation exactly which files it may touch and what it may run**, and treat any change outside that as a defect to correct, not initiative. Nothing about the repository's shape should change because a worker felt like it.
-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. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
-10. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
-11. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
-12. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+2. Decompose heavy work; do not delegate light work. Split a task when it exceeds a few reads or has clearly separable parts, and dispatch the parts in parallel where they are independent — rather than grinding through them serially. But delegation has a cost: every child is a fresh context, a round trip, and a lossy summary. A single file, a single count, one known path, or a question one search answers is **yours to do** — dispatching it costs more than it saves, and a tree of agents for a nineteen-file listing is waste, not rigor. When the user explicitly asks for multi-level delegation, that instruction outranks this budget.
+3. **Mind the live capacity, not just the work.** Delegated children are resident: a slot returns only after a child's turn ends, its inbox is empty, and its own children are gone. A wide fan-out therefore holds every slot until the work actually finishes, and starting more than the environment allows fails outright with a limit error — the batch does not queue. So dispatch a batch you can finish, collect its results before opening the next, and when a delegation is refused for capacity, that is information about your scheduling rather than a reason to retry: use the agents you already have, or finish what is in flight first. Neither the depth limit nor this capacity is yours to change; plan inside them.
+4. Delegate research by default — within that budget. 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".
+5. 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.
+6. 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. **Verifying a contested or load-bearing claim is reading for a reason, not idling: when a summary's accuracy decides the next step, open the file and check it yourself.** Rule 9 tells you to distrust a summary; this is the clause that lets you act on that.
+7. 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).
+8. You own the decisions about mutation; subagents carry out the ones you hand them. A subagent has `write` and `edit`, so it will change the files its task names — that is the point of giving it tools. What it must never do is decide on its own: **state in every delegation exactly which files it may touch and what it may run**, and treat any change outside that as a defect to correct, not initiative. Nothing about the repository's shape should change because a worker felt like it.
+9. 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.
+10. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
+11. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
+12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
+13. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
 
 ## Subagent rules
 

package/release.mjs

@@ -220,6 +220,26 @@ step(`Upgrade the local "${profile}" profile so the machine runs what was publis
 if (dryRun || skipInstall) {
   process.stdout.write('  skipped\n');
 } else {
+  // The profile installs through the CONFIGURED registry, which is a mirror that
+  // lags the official one — so a version that just went live can still answer
+  // "No matching version found" here. That is what made this step fail after the
+  // 1.1.4 release, with nothing wrong on the npm side. Wait for the mirror, then
+  // name the official registry anyway so the install works either way.
+  const mirror = process.env.DSH_RELEASE_MIRROR ?? 'https://registry.npmmirror.com/';
+  const probeMirror = () =>
+    spawnSync('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '-m', '20', '-x', PROXY, `${mirror}${manifest.name}/${version}`], {
+      encoding: 'utf8',
+    }).stdout?.trim();
+  let mirrored = false;
+  for (let attempt = 1; attempt <= 30 && !mirrored; attempt += 1) {
+    mirrored = probeMirror() === '200';
+    if (!mirrored) {
+      if (attempt === 1) process.stdout.write(`  waiting for ${mirror} to mirror ${version}…\n`);
+      await new Promise((resolve) => setTimeout(resolve, 20_000));
+    }
+  }
+  process.stdout.write(mirrored ? `  ${mirror} has it\n` : `  ${mirror} still lacks it; using the official registry\n`);
+
   // `dsh` is a shell shim on Windows too, so it is invoked through Node rather
   // than spawned directly. DSH_RELEASE_DSH overrides the entry point.
   const dshEntry = process.env.DSH_RELEASE_DSH ?? 'D:/nodejs/npm_global/node_modules/@deepseek-ai/dsh/lib/bin.js';

package/tools/check-pwsh-background.mjs

@@ -0,0 +1,91 @@
+// Checks whether `run_in_background` still exists inside a session's `pwsh` tool
+// schema — the one property this preset enforces structurally rather than by asking
+// the model nicely.
+//
+// A whole-log substring search cannot answer it: the phrase also appears in
+// `ops_bash`'s own description on this machine, so the naive check reports "present"
+// for a session where the parameter has genuinely been removed.
+//
+// Usage: node tools/check-pwsh-background.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+/**
+ * Find every `"name":"<tool>"` occurrence and return the window of text that follows
+ * it — close enough to hold that tool's own parameters object.
+ * @param text - whole decompressed log.
+ * @param tool - tool name to locate.
+ * @returns the following windows, longest first.
+ */
+function windowsAfter(text, tool) {
+  const needle = `\\"name\\":\\"${tool}\\"`;
+  const plain = `"name":"${tool}"`;
+  const out = [];
+  for (const pattern of [needle, plain]) {
+    let from = 0;
+    for (;;) {
+      const at = text.indexOf(pattern, from);
+      if (at === -1) break;
+      out.push(text.slice(at, at + 4000));
+      from = at + pattern.length;
+    }
+  }
+  return out.sort((a, b) => b.length - a.length);
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  const header = JSON.parse(text.split('\n')[0]);
+
+  const pwshWindows = windowsAfter(text, 'pwsh');
+  // The parameters object is the one that mentions the tool's own argument names.
+  const schemaWindow = pwshWindows.find((w) => w.includes('workdir') || w.includes('command')) ?? pwshWindows[0] ?? '';
+  const backgroundInSchema = /run_in_background/.test(schemaWindow);
+  const backgroundAnywhere = text.includes('run_in_background');
+
+  process.stdout.write(
+    `\n${dir.split(/[\\/]/).pop().slice(0, 20)}  depth=${header?.delegationDepth}\n` +
+      `  "run_in_background" anywhere in the log : ${backgroundAnywhere}\n` +
+      `  inside the pwsh schema window          : ${backgroundInSchema}` +
+      `${backgroundInSchema ? '  <-- the parameter is still offered' : '  <-- removed, as intended'}\n` +
+      `  pwsh schema window size                 : ${schemaWindow.length} chars\n`,
+  );
+  if (backgroundAnywhere && !backgroundInSchema) {
+    const at = text.indexOf('run_in_background');
+    process.stdout.write(`  first mention context: …${text.slice(Math.max(0, at - 120), at + 60)}…\n`);
+  }
+}

package/tools/child-status.mjs

@@ -0,0 +1,102 @@
+// Reports whether each child session in a run is finished or still active, from its
+// own log — the question behind "subagent limit reached": are slots being held by
+// children that already stopped, or by children that are genuinely still working?
+//
+// Usage: node tools/child-status.mjs <root-session-dir>
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+const rootDir = process.argv[2];
+if (rootDir === undefined) {
+  process.stderr.write('usage: node tools/child-status.mjs <root-session-dir>\n');
+  process.exit(2);
+}
+
+const base = join(rootDir, '..');
+const rootId = rootDir.split(/[\\/]/).pop();
+const rows = [];
+
+for (const name of readdirSync(base)) {
+  const file = join(base, name, 'session.v4.jsonl.zstd');
+  try {
+    if (!statSync(file).isFile()) continue;
+  } catch {
+    continue;
+  }
+  const text = await decompressAll(readFileSync(file));
+  const events = text
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+  const header = events[0];
+  if (name !== rootId && header?.origin !== 'subagent') continue;
+
+  const types = new Map();
+  for (const event of events) types.set(event.type, (types.get(event.type) ?? 0) + 1);
+
+  const last = events[events.length - 1];
+  rows.push({
+    id: name,
+    depth: header?.delegationDepth,
+    mtime: statSync(file).mtime,
+    events: events.length,
+    lastType: last?.type,
+    lastTime: last?.time,
+    // A turn that ended and left nothing pending is the shape of a settled child.
+    turnEnds: types.get('turn/end') ?? 0,
+    hasInboxPending: types.has('agent/inbox/spliced') && !types.has('agent/inbox/claimed'),
+    cancels: types.get('agent/cancel') ?? 0,
+  });
+}
+
+rows.sort((a, b) => (a.lastTime ?? 0) - (b.lastTime ?? 0));
+const fmt = (ms) => (ms === undefined ? '?' : new Date(ms).toISOString().slice(11, 19));
+
+process.stdout.write(`${rows.length} agent session(s) under ${base}\n\n`);
+process.stdout.write('depth  turnEnds  events  last event type           last event time  session\n');
+for (const row of rows) {
+  process.stdout.write(
+    `${String(row.depth ?? '-').padEnd(6)} ${String(row.turnEnds).padEnd(9)} ${String(row.events).padEnd(7)} ` +
+      `${String(row.lastType ?? '-').padEnd(25)} ${fmt(row.lastTime).padEnd(16)} ${row.id.slice(0, 20)}\n`,
+  );
+}

package/tools/count-tool-calls.mjs

@@ -0,0 +1,78 @@
+// Counts the tool calls actually made in one session, by name.
+//
+// Written to settle a question that string counting cannot: which delegation tool a
+// given level really called, and therefore which tools the child mask actually left
+// visible. A raw occurrence count of "subagent" matches "subagent_fork" too, and the
+// preset's own prose mentions both.
+//
+// Usage: node tools/count-tool-calls.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  const events = text
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+
+  const header = events[0];
+  const calls = new Map();
+  for (const event of events) {
+    if (event.type !== 'tool/call') continue;
+    const name = event.data?.name ?? event.data?.message?.name;
+    if (typeof name !== 'string') continue;
+    calls.set(name, (calls.get(name) ?? 0) + 1);
+  }
+
+  const name = dir.split(/[\\/]/).pop().slice(0, 20);
+  process.stdout.write(
+    `\n${name}  depth=${header?.delegationDepth}  origin=${header?.origin}  ${events.length} events\n`,
+  );
+  const rows = [...calls.entries()].sort((a, b) => b[1] - a[1]);
+  process.stdout.write(`  ${rows.length} distinct tools called: ${rows.map(([t, n]) => `${t}×${n}`).join(', ') || '(none)'}\n`);
+  const delegation = rows.filter(([t]) => t.startsWith('subagent'));
+  process.stdout.write(
+    `  delegation calls: ${delegation.map(([t, n]) => `${t}×${n}`).join(', ') || '(none)'}\n`,
+  );
+}

package/tools/extract-offered-tools.mjs

@@ -0,0 +1,69 @@
+// Extracts the tool names a session was actually offered, from the tool schemas the
+// session log persists.
+//
+// Why this exists: a subagent's own account of its tools is a language-model
+// recollection, and it can be wrong in both directions (the first such report
+// omitted `write` from its list while claiming to discuss it). The persisted
+// schemas are the registry's own output, so they settle questions like "does the
+// child mask really apply?" and "is run_in_background gone?" without guessing.
+//
+// Usage: node tools/extract-offered-tools.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+for (const dir of process.argv.slice(2)) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+
+  // A tool schema is an object carrying `name` plus `parameters` (and `description`).
+  // Collect every name that appears next to a parameters object anywhere in the log.
+  const names = new Set();
+  for (const match of text.matchAll(/\{\\?"name\\?":\\?"([a-zA-Z_][a-zA-Z0-9_]*)\\?":\{[^{}]*\\?"type\\?":\\?"object\\?"/g)) {
+    names.add(match[1]);
+  }
+  for (const match of text.matchAll(/\\?"name\\?":\\?"([a-zA-Z_][a-zA-Z0-9_]*)\\?",\\?"description\\?":/g)) {
+    names.add(match[1]);
+  }
+
+  const header = JSON.parse(text.split('\n')[0]);
+  const listed = [...names].sort();
+  process.stdout.write(
+    `\n${dir.split(/[\\/]/).pop().slice(0, 20)}  depth=${header?.delegationDepth}\n  ${listed.length} names: ${listed.join(', ')}\n`,
+  );
+  for (const probe of ['workflow', 'present', 'job_output', 'exit_plan_mode', 'subagent', 'subagent_fork', 'pwsh', 'write']) {
+    process.stdout.write(`    ${probe.padEnd(16)} ${names.has(probe) ? 'present' : 'ABSENT'}\n`);
+  }
+}