dsh-root-planner-preset 1.1.5 → 1.1.7

package/README.md

@@ -122,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

@@ -102,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**，那是注册表的输出，不是模型的回忆：
 
-**仍未验证**：**还没有一次成功的子代理派出。** 递归按上面的理由**应当**可用——子代理继承预设、因此拥有自己的作用域 `subagent`，而限制不会隐藏作用域注册——但这个推理恰好就是本包已经错过一次的那类推理。在有人报告"两层委派成功"之前，请当作未确认。
+| 性质 | 证据 |
+|---|---|
+| 白名单覆盖每一层 | 根被提供 **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`，不是白名单。
+
+**想自己核**：`tools/verify-session.mjs` 能证明每个会话跑的是哪个预设、深度多少，但它不读工具 schema。逐层工具清单用 `tools/extract-offered-tools.mjs`，进程边界用 `tools/check-pwsh-background.mjs`，实际调用用 `tools/count-tool-calls.mjs`。
 
 ## 参与维护
 

package/cordis.patch.yml

@@ -52,8 +52,9 @@
                 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.
+                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. **One writer per path, always:** if two subtasks genuinely need to modify the same file, run them one after the other rather than together, and never let two agents own the same output directory.
+                13. Reuse a child before spawning a new one. A finished child still holds everything it read, and `send_message` starts another turn in that same context — so a follow-up about the same material belongs there, not in a fresh agent that must read it all again. Sessions are isolated and a sibling cannot be told what another one already read, so overlapping reads across agents are a real cost you pay twice: once in tokens and once in the chance that two agents report the same file differently. When several subtasks need the same document, give them to one agent, or read it yourself and pass the conclusion down.
+                14. 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.5",
+  "version": "1.1.7",
   "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

@@ -31,8 +31,9 @@ Reading is not planning. Raw file contents and raw query results belong in the a
 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.
+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. **One writer per path, always:** if two subtasks genuinely need to modify the same file, run them one after the other rather than together, and never let two agents own the same output directory.
+13. Reuse a child before spawning a new one. A finished child still holds everything it read, and `send_message` starts another turn in that same context — so a follow-up about the same material belongs there, not in a fresh agent that must read it all again. Sessions are isolated and a sibling cannot be told what another one already read, so overlapping reads across agents are a real cost you pay twice: once in tokens and once in the chance that two agents report the same file differently. When several subtasks need the same document, give them to one agent, or read it yourself and pass the conclusion down.
+14. 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

@@ -271,13 +271,33 @@ if (dryRun || skipInstall) {
 // ── CI ───────────────────────────────────────────────────────────────────────
 if (!dryRun && !skipGh) {
   step('Wait for CI on the pushed commit');
+  const repo = 'XiaoOu2024/dsh-root-planner-preset';
   const sha = git('rev-parse', 'HEAD');
-  const waited = run(
-    GH,
-    ['run', 'watch', sha, '--repo', 'XiaoOu2024/dsh-root-planner-preset', '--exit-status'],
-    { allowFailure: true },
-  );
-  process.stdout.write(`  ${waited.trim().split('\n').slice(-2).join('\n  ') || '(no output)'}\n`);
+  // `gh run watch <sha>` is wrong: the bare argument is a run ID, so a commit hash
+  // returns HTTP 404. Select the run by commit, then watch it by ID; if no run has
+  // registered yet, say so rather than reporting a failure that never happened.
+  let runId;
+  for (let attempt = 1; attempt <= 12 && runId === undefined; attempt += 1) {
+    const listed = run(
+      GH,
+      ['run', 'list', '--repo', repo, '--commit', sha, '--limit', '1', '--json', 'databaseId'],
+      { allowFailure: true },
+    );
+    try {
+      const [first] = JSON.parse(listed.trim() || '[]');
+      if (first?.databaseId !== undefined) runId = String(first.databaseId);
+    } catch {
+      /* the run has not registered yet */
+    }
+    if (runId === undefined) await new Promise((resolve) => setTimeout(resolve, 10_000));
+  }
+  if (runId === undefined) {
+    process.stdout.write(`  no CI run registered for ${sha.slice(0, 8)} within 2 minutes; check it by hand\n`);
+  } else {
+    const waited = run(GH, ['run', 'watch', runId, '--repo', repo, '--exit-status'], { allowFailure: true });
+    const tail = waited.trim().split('\n').filter((line) => line.trim().length > 0).slice(-2);
+    process.stdout.write(`  ${tail.join('\n  ') || `run ${runId} finished`}\n`);
+  }
 }
 
 step(dryRun ? 'Dry run complete — nothing was changed' : `Released ${manifest.name}@${version}`);

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

package/tools/measure-read-overlap.mjs

@@ -0,0 +1,134 @@
+// Measures cross-agent read overlap in a real run: how many files were read by more
+// than one agent, and how much redundant reading that represents.
+//
+// The question this answers: sessions are isolated, so a parent cannot pass "what I
+// already read" to a sibling. Is that redundancy a rounding error or the dominant
+// cost of the fan-out? Only the logs can say.
+//
+// Usage: node tools/measure-read-overlap.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;
+}
+
+const READ_TOOLS = new Set(['read', 'ops_inspect_local_file']);
+
+/** Normalize a path argument so the same file spelled two ways counts once. */
+function normalize(value) {
+  if (typeof value !== 'string') return undefined;
+  return value.replace(/\\/g, '/').toLowerCase().trim();
+}
+
+/**
+ * Read one tool call's arguments. The log stores them as a JSON *string*, not as an
+ * object — reading `arguments.path` off it silently yields nothing, which made the
+ * first version of this tool report zero overlap on a run full of reads.
+ * @param data - the `tool/call` event's data.
+ * @returns the parsed arguments, or an empty object.
+ */
+function parseArguments(data) {
+  const raw = data?.arguments ?? data?.message?.arguments;
+  if (typeof raw === 'object' && raw !== null) return raw;
+  if (typeof raw !== 'string') return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Pull (agent, path) read pairs out of one session log. */
+async function readsOf(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 [];
+      }
+    });
+  const header = events[0];
+  const reads = [];
+  for (const event of events) {
+    if (event.type !== 'tool/call') continue;
+    const name = event.data?.name ?? event.data?.message?.name;
+    if (!READ_TOOLS.has(name)) continue;
+    const args = parseArguments(event.data);
+    const path = args.path ?? args.file_path;
+    const norm = normalize(path);
+    if (norm !== undefined) reads.push({ path: norm, depth: header?.delegationDepth });
+  }
+  return { id: dir.split(/[\\/]/).pop(), depth: header?.delegationDepth, reads };
+}
+
+const sessions = [];
+for (const dir of process.argv.slice(2)) sessions.push(await readsOf(dir));
+
+/** How many distinct agents touched each file. */
+const byPath = new Map();
+for (const session of sessions) {
+  for (const path of new Set(session.reads.map((r) => r.path))) {
+    const list = byPath.get(path) ?? [];
+    list.push(session.id.slice(0, 8));
+    byPath.set(path, list);
+  }
+}
+
+const totalReads = sessions.reduce((sum, s) => sum + s.reads.length, 0);
+const shared = [...byPath.entries()].filter(([, agents]) => agents.length > 1);
+const sharedReads = sessions.reduce(
+  (sum, s) => sum + s.reads.filter((r) => (byPath.get(r.path)?.length ?? 0) > 1).length,
+  0,
+);
+
+process.stdout.write(`\n${sessions.length} session(s), ${totalReads} read calls, ${byPath.size} distinct paths\n`);
+process.stdout.write(
+  `paths read by more than one agent: ${shared.length} (${((shared.length / Math.max(1, byPath.size)) * 100).toFixed(1)}% of paths)\n`,
+);
+process.stdout.write(
+  `read calls that hit a path another agent also read: ${sharedReads} (${((sharedReads / Math.max(1, totalReads)) * 100).toFixed(1)}% of reads)\n`,
+);
+
+const worst = shared.sort((a, b) => b[1].length - a[1].length).slice(0, 12);
+if (worst.length > 0) {
+  process.stdout.write('\nmost shared paths:\n');
+  for (const [path, agents] of worst) {
+    process.stdout.write(`  ${String(agents.length)}× ${path.slice(-96)}\n`);
+  }
+}

package/verify-patch.mjs

@@ -62,6 +62,30 @@ check(
   'persona forbids long-running processes for subagents',
 );
 
+/**
+ * Rule count, asserted on purpose.
+ *
+ * Byte-identity above only proves the patch matches `persona.txt` in the working
+ * tree. It says nothing about what was PUBLISHED: 1.1.6 shipped a package.json bump
+ * while the two collaboration rules added in the same session stayed in the working
+ * tree, so npm carried a 13-rule persona while the repository had 14. The byte check
+ * could not see that, because both files agreed with each other.
+ *
+ * Update this number in the same commit as the rule it counts, so the release is the
+ * act that carries it.
+ */
+const ROOT_RULE_COUNT = 14;
+const rootSection = (personaRow?.config?.prefix ?? '').split('## Root agent rules')[1]?.split('## Subagent rules')[0] ?? '';
+const rootRules = [...rootSection.matchAll(/^(\d+)\. /gm)].map((match) => Number(match[1]));
+check(
+  rootRules.length === ROOT_RULE_COUNT,
+  `persona carries ${ROOT_RULE_COUNT} root rules (found ${rootRules.length})`,
+);
+check(
+  rootRules.every((value, index) => value === index + 1),
+  `root rule numbering is 1..${rootRules.length} with no gaps or repeats (found ${rootRules.join(',')})`,
+);
+
 const delegation = plugins.find((row) => row.id === 'delegation');
 check(delegation?.group === true, 'delegation is a group row');
 const delegationRows = delegation?.config ?? [];