dsh-root-planner-preset 1.0.4 → 1.1.0

package/.github/CONTRIBUTING.md

@@ -72,9 +72,13 @@ script prints `SKIP` and explains why. That is a pass, not a failure.
 - **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.
+- Do not weaken the **process bound**. `enableRunInBackground: false` must stay on
+  the preset's `tool-pwsh` row: a change that lets a subagent detach a server drops
+  the one property this preset enforces structurally rather than by asking nicely.
+  `verify-patch.mjs` fails if it is missing.
+- A subagent keeps `write`, `edit`, `ops_replace` and `pwsh`. They are workers —
+  taking their tools away turns every executable step back into the root's own work,
+  which is the failure mode this preset exists to avoid.
 - Keep `main` linear — the branch protection refuses merge commits, so rebase
   rather than merge.
 

package/INSTALL.md

@@ -87,6 +87,9 @@ git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
 
 1. **开一个新会话**（已有会话和它的子代理会保留启动时的插件版本，不会变）。
 2. 在预设选择器里选 **Root Planner**。
+
+   > ⚠️ **这是最容易踩的坑：根会话必须真的选中 Root Planner。** 有人实测时根会话仍是 `standard`，结果整棵树的行为都对不上——根不受本预设任何规则约束，而它派出的子代理却是 `root-planner`，于是"谁的权限是什么"完全错位，最后据此得出一堆关于预设的错误结论。**怎么确认**：会话文件 `~/.dsh/sessions/<cwd>/<session-id>/session.v4.jsonl.zstd` 的第一行里有 `"agentPreset":"root-planner"` 字段；写着 `standard` 就是没选中。
+
 3. 派一个研究任务，确认两件事：
 
    - 子代理的工具列表里**没有** `write`、`edit`、`ops_replace`、`ops_bash`、`pwsh`；
@@ -110,7 +113,8 @@ git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
 | 子代理创建失败，报 **`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`；改完必须重开会话 |
+| 子代理**还是能改文件** | 根会话没选中 Root Planner（见第四节），或白名单被改坏了 | 先查会话文件的 `agentPreset` 字段是否 `root-planner`；再确认 `cordis.patch.yml` 里两处 `toolFilter.allow` 都**不含** `write`、`edit`、`ops_replace`、`ops_bash`、`pwsh`。改完必须重开会话 |
+| 行为与人设描述**对不上**（比如"子代理能写"、"规则没生效"） | 最常见的原因就是**根会话跑在别的预设上**，而它的子代理跑在 root-planner 上——两者的规则和权限本来就不一样 | 查会话文件第一行的 `agentPreset`；也可跑 `node tools/inspect-sessions.mjs <会话目录>` 一次性打印根与全部子会话的预设、深度与工具清单 |
 | 改了 `persona.txt` 但没生效 | 会话与子代理都锁定启动时的插件版本 | 开**新会话**；必要时把 `preset-root-planner` 在插件列表里关掉再打开 |
 | Windows 上校验报**人设不一致** | 换行符被 Git 改写了 | 确认 `.gitattributes` 存在且含 `* text=auto eol=lf`，重新克隆一次 |
 

package/README.md

@@ -1,41 +1,43 @@
 # dsh-root-planner-preset
 
-An agent preset for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) that **separates reading from deciding**.
+An agent preset for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) that **separates deciding from doing**.
 
-The root agent's context holds task analysis, planning and decisions; file reading and information queries go to subagents that return summaries only. Creating, modifying and deleting files stays with the root agent — subagents do not even have the tools.
+The root agent's context holds the plan and the decisions; reading, editing and running commands go to subagents that report back summaries. Subagents are full workers — they have `write`, `edit` and a shell — and the one thing none of them may leave behind is **a process still running**.
 
-> One agent in the tree has hands. Every other agent has only eyes.
+> The root decides, the workers do the work, and nothing outlives the task.
 
 [中文说明](README.zh.md) | [Install](INSTALL.md) | [Maintainer notes](docs/DEVELOPMENT.md)
 
 ## The problem it solves
 
-On a long task a coding agent's context fills up with raw file contents, and it forgets the goal, loses the plan, and starts repeating work. The usual answer — "delegate more to subagents" — does not hold on its own: a subagent will still edit files on its way past, and work gets passed further down without limit.
+On a long task a coding agent's context fills up with raw file contents and command output, and it forgets the goal, loses the plan, and starts repeating work. The usual answer — "delegate more to subagents" — fails in two opposite directions: a delegate with no hands cannot do anything, so every step bounces back; and a fleet of delegates with no bounds will edit whatever they like and leave servers running.
 
-This preset turns both of those into structural constraints rather than good intentions:
+This preset takes the middle line: **workers with tools, bounded by their task.**
 
 | Requirement | Mechanism | Strength |
 |---|---|---|
-| 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** |
-| 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 |
-| A heavy task is decomposed rather than ground through | Persona rule 2 | Prompt-level |
+| A subagent can read, **edit files and run commands** | `toolFilter.allow` on both delegation tools includes `write`, `edit`, `ops_replace`, `pwsh` | Grant, not restriction — a worker without tools is not a worker |
+| A subagent cannot leave a process running | `enableRunInBackground: false` on the preset's `pwsh` row: the call is refused **and** `run_in_background` is removed from the tool schema | **Structural** — no model at any depth can reach for a detached process |
+| 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` |
+| The root decides; workers execute | Persona rules | 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 — **with one exception, and it is what makes recursion work.**
+The mask is an **allow** list: a tool added by a future plugin is invisible to subagents until it is added here.
 
 ## How it works
 
 ```
 root agent  ──delegates──▶  subagent  ──delegates──▶  … until maxDepth
    │                            │
-   └── the only one with write / edit / shell; every level stays read-only
+   └── decides, integrates, and states what each worker may touch
 ```
 
 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 mask** gives *every* subagent, at *every* level, the same working set — read,
+  write, shell — and withholds the same things. The grant does not weaken with
+  depth, and neither does the bound.
 - **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.
@@ -52,9 +54,9 @@ subagent creation failed** with
 `tools.restrict() names unknown global tool "subagent"` — the mask rejecting a
 name it could never legally contain, not the tool being missing.
 
-- **Root agent**: plans first (goal, success criteria, constraints, ordered task list), delegates reading, searching and locating by default, and reads directly only for one known file, a short targeted range, or to check a claim a subagent made.
-- **Subagent**: reads, locates and summarizes. On finding that a file **needs changing** it does not act; it reports the exact change — target path, location (`file:line`), current content, proposed replacement, and why.
-- **The root agent decides** on that proposal and then makes the change itself.
+- **Root agent**: plans first (goal, success criteria, constraints, ordered task list), dispatches work that is heavy enough to be worth the round trip, keeps the integration and the decisions, and states in every delegation which files may be touched.
+- **Subagent**: does the task — reads, edits the files it was given, runs the commands that belong to it — and reports the conclusion with the minimum evidence, plus exactly what it changed.
+- **The root decides** what changes and who makes them; a worker that changes something outside its task is a defect, not initiative.
 
 How does a subagent know it is a subagent? DSH force-inserts the sentence `You are a delegated subagent: …` into every subagent's prompt, injected by the runtime and impossible to remove — while a preset persona has **no** `{{role}}`-style variable available. So the persona states a **test** instead: read your own prompt for that sentence. One persona then serves both roles, and parent and child read the same text, which is what prevents the drift where a parent believes a child is constrained and the child never saw it.
 
@@ -76,6 +78,8 @@ Then **one required step**: set **Settings → Subagents → depth limit** to **
 
 Then **start a new session** and pick **Root Planner** in the preset selector. Full steps and troubleshooting are in [INSTALL.md](INSTALL.md).
 
+> ⚠️ **The easiest mistake to make: the root session must actually be composed with Root Planner.** In one real trial the root session was still `standard`, so the root was bound by none of this preset while the subagents it spawned *were* `root-planner` — every rule and permission in the tree was mismatched, and a batch of confident conclusions about the preset followed from it. **To check:** the first line of `~/.dsh/sessions/<cwd>/<session-id>/session.v4.jsonl.zstd` carries `"agentPreset"`, which must read `root-planner`; or run `node tools/inspect-sessions.mjs <session-dir>` to print the preset, depth and tool inventory of the root and every child at once.
+
 ## When it fits, and when it does not
 
 **Fits**: long research-heavy tasks across many files, reverse engineering, code review — anything read-heavy, or where a change must be carefully decided.

package/README.zh.md

@@ -1,49 +1,50 @@
 # dsh-root-planner-preset
 
-一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 agent 预设：**把「读书」和「决策」分开**。
+一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 agent 预设：**把「决策」和「干活」分开**。
 
-根 agent 的上下文只装任务分析、规划与决策；文件阅读、信息查询交给子代理，子代理只回摘要。而**创建、修改、删除文件只能由根 agent 执行**——子代理连工具都没有。
+根 agent 的上下文装计划与决策；阅读、改文件、跑命令交给子代理，子代理回报摘要。**子代理是有工具的工人**——它有 `write`、`edit` 和 shell；唯一不许留下的是**还在跑的进程**。
 
-> 一句话：让整棵树里只有一个 agent 有手，其余都只有眼睛。
+> 根负责决策，工人负责干活，没有任何东西能活过任务本身。
 
 [English](README.md) | [安装步骤](INSTALL.md) | [维护者文档](docs/DEVELOPMENT.md)
 
 ## 它解决什么问题
 
-用 coding agent 干长任务，上下文很快被原始文件内容塞满，于是忘了目标、丢了计划、开始重复劳动。常见对策是「让 agent 多派子代理」，但光靠提示词约束不住——子代理照样会顺手改文件，任务也会被无限往下转派。
+用 coding agent 干长任务，上下文很快被原始文件内容和命令输出塞满，于是忘了目标、丢了计划、开始重复劳动。常见对策「让 agent 多派子代理」会朝两个相反方向失败：**没有手的子代理什么也干不了**，每一步都被推回根；而**没有边界的子代理群**会随手改任何文件、还会给你留下一堆跑着的服务。
 
-这个预设把两件事做成了结构约束，而不是靠自觉：
+本预设走中间那条线：**有工具的工人，边界是它的任务。**
 
 | 要求 | 机制 | 强度 |
 |---|---|---|
-| 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
-| 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
-| 委派层数由配置决定 | 运行时深度上限（`subagent.maxDepth`，Host 设置） | **结构性**：超过上限直接抛 `SubagentDepthError` |
-| 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
-| 任务过重时拆分下发而非硬扛 | 人设规则 2 | 提示词级 |
+| 子代理能读、**能改文件、能跑命令** | 两个委派工具的白名单**包含** `write`、`edit`、`ops_replace`、`pwsh` | 这是授予而非限制——没有工具的工人不算工人 |
+| 子代理不能留下运行中的进程 | 预设的 `pwsh` 行设 `enableRunInBackground: false`：后台调用被拒，**且 `run_in_background` 参数被从工具 schema 里移除** | **结构性**——任何深度的模型都够不到"脱离进程"这个能力 |
+| 谁都不跑无界服务 | 根与子代理的人设规则 | 提示词级，覆盖 schema 管不到的部分（`ops_bash` 没有任务注册表） |
+| 子代理不越出被交代的任务 | 人设规则：只动点名文件、不顺手修、不与兄弟抢文件 | 提示词级 |
+| 委派层数由用户配置 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
+| 根决策、工人执行 | 人设规则 | 提示词级 |
 
-白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见——**但有一个例外，而正是它让递归得以成立**。
+白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
 
 ## 工作方式
 
 ```
 根 agent  ──委派──▶  子代理  ──委派──▶  … 直到 maxDepth
    │                      │
-   └── 只有它有 write / edit / shell；每一层都保持只读
+   └── 决策、集成、把关；每一层都拿同一套工具，也受同一条边界
 ```
 
 有两个机制决定树有多深，方向一致：
 
-- **白名单**剥掉**每一层**、**每一个**子代理的所有写入入口——这个保证不随深度衰减。
+- **白名单**给**每一层**、**每一个**子代理同一套工作集（读、写、shell），也扣掉同样几样。授予不随深度衰减，边界也不衰减。
 - **深度上限**（`subagent.maxDepth`，由你控制的 Host 设置）决定有几层。`2` 就是根 → 子 → 孙；调大则更深，设成 `1` 则子代理变叶子。
 
 `toolFilter` 是**全局**工具的掩码，而 `subagent` 不是全局工具：因为 `modelSelectionSettings: true`，它被注册进每个被组合 Agent **自身的作用域**，掩码永远写不上它的名字。所以它不在 `child-tools.mjs` 里——**不是**因为子代理没有它。作用域注册**不受限制影响**，而每个子代理都继承本预设，于是每一层都拿到自己的 `subagent`，可以一直往下派到深度上限为止。
 
 本包早期版本确实把 `subagent` 写进了白名单，结果是**每一次子代理创建都失败**，报 `tools.restrict() names unknown global tool "subagent"`——那是白名单在拒绝一个它永远不可能合法包含的名字，不是工具缺失。
 
-- **根 agent**：先立计划（目标、成功判据、约束、任务清单），把阅读/搜索/定位默认派出去，自己只在「单个已知文件、一小段范围、或核实子代理的某个断言」时才亲自读。
-- **子代理**：只读、只定位、只总结。发现**需要改文件**时不动手，而是回报精确的改动方案——目标路径、位置（file:line）、当前内容、建议替换、理由。
-- **根 agent 收到方案后决策**，然后亲自落盘。
+- **根 agent**：先立计划（目标、成功判据、约束、任务清单），把值得一次往返的活派出去，自己保留集成、把关与决策——并在每次委派里**点名允许改哪些文件**。
+- **子代理**：干活。读、改被点名的文件、跑属于它的命令，然后回报结论与最小证据，外加**确切改了哪些文件**。
+- **根决策**改什么、谁改；工人改了任务之外的东西，那是缺陷，不是主动性。
 
 子代理怎么知道自己是子代理？DSH 会在每个子代理的提示词里强制插入一句 `You are a delegated subagent: …`，运行时注入、无法移除，而预设人设**没有** `{{role}}` 这类变量可用。所以人设里写的是一条**判定指令**：读自己的提示词里有没有那句话。这让人设只需要一份，父与子读到的是同一份文本，因此不会出现「父以为子被这么约束、子其实没读到」的漂移。
 
@@ -65,6 +66,8 @@ dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
 
 然后**开新会话**，在预设选择器里选 **Root Planner**。完整步骤与故障排查见 [INSTALL.md](INSTALL.md)。
 
+> ⚠️ **最容易踩的坑：根会话必须真的选中 Root Planner。** 有人实测时根会话仍是 `standard`，于是根不受本预设约束、而它派出的子代理却是 `root-planner`——权限与规则整棵树错位，最后据此得出一批关于本预设的错误结论。**确认方法**：会话文件 `~/.dsh/sessions/<cwd>/<session-id>/session.v4.jsonl.zstd` 第一行的 `"agentPreset"` 字段应为 `root-planner`；或跑 `node tools/inspect-sessions.mjs <会话目录>` 一次性列出根与全部子会话的预设、深度与工具清单。
+
 ## 适合 / 不适合
 
 **适合**：需要跨很多文件调研的长任务、逆向分析、代码审查，以及任何「读得多、改得少」或「改动必须被仔细决策」的工作。

package/build-patch.mjs

@@ -65,7 +65,7 @@ const patch = `# Generated by build-patch.mjs from persona.txt. Do not hand-edit
       config:
         id: root-planner
         name: Root Planner
-        description: Plans in a lean context, delegates reading to strictly read-only subagents, and owns every file mutation.
+        description: Keeps the plan and the decisions in the root agent, dispatches reading, edits and commands to subagent workers, and lets nothing outlive the task.
         order: 5
         plugins:
           - id: persona
@@ -84,6 +84,16 @@ const patch = `# Generated by build-patch.mjs from persona.txt. Do not hand-edit
           - id: tool-pwsh
             name: '@deepseek-ai/dsh-tool-pwsh'
             disabled: !!js process.platform !== 'win32'
+            # Subagents get a shell here (see child-tools.mjs), so background jobs
+            # are switched off for the whole preset. This is the one place the
+            # "no long-running services" rule is enforceable rather than advisory:
+            # with enableRunInBackground false the tool refuses a background call
+            # AND omits run_in_background from its schema entirely, so no model at
+            # any depth can reach for a detached process. A server a child starts
+            # without backgrounding holds its own call until the timeout and dies
+            # with it, which is the behaviour this preset wants.
+            config:
+              enableRunInBackground: false
           - id: tool-fs
             name: '@deepseek-ai/dsh-tool-fs'
           - id: tool-fs-search
@@ -138,11 +148,13 @@ const patch = `# Generated by build-patch.mjs from persona.txt. Do not hand-edit
                   thresholdChars: 8192
                   headChars: 4096
                   tailChars: 1024
-          # Delegation. Both tools share ONE readonly mask, so every child in the
-          # tree is read-only no matter which tool produced it. maxDepth is left
-          # unset on purpose: it resolves from the Host subagent.maxDepth setting
-          # (default 1), and this preset needs unbounded depth for read-only
-          # recursion. Do not raise that Host setting to 0 while using this preset.
+          # Delegation. Both tools share ONE mask (child-tools.mjs), so every child
+          # in the tree gets the same working set — read, write, shell — no matter
+          # which tool produced it, and every child is bounded the same way.
+          # maxDepth is left unset on purpose: it resolves from the Host
+          # subagent.maxDepth setting, which is what decides how many levels exist.
+          # Raising it deepens the tree; setting it to 0 disables delegation and
+          # breaks this preset's design.
           - id: delegation
             name: cordis:group
             group: true

package/child-tools.mjs

@@ -3,27 +3,48 @@
  * the verifier, so the two cannot disagree about what a subagent may call.
  *
  * These are the only GLOBAL tools a subagent may call. Everything absent is
- * invisible to the child, including every mutation entry point.
- *
- * `subagent` is deliberately NOT here, and cannot be — but that does NOT mean a
- * subagent lacks it. Two separate facts:
- *
- *  1. With `modelSelectionSettings: true` the tool is mounted inside each composed
- *     Agent's own scope (`dsh-tool-subagent` registers it through
- *     `installScoped`), and `tools.restrict()` takes a mask of *global* tools
- *     only. It throws on a scope-local name exactly as it throws on an unknown
- *     one, which is how this bundle broke: every subagent creation failed with
- *     `tools.restrict() names unknown global tool "subagent"`.
- *  2. Restrictions only filter globals — "scoped registrations remain visible".
- *     A child inherits this preset, so it gets its own scoped `subagent` and can
- *     delegate onward until the runtime depth cap stops it.
- *
- * So the mask is not what makes a child a leaf; `subagent.maxDepth` is. Listing
- * `subagent` here rejected a name the mask can never legally contain. Do not add
- * it back; `verify-patch.mjs` asserts its absence on purpose.
+ * invisible to the child.
+ *
+ * ## What a subagent MAY do
+ *
+ * A subagent reads, **changes files, and runs commands**. It has to: a delegate
+ * that cannot create anything is not a worker, and a "read-only worker" in a code
+ * project cannot run tests, git, or a verification script, so every executable
+ * step bounces back to the root and the parallelism the tree exists for buys
+ * nothing. `write`, `edit`, `ops_replace`, `ops_bash` and `pwsh` are all in the
+ * mask for that reason.
+ *
+ * ## What is forbidden, and how it is enforced
+ *
+ * The line is not "may not change anything" — it is **unbounded processes**. A
+ * subagent must not leave a service, watcher or daemon running past its task.
+ * That is enforced, not merely advised:
  *
- * `subagent_fork` IS registered in the preset's own scope and is observable as a
- * global, so it stays in the list.
+ *  1. `enableRunInBackground: false` on the preset's `tool-pwsh` row (set in
+ *     `build-patch.mjs`). The tool then refuses a background call *and omits
+ *     `run_in_background` from its schema*, so no model at any depth can reach for
+ *     a detached process at all. Structural.
+ *  2. A persona rule covers what a schema cannot: `ops_bash` is a host tool with
+ *     no per-preset config and no job registry, so a command blocking inside it is
+ *     bounded only by the call timeout.
+ *
+ * A subagent that starts a long-running server is therefore self-limiting — the
+ * call holds until its timeout and the process dies with it.
+ *
+ * ## Why `subagent` is absent, and what that does NOT mean
+ *
+ * With `modelSelectionSettings: true` the spawn 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"`.
+ *
+ * Its absence does **not** make a child a leaf. Restrictions filter globals only —
+ * "scoped registrations remain visible" — and a child inherits this preset, so it
+ * gets its own scoped `subagent` and delegates onward until the runtime depth cap
+ * stops it. Depth is the user's setting; the mask is not a depth limit. Do not add
+ * it back; `verify-patch.mjs` asserts its absence on purpose.
  */
 export const CHILD_TOOLS = [
   'read',
@@ -36,6 +57,20 @@ export const CHILD_TOOLS = [
   'web_fetch',
   'read_image',
   'skill',
+  'write',
+  'edit',
+  'ops_replace',
+  // Running commands. `pwsh` is the one shell this profile reports as a global
+  // tool, and background jobs are switched off for it in the preset (see above).
+  //
+  // `ops_bash` is deliberately NOT here even though it looks like the natural
+  // choice on Windows: the runtime's own tool inventory — the list
+  // `tools.restrict()` prints when it refuses a name — includes
+  // ops_glob/ops_grep/ops_inspect_local_file but NOT ops_bash, so naming it breaks
+  // every child creation exactly the way `subagent` did. The dsh-ops shell
+  // component publishes it through a different path than its file component. Add
+  // it only after seeing it in your own environment's inventory line.
+  'pwsh',
   'todo_write',
   'ask_user_question',
   'get_goal',
@@ -55,8 +90,13 @@ export const CHILD_TOOLS = [
 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.
+ * The capabilities a subagent must not reach. It is deliberately no longer a list
+ * of "things that write" — a subagent is *expected* to write, so forbidding that
+ * would contradict the mask above. What it must not reach is an unbounded process,
+ * and because the shell tool is present rather than absent, the property to verify
+ * is the tool's configuration, not its absence.
  */
-export const MUTATION_TOOLS = ['write', 'edit', 'ops_replace', 'ops_bash', 'pwsh', 'bash'];
+export const FORBIDDEN_CAPABILITIES = {
+  /** The preset's `tool-pwsh` row must carry this, or a child could detach a server. */
+  pwshConfig: { enableRunInBackground: false },
+};

package/cordis.patch.yml

@@ -11,7 +11,7 @@
       config:
         id: root-planner
         name: Root Planner
-        description: Plans in a lean context, delegates reading to strictly read-only subagents, and owns every file mutation.
+        description: Keeps the plan and the decisions in the root agent, dispatches reading, edits and commands to subagent workers, and lets nothing outlive the task.
         order: 5
         plugins:
           - id: persona
@@ -42,24 +42,28 @@
                 ## 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. 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".
+                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.
+                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 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. 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. 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.
+                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.
 
                 ## Subagent rules
 
-                1. You are read-only, and this is structural rather than advisory: you have no tool that can create, modify, rename, or delete a file or directory, and no shell. Do not hunt for a workaround and do not retry a denied operation.
-                2. When the work needs a file changed, do not change it. Report the change instead: target path, exact location (file and line), current text or state, proposed replacement, and why it is needed. The root agent decides and executes.
-                3. A file change is never a silent side effect of research. Scratch artifacts, reformatting, "fixing what you noticed" along the way, and running a generator that rewrites tracked files are all forbidden under this rule; report them instead.
-                4. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
-                5. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
-                6. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for.
-                7. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree. Read the material yourself and summarize. Do not route work onward to avoid reading, and do not treat a depth rejection as a reason to give up. If you cannot finish, or the request is ambiguous and reading cannot resolve it, say so plainly and stop. Do not guess and do not invent a result.
+                1. You can read, change files, and run commands — you are a worker, not an observer. **Read the task you were given for what you may do.** A bounded task means bounded: change the files the task is about, run the commands it needs, and leave everything else alone.
+                2. **Never leave something running.** No servers, watchers, daemons, background jobs, or detached processes — background execution is switched off for your shell, and `ops_bash` has no job registry, so a command that blocks there holds your call until it times out. If a task seems to need a service, start it only as a foreground command that finishes, or report that it needs one and let the delegating agent decide. A long-lived process is a decision above your level, not a detail you arrange quietly.
+                3. Keep every change inside your task. Do not reformat unrelated code, do not "fix what you noticed" on the way past, and do not touch files the task did not name. If you find another problem, report it — do not fix it.
+                4. Do not race the other agents. Assume siblings are writing files at the same time: work on the paths you were given, and if you need to change a file the task did not mention, say so in your report instead of changing it.
+                5. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
+                6. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
+                7. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for. Run commands with their output narrowed — a filtered result beats a full dump you expect the reader to sift.
+                8. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree — **do the work yourself and say in your report that you did it directly because the tree ended there.** Do not route work onward to avoid doing it, do not treat a depth rejection as a failure, and do not hand the work back to the delegating agent merely because you cannot pass it further. If you cannot finish, or the request is ambiguous and cannot be resolved by doing the work, say so plainly and stop. Do not guess and do not invent a result.
 
                 ## When to pass work down
 
@@ -73,7 +77,9 @@
 
                 ## Reporting upward
 
-                Send the delegating agent what it needs to decide and nothing else: status, the conclusion, supporting evidence with locations, what remains uncertain, and any proposed file change in the exact form given above. Do not open with a preamble and do not close with an offer to do more.
+                Send the delegating agent what it needs to decide and nothing else: status, the conclusion, supporting evidence with locations, what remains uncertain, and — for anything you changed — exactly which files and what changed in them. Do not open with a preamble and do not close with an offer to do more.
+
+                If the workspace has its own conventions for recording changes — a change log, a per-directory register, a commit message format — follow them only if your task told you to. Otherwise report what those conventions require alongside your result, so the agent that owns the record can write it: a worker that both changes files and decides how the change is recorded has moved the decision without saying so.
           - id: agent-instructions
             name: '@deepseek-ai/dsh-agent-instructions'
             config:
@@ -84,6 +90,16 @@
           - id: tool-pwsh
             name: '@deepseek-ai/dsh-tool-pwsh'
             disabled: !!js process.platform !== 'win32'
+            # Subagents get a shell here (see child-tools.mjs), so background jobs
+            # are switched off for the whole preset. This is the one place the
+            # "no long-running services" rule is enforceable rather than advisory:
+            # with enableRunInBackground false the tool refuses a background call
+            # AND omits run_in_background from its schema entirely, so no model at
+            # any depth can reach for a detached process. A server a child starts
+            # without backgrounding holds its own call until the timeout and dies
+            # with it, which is the behaviour this preset wants.
+            config:
+              enableRunInBackground: false
           - id: tool-fs
             name: '@deepseek-ai/dsh-tool-fs'
           - id: tool-fs-search
@@ -138,11 +154,13 @@
                   thresholdChars: 8192
                   headChars: 4096
                   tailChars: 1024
-          # Delegation. Both tools share ONE readonly mask, so every child in the
-          # tree is read-only no matter which tool produced it. maxDepth is left
-          # unset on purpose: it resolves from the Host subagent.maxDepth setting
-          # (default 1), and this preset needs unbounded depth for read-only
-          # recursion. Do not raise that Host setting to 0 while using this preset.
+          # Delegation. Both tools share ONE mask (child-tools.mjs), so every child
+          # in the tree gets the same working set — read, write, shell — no matter
+          # which tool produced it, and every child is bounded the same way.
+          # maxDepth is left unset on purpose: it resolves from the Host
+          # subagent.maxDepth setting, which is what decides how many levels exist.
+          # Raising it deepens the tree; setting it to 0 disables delegation and
+          # breaks this preset's design.
           - id: delegation
             name: cordis:group
             group: true
@@ -172,6 +190,10 @@
                       - web_fetch
                       - read_image
                       - skill
+                      - write
+                      - edit
+                      - ops_replace
+                      - pwsh
                       - todo_write
                       - ask_user_question
                       - get_goal
@@ -199,6 +221,10 @@
                       - web_fetch
                       - read_image
                       - skill
+                      - write
+                      - edit
+                      - ops_replace
+                      - pwsh
                       - todo_write
                       - ask_user_question
                       - get_goal

package/docs/DEVELOPMENT.md

@@ -26,6 +26,8 @@ Paths below are relative to the repository root; this file lives in `docs/`.
 | `cordis.patch.yml` | Generated. Do not hand-edit — regenerate instead. |
 | `lib-yaml.mjs` | Resolves a YAML parser from the local DSH installation, so the scripts need no dependencies. |
 | `verify-patch.mjs` | Parses the generated patch and checks persona integrity, role wiring, and the child mask. |
+| `child-tools.mjs` | The child mask, defined once so the generator and the verifier cannot disagree. |
+| `tools/inspect-sessions.mjs` | Forensics for a real run: prints each session's `agentPreset`, delegation depth and tool inventory from the `.jsonl.zstd` logs. Use it before trusting any claim about what a run did — an apparent bundle defect turned out twice to be the *root* session composed with a different preset. |
 | `verify-depth-override.mjs` | Checks that the profile patch layer still parses and that the `subagent` depth override landed in the composed profile. |
 | `package.json` | Bundle manifest (`dsh.bundle.patch`). |
 | `.gitattributes` | Pins LF; without it a Windows checkout breaks the byte-identity check. |
@@ -230,5 +232,7 @@ directory is not read. `CLAUDE.md` is loaded with the same candidates, and ident
 sibling files render once.
 
 The persona carries one precedence clause instead of the conventions themselves:
-project files apply, but the subagent read-only rule wins where they conflict,
-because the runtime enforces it and a project file cannot.
+project files apply, but the subagent's task bound wins where they conflict —
+a worker changes the files its task names and nothing else, and that is enforced by
+the runtime's tool grant plus the persona, neither of which a project file can
+override.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "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,24 +21,28 @@ 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. 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".
+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.
+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 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. 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. 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.
+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.
 
 ## Subagent rules
 
-1. You are read-only, and this is structural rather than advisory: you have no tool that can create, modify, rename, or delete a file or directory, and no shell. Do not hunt for a workaround and do not retry a denied operation.
-2. When the work needs a file changed, do not change it. Report the change instead: target path, exact location (file and line), current text or state, proposed replacement, and why it is needed. The root agent decides and executes.
-3. A file change is never a silent side effect of research. Scratch artifacts, reformatting, "fixing what you noticed" along the way, and running a generator that rewrites tracked files are all forbidden under this rule; report them instead.
-4. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
-5. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
-6. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for.
-7. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree. Read the material yourself and summarize. Do not route work onward to avoid reading, and do not treat a depth rejection as a reason to give up. If you cannot finish, or the request is ambiguous and reading cannot resolve it, say so plainly and stop. Do not guess and do not invent a result.
+1. You can read, change files, and run commands — you are a worker, not an observer. **Read the task you were given for what you may do.** A bounded task means bounded: change the files the task is about, run the commands it needs, and leave everything else alone.
+2. **Never leave something running.** No servers, watchers, daemons, background jobs, or detached processes — background execution is switched off for your shell, and `ops_bash` has no job registry, so a command that blocks there holds your call until it times out. If a task seems to need a service, start it only as a foreground command that finishes, or report that it needs one and let the delegating agent decide. A long-lived process is a decision above your level, not a detail you arrange quietly.
+3. Keep every change inside your task. Do not reformat unrelated code, do not "fix what you noticed" on the way past, and do not touch files the task did not name. If you find another problem, report it — do not fix it.
+4. Do not race the other agents. Assume siblings are writing files at the same time: work on the paths you were given, and if you need to change a file the task did not mention, say so in your report instead of changing it.
+5. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
+6. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
+7. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for. Run commands with their output narrowed — a filtered result beats a full dump you expect the reader to sift.
+8. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree — **do the work yourself and say in your report that you did it directly because the tree ended there.** Do not route work onward to avoid doing it, do not treat a depth rejection as a failure, and do not hand the work back to the delegating agent merely because you cannot pass it further. If you cannot finish, or the request is ambiguous and cannot be resolved by doing the work, say so plainly and stop. Do not guess and do not invent a result.
 
 ## When to pass work down
 
@@ -52,4 +56,6 @@ A delegated task is not delegated again: hand a given question to at most one ag
 
 ## Reporting upward
 
-Send the delegating agent what it needs to decide and nothing else: status, the conclusion, supporting evidence with locations, what remains uncertain, and any proposed file change in the exact form given above. Do not open with a preamble and do not close with an offer to do more.
+Send the delegating agent what it needs to decide and nothing else: status, the conclusion, supporting evidence with locations, what remains uncertain, and — for anything you changed — exactly which files and what changed in them. Do not open with a preamble and do not close with an offer to do more.
+
+If the workspace has its own conventions for recording changes — a change log, a per-directory register, a commit message format — follow them only if your task told you to. Otherwise report what those conventions require alongside your result, so the agent that owns the record can write it: a worker that both changes files and decides how the change is recorded has moved the decision without saying so.

package/tools/inspect-sessions.mjs

@@ -0,0 +1,71 @@
+// Forensics on the real root-planner test run: which preset did the root session
+// compose with, and what tools did each level actually receive?
+//
+// Usage: node inspect-sessions.mjs <rootSessionDir> [childSessionDir ...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { zstdDecompressSync } from 'node:zlib';
+
+/** Read one .jsonl.zstd session log into parsed events. */
+function readSession(dir) {
+  const raw = zstdDecompressSync(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  return raw
+    .toString('utf8')
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return undefined;
+      }
+    })
+    .filter(Boolean);
+}
+
+for (const dir of process.argv.slice(2)) {
+  const events = readSession(dir);
+  const types = new Map();
+  for (const event of events) types.set(event.type, (types.get(event.type) ?? 0) + 1);
+
+  process.stdout.write(`\n===== ${dir.split(/[\\/]/).pop()} — ${events.length} events =====\n`);
+  process.stdout.write(`event types: ${[...types.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12).map(([t, n]) => `${t}×${n}`).join(', ')}\n`);
+
+  // Session header: the composition that was actually in force.
+  for (const event of events) {
+    if (event.type === 'session/header' || event.type === 'session/start') {
+      const h = event.data ?? event;
+      process.stdout.write(
+        `header: origin=${h.header?.origin ?? h.origin} parent=${h.header?.parentSession ?? h.parentSession} ` +
+          `depth=${h.header?.delegationDepth ?? h.delegationDepth} preset=${h.preset ?? h.presetId ?? '(not in header)'}\n`,
+      );
+    }
+  }
+
+  // Tool names actually offered to this session, from its request payloads.
+  const offered = new Set();
+  for (const event of events) {
+    const message = event.data?.request?.messages ?? event.request?.messages;
+    if (!Array.isArray(message)) continue;
+    for (const entry of message) {
+      if (entry?.role !== 'system') continue;
+      const text = typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content);
+      for (const match of text.matchAll(/"name":\s*"([a-z_0-9]+)"/g)) offered.add(match[1]);
+    }
+  }
+  if (offered.size > 0) {
+    process.stdout.write(`tools seen in request payloads (${offered.size}): ${[...offered].sort().join(', ')}\n`);
+  }
+
+  // Any tool error mentioning a mask or an executor.
+  for (const event of events) {
+    const text = JSON.stringify(event);
+    for (const needle of ['unknown global tool', 'EXECUTOR_UNAVAILABLE', 'SubagentDepthError', 'exceeds maxDepth']) {
+      if (text.includes(needle)) {
+        const start = Math.max(0, text.indexOf(needle) - 220);
+        process.stdout.write(`  [${needle}] …${text.slice(start, text.indexOf(needle) + 220)}…\n`);
+      }
+    }
+  }
+}

package/tools/verify-session.mjs

@@ -0,0 +1,177 @@
+// Verifies a real root-planner run from its own session logs.
+//
+// Why this exists: twice now, a conclusion about this preset was drawn from a run
+// whose ROOT session was composed with a different preset (the children were
+// root-planner while the root was `standard`), so every rule and permission in the
+// tree was mismatched — and the run looked like a bundle defect. Reading the logs
+// is the only way to tell. This script does it mechanically.
+//
+// Usage:
+//   node tools/verify-session.mjs <session-dir> [--expect-depth N] [--quiet]
+//
+// <session-dir> is the ROOT session directory under
+// ~/.dsh/sessions/<cwd-slug>/ ; child directories sitting beside it are found by
+// parentSession, so pass only the root.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/**
+ * Decompress a concatenated-zstd file. The session logs are appended frame by
+ * frame, and a single decompress call stops at the first frame — which yields a
+ * 300-byte file out of an 85 KB one and silently hides every event.
+ * @param {Buffer} buf - whole file.
+ * @returns {Promise<string>} the complete decompressed text.
+ */
+async function decompressAll(buf) {
+  const out = [];
+  let rest = buf;
+  for (;;) {
+    const 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(rest);
+    });
+    if (text.length === 0) break;
+    out.push(text);
+    // Each frame's decompressed size is not exposed; feed the remainder in and let
+    // the next frame fail once the buffer is exhausted.
+    const consumed = frameBytes(rest, text.length);
+    if (consumed === undefined || consumed >= rest.length) break;
+    rest = rest.subarray(consumed);
+  }
+  return out.join('');
+}
+
+/** Locate the end of the first zstd frame by magic-number scanning. */
+function frameBytes(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 undefined;
+}
+
+/** Read one session directory into {header, events}. */
+async function readSession(dir) {
+  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 [];
+      }
+    });
+  return { header: events[0], events };
+}
+
+const argv = process.argv.slice(2);
+const quiet = argv.includes('--quiet');
+const expectDepthIndex = argv.indexOf('--expect-depth');
+const expectDepth = expectDepthIndex === -1 ? undefined : Number(argv[expectDepthIndex + 1]);
+const rootDir = argv.find((arg) => !arg.startsWith('--') && !/^\d+$/.test(arg));
+
+if (rootDir === undefined) {
+  process.stderr.write('usage: node tools/verify-session.mjs <root-session-dir> [--expect-depth N]\n');
+  process.exit(2);
+}
+
+const base = join(rootDir, '..');
+const root = await readSession(rootDir);
+
+const sessions = [{ dir: rootDir, ...root }];
+for (const name of readdirSync(base)) {
+  if (name === rootDir.split(/[\\/]/).pop()) continue;
+  const candidate = join(base, name);
+  try {
+    if (!statSync(join(candidate, 'session.v4.jsonl.zstd')).isFile()) continue;
+  } catch {
+    continue;
+  }
+  const session = await readSession(candidate);
+  // Only real children count. Sibling ROOT sessions of other conversations live in
+  // the same directory and have no parentSession — including them made the report
+  // claim the run failed when it had not.
+  if (session.header?.origin !== 'subagent') continue;
+  sessions.push({ dir: candidate, ...session });
+}
+
+const failures = [];
+const check = (ok, label) => {
+  if (ok) {
+    if (!quiet) process.stdout.write(`ok   ${label}\n`);
+  } else {
+    process.stdout.write(`FAIL ${label}\n`);
+    failures.push(label);
+  }
+};
+
+if (!quiet) process.stdout.write(`root session: ${root.header?.id}\n`);
+
+check(
+  root.header?.agentPreset === 'root-planner',
+  `root session is composed with root-planner (found "${root.header?.agentPreset ?? '?'}") — if this fails, the run proves nothing about the preset`,
+);
+check(root.header?.delegationDepth === 0, `root is at depth 0 (found ${root.header?.delegationDepth})`);
+
+const children = sessions.filter((session) => session.header?.parentSession === root.header?.id);
+const byId = new Map(sessions.map((session) => [session.header?.id, session]));
+const depths = new Map([[root.header?.id, 0]]);
+const depthOf = (session) => {
+  const known = depths.get(session.header?.id);
+  if (known !== undefined) return known;
+  const parent = byId.get(session.header?.parentSession);
+  const value = parent === undefined ? 1 : depthOf(parent) + 1;
+  depths.set(session.header?.id, value);
+  return value;
+};
+
+if (!quiet) {
+  process.stdout.write(`\n${sessions.length} session(s) total:\n`);
+  for (const session of sessions) {
+    process.stdout.write(
+      `  ${String(session.header?.id).slice(0, 20)}  preset=${String(session.header?.agentPreset).padEnd(14)} ` +
+        `depth=${depthOf(session)}  parent=${String(session.header?.parentSession ?? '(root)').slice(0, 20)}\n`,
+    );
+  }
+  process.stdout.write('\n');
+}
+
+const descendants = sessions.filter((session) => session !== sessions[0]);
+check(descendants.length > 0, 'the root actually delegated (at least one child session exists)');
+
+for (const session of descendants) {
+  const depth = depthOf(session);
+  check(
+    session.header?.agentPreset === 'root-planner',
+    `child ${String(session.header?.id).slice(0, 8)} at depth ${depth} inherits root-planner (found "${session.header?.agentPreset ?? '?'}")`,
+  );
+}
+
+const maxDepth = Math.max(0, ...[...sessions].map((session) => depthOf(session)));
+if (expectDepth !== undefined) {
+  check(maxDepth === expectDepth, `deepest session is depth ${expectDepth} (found ${maxDepth})`);
+}
+
+// A delegation attempted from a leaf is the depth cap doing its job, not a defect.
+let capped = 0;
+for (const session of sessions) {
+  const text = JSON.stringify(session.events);
+  for (const needle of ['exceeds maxDepth', 'SubagentDepthError', 'unknown global tool']) {
+    if (text.includes(needle)) capped += 1;
+  }
+}
+if (!quiet && capped > 0) process.stdout.write(`note: ${capped} depth-cap or mask rejection(s) recorded in the logs\n`);
+
+process.stdout.write(
+  failures.length === 0
+    ? `\nVERIFIED: root and all ${descendants.length} descendant session(s) used root-planner; max depth ${maxDepth}.\n`
+    : `\n${failures.length} CHECK(S) FAILED — this run does not demonstrate the preset.\n`,
+);
+process.exit(failures.length === 0 ? 0 : 1);

package/verify-patch.mjs

@@ -2,15 +2,17 @@
 //  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 names only global tools, excludes every mutation entry
-//     point, and excludes agent-scoped names that tools.restrict() would reject.
+//  4. the child tool mask names only global tools, keeps the write and shell tools
+//     a worker needs, and excludes agent-scoped names tools.restrict() would reject,
+//  5. the "no unbounded process" property holds: the preset's pwsh row has
+//     background jobs switched off.
 //
 // 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 { CHILD_TOOLS, FORBIDDEN_CAPABILITIES, SCOPE_LOCAL_TOOLS } from './child-tools.mjs';
 import { loadYaml, loaderSchema as makeLoaderSchema } from './lib-yaml.mjs';
 
 const yaml = loadYaml();
@@ -54,7 +56,11 @@ check(personaRow?.config?.suffix === 'Your working directory is {{cwd}}.', 'pers
 const expected = readFileSync(join(here, 'persona.txt'), 'utf8').replace(/\r\n/g, '\n').trimEnd();
 check(personaRow?.config?.prefix === expected, 'parsed persona is byte-identical to persona.txt');
 check(!personaRow?.config?.prefix?.includes('\t'), 'persona contains no tab characters');
-check(/read-only/.test(personaRow?.config?.prefix ?? ''), 'persona states the read-only rule for subagents');
+check(/read-only/.test(personaRow?.config?.prefix ?? '') === false, 'persona no longer claims subagents are read-only (they are workers with write and shell)');
+check(
+  /Never leave something running/.test(personaRow?.config?.prefix ?? ''),
+  'persona forbids long-running processes for subagents',
+);
 
 const delegation = plugins.find((row) => row.id === 'delegation');
 check(delegation?.group === true, 'delegation is a group row');
@@ -71,13 +77,14 @@ const childTools = [
   return { id, toolName, allow: row?.config?.toolFilter?.allow };
 });
 
-// The mask must deny every mutation entry point, and it can only name global tools.
+// A subagent is a worker: it keeps the write and shell tools, so the mask must
+// only exclude what a mask can name and what would unbounded a child's process.
 for (const { id, allow } of childTools) {
   check(Array.isArray(allow) && allow.length > 0, `${id} declares a non-empty allow list`);
-  for (const denied of MUTATION_TOOLS) {
-    check(!allow?.includes(denied), `${id} mask excludes ${denied}`);
-  }
   check(allow?.includes('read'), `${id} mask keeps read`);
+  for (const worker of ['write', 'edit', 'ops_replace', 'pwsh']) {
+    check(allow?.includes(worker), `${id} mask keeps ${worker} (a subagent must be able to work)`);
+  }
   for (const scoped of SCOPE_LOCAL_TOOLS) {
     check(
       !allow?.includes(scoped),
@@ -86,6 +93,16 @@ for (const { id, allow } of childTools) {
   }
 }
 
+// "No unbounded process": with the shell tools present, the property lives in the
+// preset's own rows rather than in the mask.
+const pwshRow = plugins.find((row) => row.id === 'tool-pwsh');
+check(pwshRow !== undefined, 'the preset declares tool-pwsh');
+check(
+  pwshRow?.config?.enableRunInBackground === FORBIDDEN_CAPABILITIES.pwshConfig.enableRunInBackground,
+  `tool-pwsh sets enableRunInBackground=${FORBIDDEN_CAPABILITIES.pwshConfig.enableRunInBackground} ` +
+    `(found ${JSON.stringify(pwshRow?.config?.enableRunInBackground)}) — without it a subagent could detach a server`,
+);
+
 /**
  * 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