@maxiaochao/pi-toolkit 0.11.0 → 0.11.3

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 2026-10-12 - v0.11.3
+
+- harden coordinated publishing and make local release checks authoritative
+
+## Unreleased
+
+- Replace split child/root publishing with one idempotent root-tag workflow, make final-version local checks authoritative, keep CI publication-only, and remove timing-sensitive Herdr lifecycle assertions.
+
+## 2026-10-12 - v0.11.2
+
+- bundle herdr-subagents v0.4.12: enable codemode for child agents while preserving persona tool boundaries
+- Enable `codemode` for bundled Herdr Subagents children while preserving persona tool boundaries.
+
+## 2026-10-12 - v0.11.1
+
+- bundle herdr-subagents v0.4.11: add architecture documentation and clear-output guidance evaluation
+
 ## 2026-10-12 - v0.11.0
 
 - bundle worktree v0.4.0: Replace CLI start and prepare with the create-only command

package/evaluations/agents-md/README.md

@@ -0,0 +1,19 @@
+# AGENTS.md Clear Output Evaluation
+
+This A/B evaluation measures the effect of the `Clear Output` guidance. The `before` variant uses a minimal coding-assistant prompt. The `after` variant adds only the two `Clear Output` rules.
+
+Run the deterministic scorer tests:
+
+```bash
+npm run eval:agents:test
+```
+
+Run the model evaluation:
+
+```bash
+npm run eval:agents -- --runs 2
+```
+
+Set `PI_EVAL_MODEL` or pass `--model <provider/model>` to pin a model. Results are written to `results/latest.json` and `results/latest.md`.
+
+The scorer measures sentence length, conjunction density, response language, terminology changes, and use of a visual for the branching-flow case. These are proxies. Review the saved outputs for correctness and completeness before accepting a prompt change.

package/evaluations/agents-md/run.mjs

@@ -0,0 +1,217 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const CLEAR_OUTPUT = `## Clear Output
+
+- Make outputs easy to understand and verify. Use ASD-STE100-inspired principles: short sentences, one idea per sentence, and consistent terms. Apply its formal language rules only to English.
+- When it improves understanding, use a diagram, HTML artifact, or video instead of long prose.`;
+
+const BASE_SYSTEM = "You are an expert coding assistant. Give a direct and accurate answer. Reply in the same language as the user.";
+
+export const variants = {
+  before: BASE_SYSTEM,
+  after: `${BASE_SYSTEM}\n\n${CLEAR_OUTPUT}`,
+};
+
+export const cases = [
+  {
+    id: "english-explanation",
+    language: "en",
+    prompt: "Explain how optimistic concurrency control prevents lost updates. Include the read, write, conflict, and retry stages. Write for an application developer.",
+  },
+  {
+    id: "chinese-explanation",
+    language: "zh",
+    prompt: "向应用开发者解释乐观并发控制如何防止更新丢失。需要涵盖读取、写入、冲突和重试阶段。",
+  },
+  {
+    id: "term-consistency",
+    language: "en",
+    aliases: ["work item", "job", "task"],
+    prompt: "A queue API uses job, task, and work item for the same object. Explain its lifecycle from creation through processing to completion. Resolve the naming ambiguity in your answer.",
+  },
+  {
+    id: "visual-flow",
+    language: "en",
+    expectVisual: true,
+    prompt: "Explain this request flow: gateway to authentication; failed authentication to rejection; successful authentication to cache; cache miss to database; transient database failure retries twice, then returns an error. Make the branching and retry path easy to verify.",
+  },
+];
+
+function splitSentences(text) {
+  return [...new Intl.Segmenter(undefined, { granularity: "sentence" }).segment(text)]
+    .map(({ segment }) => segment.trim())
+    .filter(Boolean);
+}
+
+function tokenCount(sentence, language) {
+  if (language === "zh") {
+    return (sentence.match(/[\p{Script=Han}]|[A-Za-z0-9]+/gu) ?? []).length;
+  }
+  return (sentence.match(/[\p{L}\p{N}]+(?:[-'][\p{L}\p{N}]+)*/gu) ?? []).length;
+}
+
+export function scoreOutput(text, testCase) {
+  const sentences = splitSentences(text);
+  const lengths = sentences.map((sentence) => tokenCount(sentence, testCase.language));
+  const limit = testCase.language === "zh" ? 35 : 25;
+  const conjunctionPattern = testCase.language === "zh"
+    ? /(?:而且|但是|同时|以及|并且|然而|其中)/g
+    : /\b(?:and|but|while|whereas|which|although|however)\b/gi;
+  const conjunctions = sentences.reduce(
+    (sum, sentence) => sum + (sentence.match(conjunctionPattern) ?? []).length,
+    0,
+  );
+  const firstParagraphEnd = text.indexOf("\n\n");
+  const bodyAfterNaming = firstParagraphEnd >= 0
+    ? text.slice(firstParagraphEnd + 2)
+    : sentences.slice(1).join(" ");
+  const usedAliasesAfterNaming = (testCase.aliases ?? []).filter((alias) =>
+    new RegExp(`\\b${alias.replaceAll(" ", "\\s+")}s?\\b`, "i").test(bodyAfterNaming),
+  );
+  const hasVisual = /```(?:mermaid)?|(?:-->|->|→|↓|├|└)|<svg\b|<html\b|\|[^\n]+\|[^\n]+\|/i.test(text);
+  const hanCharacters = (text.match(/[\p{Script=Han}]/gu) ?? []).length;
+  const latinWords = (text.match(/[A-Za-z]+/g) ?? []).length;
+  const languageMatches = testCase.language === "zh"
+    ? hanCharacters >= 20
+    : hanCharacters <= Math.max(5, latinWords * 0.05);
+
+  return {
+    characters: text.length,
+    sentences: sentences.length,
+    averageSentenceTokens: lengths.length
+      ? Number((lengths.reduce((sum, value) => sum + value, 0) / lengths.length).toFixed(1))
+      : 0,
+    longSentenceRate: lengths.length
+      ? Number((lengths.filter((value) => value > limit).length / lengths.length).toFixed(2))
+      : 0,
+    conjunctionsPerSentence: lengths.length
+      ? Number((conjunctions / lengths.length).toFixed(2))
+      : 0,
+    extraAliasesAfterNaming: Math.max(0, usedAliasesAfterNaming.length - 1),
+    languageMatches,
+    hasVisual,
+  };
+}
+
+function parseArguments(argv) {
+  const options = { runs: 1, model: process.env.PI_EVAL_MODEL };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--runs") options.runs = Number(argv[++index]);
+    else if (argv[index] === "--model") options.model = argv[++index];
+    else throw new Error(`Unknown argument: ${argv[index]}`);
+  }
+  if (!Number.isInteger(options.runs) || options.runs < 1) {
+    throw new Error("--runs must be a positive integer");
+  }
+  return options;
+}
+
+function runPi(systemPrompt, prompt, model) {
+  const args = [
+    "--print",
+    "--no-session",
+    "--no-tools",
+    "--no-extensions",
+    "--no-skills",
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--system-prompt",
+    systemPrompt,
+  ];
+  if (model) args.push("--model", model);
+  args.push("--", prompt);
+  return execFileSync("pi", args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }).trim();
+}
+
+function average(rows, key) {
+  if (rows.length === 0) return 0;
+  return Number((rows.reduce((sum, row) => sum + Number(row.score[key]), 0) / rows.length).toFixed(2));
+}
+
+export function summarize(results) {
+  return Object.fromEntries(Object.keys(variants).map((variant) => {
+    const rows = results.filter((result) => result.variant === variant);
+    const visualRows = rows.filter((result) => cases.find(({ id }) => id === result.caseId).expectVisual);
+    const terminologyRows = rows.filter((result) => cases.find(({ id }) => id === result.caseId).aliases);
+    return [variant, {
+      averageCharacters: average(rows, "characters"),
+      averageSentenceTokens: average(rows, "averageSentenceTokens"),
+      longSentenceRate: average(rows, "longSentenceRate"),
+      conjunctionsPerSentence: average(rows, "conjunctionsPerSentence"),
+      languageMatchRate: average(rows, "languageMatches"),
+      visualFlowRate: average(visualRows, "hasVisual"),
+      extraAliasesAfterNaming: average(terminologyRows, "extraAliasesAfterNaming"),
+    }];
+  }));
+}
+
+export function markdownReport(payload) {
+  const { summary } = payload;
+  const lines = [
+    "# AGENTS.md Clear Output A/B Evaluation",
+    "",
+    `Runs per case: ${payload.options.runs}`,
+    `Model override: ${payload.options.model ?? "Pi default"}`,
+    "",
+    "| Variant | Mean characters | Mean sentence tokens | Long sentence rate | Conjunctions / sentence | Language match | Visual-flow rate | Extra aliases |",
+    "|---|---:|---:|---:|---:|---:|---:|---:|",
+    ...Object.entries(summary).map(([name, score]) =>
+      `| ${name} | ${score.averageCharacters} | ${score.averageSentenceTokens} | ${score.longSentenceRate} | ${score.conjunctionsPerSentence} | ${score.languageMatchRate} | ${score.visualFlowRate} | ${score.extraAliasesAfterNaming} |`,
+    ),
+    "",
+    "Lower is better for long sentence rate, conjunctions, and extra aliases after naming. Higher is better for language match and visual-flow rate. Character count is descriptive, not a quality score.",
+    "",
+    "## Per-case output",
+    "",
+    ...payload.results.flatMap((result) => [
+      `### ${result.caseId} · ${result.variant} · run ${result.run}`,
+      "",
+      `Score: \`${JSON.stringify(result.score)}\``,
+      "",
+      result.output,
+      "",
+    ]),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const results = [];
+  for (let run = 1; run <= options.runs; run += 1) {
+    for (const testCase of cases) {
+      const order = run % 2 === 1 ? ["before", "after"] : ["after", "before"];
+      for (const variant of order) {
+        process.stderr.write(`Running ${testCase.id} / ${variant} / ${run}\n`);
+        const output = runPi(variants[variant], testCase.prompt, options.model);
+        results.push({
+          caseId: testCase.id,
+          variant,
+          run,
+          output,
+          score: scoreOutput(output, testCase),
+        });
+      }
+    }
+  }
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    options,
+    summary: summarize(results),
+    results,
+  };
+  const resultDirectory = fileURLToPath(new URL("./results", import.meta.url));
+  mkdirSync(resultDirectory, { recursive: true });
+  writeFileSync(`${resultDirectory}/latest.json`, `${JSON.stringify(payload, null, 2)}\n`);
+  writeFileSync(`${resultDirectory}/latest.md`, markdownReport(payload));
+  console.log(JSON.stringify(payload.summary, null, 2));
+  console.log(`\nFull report: ${resultDirectory}/latest.md`);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  await main();
+}

package/evaluations/agents-md/tests/run-tests.mjs

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { scoreOutput } from "../run.mjs";
+
+const concise = scoreOutput(
+  "Read the record. Compare its version. Reject a conflict. Retry the operation.",
+  { language: "en" },
+);
+assert.equal(concise.sentences, 4);
+assert.equal(concise.longSentenceRate, 0);
+assert.equal(concise.conjunctionsPerSentence, 0);
+assert.equal(concise.languageMatches, true);
+
+const dense = scoreOutput(
+  "Read the record and compare its version, but reject the write when another client changed it, while preserving the new value and returning a conflict which the caller can retry after loading the latest record.",
+  { language: "en" },
+);
+assert.equal(dense.sentences, 1);
+assert.equal(dense.longSentenceRate, 1);
+assert.ok(dense.conjunctionsPerSentence >= 4);
+
+const chinese = scoreOutput(
+  "客户端读取记录。客户端比较版本。版本冲突时，服务拒绝写入。客户端重新读取后重试。",
+  { language: "zh" },
+);
+assert.equal(chinese.sentences, 4);
+assert.equal(chinese.longSentenceRate, 0);
+assert.equal(chinese.languageMatches, true);
+
+const terms = scoreOutput(
+  "Create one work item. The worker processes the job and completes the task.",
+  { language: "en", aliases: ["work item", "job", "task"] },
+);
+assert.equal(terms.extraAliasesAfterNaming, 1);
+
+const canonicalTerm = scoreOutput(
+  "Use work item as the canonical term for job, task, and work item. Create the work item. Process the work item. Complete the work item.",
+  { language: "en", aliases: ["work item", "job", "task"] },
+);
+assert.equal(canonicalTerm.extraAliasesAfterNaming, 0);
+
+const wrongLanguage = scoreOutput("这是一个中文回答，包含足够多的中文字符，因此不应匹配英文问题。", {
+  language: "en",
+});
+assert.equal(wrongLanguage.languageMatches, false);
+
+const visual = scoreOutput("gateway --> auth --> cache\n                  ↓\n                reject", {
+  language: "en",
+  expectVisual: true,
+});
+assert.equal(visual.hasVisual, true);
+
+console.log("AGENTS.md evaluation scorer tests passed");

package/global/AGENTS.md

@@ -2,13 +2,18 @@
 
 Behavioral guidelines to reduce common LLM coding mistakes. Project-specific instructions override this file when they conflict.
 
-## 1. Think Before Coding
+## 1. Clear Output
+
+- Make outputs easy to understand and verify. Use ASD-STE100-inspired principles: short sentences, one idea per sentence, and consistent terms. Apply its formal language rules only to English.
+- When it improves understanding, use a diagram, HTML artifact, or video instead of long prose.
+
+## 2. Think Before Coding
 
 - Surface material assumptions, interpretations, and tradeoffs.
 - If unresolved ambiguity would materially change the result, ask. When no human is reachable, choose a defensible interpretation, state it, and proceed with verifiable criteria.
 - Prefer the simpler approach. Name conflicting requirements rather than silently compromising between them.
 
-## 2. Minimal Solution
+## 3. Minimal Solution
 
 Understand the problem and relevant code flow before choosing the first rung that works:
 
@@ -24,11 +29,11 @@ Understand the problem and relevant code flow before choosing the first rung tha
 - For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
 - State the ceiling and upgrade trigger of any deliberate simplification that cuts a real corner.
 
-## 3. Skill Boundaries
+## 4. Skill Boundaries
 
 After loading a skill, treat its documented interface as sufficient for normal use. Do not inspect the skill's implementation, installed executable, or package source unless the user asks to review, debug, or modify it; its documented behavior conflicts with observed behavior; or required usage details are missing from the skill.
 
-## 4. Read, Then Change Surgically
+## 5. Read, Then Change Surgically
 
 Before editing, read the affected public API and its immediate callers. For a bug, find every statically discoverable caller and relevant implementation.
 
@@ -38,23 +43,23 @@ Every changed line traces to the user's request or to a defect that request reve
 - Remove imports, variables, and functions that your changes make unused. Leave pre-existing dead code in place and mention it.
 - Fix a faulty shared function once and name affected sibling callers; if only one caller is wrong, fix that caller instead of guarding a correct shared function.
 
-## 5. Goal-Driven Execution
+## 6. Goal-Driven Execution
 
 - Turn work into checkable outcomes: reproduce bugs before fixing them, preserve behavior during refactors, and optimize against a tested reference implementation.
 - For multi-step or materially ambiguous work, state a brief plan and give every step its own verification.
 - Leave the smallest relevant runnable check for new or changed non-trivial logic. Do not introduce a test framework solely for that check.
 
-## 6. Fail Visibly
+## 7. Fail Visibly
 
 - "Completed" is wrong if anything required was silently skipped.
 - "Tests pass" is wrong if any required test was skipped or not run.
 - If a required input, file, or tool is missing, or a step is impossible under the stated constraints, report what is missing and what you need. Never fabricate it to make a check pass.
 
-## 7. Frontend Verification
+## 8. Frontend Verification
 
 For frontend feature development, load the `web-browser` skill and verify the result in a real Chrome browser through CDP. Exercise the relevant user flow with real clicks, capture screenshots of the resulting UI, and test the actual behavior before reporting completion. Static inspection or non-browser tests do not replace this verification.
 
-## 8. Worktree Isolation
+## 9. Worktree Isolation
 
 For a Git-repository task that coordinates substantial changes across multiple files or modules, or implements a feature intended for release, ask before editing whether to isolate it in a worktree. Skip the question when already in a linked worktree.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.0",
+  "version": "0.11.3",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -12,6 +12,7 @@
   ],
   "files": [
     "extensions",
+    "evaluations/agents-md",
     "packages/cache-export",
     "packages/codex-edit",
     "packages/herdr-subagents",

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -0,0 +1,407 @@
+# Herdr Subagents architecture and decision-pause design
+
+This document describes the package's current architecture, the problems exposed by failure and blocking semantics, and the target decision-pause model. Sections marked **Current** describe implemented behavior. Sections marked **Target** are an implementation plan, not the current contract.
+
+## 1. Product boundary
+
+Herdr Subagents runs ordinary interactive Pi Agents in visible Herdr panes and keeps their complete sessions and results in project-local durable records. The parent receives compact status, questions, summaries, and document paths.
+
+A batch is a resource-bounded collection of **independent tasks**:
+
+- array order controls FIFO scheduling, pane numbering, and result order;
+- `concurrency` controls how many tasks may be active at once;
+- a batch containing a write-capable persona is forced to concurrency one;
+- concurrency one does **not** express `A -> B` dependency semantics;
+- tasks that consume another task's result must be orchestrated by the parent as separate runs.
+
+The package does not currently need a DAG scheduler. If dependency workflows become a first-class product requirement, they should be introduced explicitly with dependency and skip-propagation semantics instead of inferred from array order.
+
+## 2. Architecture overview
+
+```text
+Parent Pi tool call
+        |
+        v
+Extension lifecycle and foreground handoff
+        |  extensions/herdr-subagents.ts
+        v
+Global run dispatcher ---- persisted background queue
+        |                  src/dispatcher.ts, src/queued-runs.ts
+        v
+Batch runner and bounded workers
+        |  src/batch-runner.ts
+        +---- pane allocation / Herdr Agent lifecycle
+        |     src/run-pane-allocator.ts, src/live-agent.ts, src/herdr.ts
+        +---- attempt-scoped structured report
+        |     src/attempts.ts, src/protocol.ts, src/records.ts
+        +---- durable run/task/session records
+        |     .pi/herdr-subagents/runs/<run>/...
+        v
+Aggregate status, monitor, control, recovery and cleanup
+           src/run-status.ts, src/status.ts, src/fleet*.ts,
+           src/blocking.ts, src/historical-resume.ts,
+           src/reconcile.ts, src/tab-cleanup.ts
+```
+
+### Responsibilities
+
+| Layer | Responsibility |
+| --- | --- |
+| Extension | Register tools, bind parent-session lifetime, return foreground results, send final background follow-ups. |
+| Dispatcher | Give one run ownership of the global submission lane and queue later submissions FIFO. |
+| Batch runner | Persist the run, start bounded workers, allocate one pane per task, and aggregate task results. |
+| Live Agent adapter | Start or continue an interactive Pi Agent and distinguish runtime telemetry from business reports. |
+| Records | Atomically persist run, task, turn, report, attempt, ownership, and resume state. |
+| Control | Inspect, answer, retry/continue saved work, cancel, resume history, and clean archives. |
+| Recovery | Reconcile stale owners and processes, settle abandoned work, and clean identifiable tabs. |
+| Fleet | Project durable business state plus transient runtime telemetry into the parent UI. |
+
+## 3. Authoritative state and invariants
+
+1. A matching attempt-scoped `subagent_report` is authoritative for business `completed`, `blocked`, or `failed`.
+2. Herdr `working`, `blocked`, `idle`, and `done` are transport/runtime telemetry. Herdr UI `blocked` projects to `waiting_interaction`; it does not make the business task blocked.
+3. Each task owns one pane and one Pi session. A pane is never reused by another task.
+4. A task session has at most one writer. Task resume locks enforce that invariant.
+5. Shared `run.json` changes occur under the short-lived run-state lock. An Agent turn never holds that lock.
+6. Every new prompt has a unique attempt ID. A late report from an older attempt cannot settle a newer attempt.
+7. Task and report state is persisted before it is exposed as an actionable parent result.
+8. Running work is not forcibly interrupted merely because a sibling needs a decision.
+
+## 4. Current execution flow
+
+### Submission
+
+1. Tool parameters are validated.
+2. Configuration and personas are loaded and resolved.
+3. A stable run ID is allocated.
+4. Background runs are durably queued before dispatch; foreground runs wait for the dispatcher lane.
+5. The batch runner creates `run.json`, task directories, task records, prompts, and session paths.
+6. Effective concurrency is bounded by settings and forced to one if any persona is write-capable.
+
+### Task execution
+
+Each worker repeatedly claims the next FIFO task, allocates a pane, starts an interactive Pi Agent, waits for the matching structured report, persists the result, and claims another task. A failed task does not currently stop that worker. A blocked task stops only its worker lane.
+
+### Current foreground outcomes
+
+| Event | Current foreground behavior | Queued siblings |
+| --- | --- | --- |
+| All tasks complete | Return after the whole batch settles. | Completed normally. |
+| Failure with concurrency one | Continue later tasks, then return terminal `failed` or `partial`. | Continue automatically. |
+| Failure with concurrency greater than one and unfinished siblings | Persist the failure, return early, detach the batch, and let it finish in the background. | Continue automatically. |
+| Business block | Wait for the other worker lanes to settle, then return the question and retain the dispatcher lane. | A blocked worker stops, but other workers keep claiming tasks. |
+| Herdr UI block | Keep waiting for an authoritative report while showing `waiting_interaction`. | Unchanged. |
+
+The failure and block rows are asymmetric: parallel failure gives control back promptly, while block may withhold its question until unrelated work finishes. Serial failure also assumes later tasks are independent. The target design removes both ambiguities.
+
+## 5. Dispatcher ownership in plain language
+
+The dispatcher is the global submission lane, not the task-concurrency limiter.
+
+| Operation | Meaning |
+| --- | --- |
+| `detach` | The run continues in the background but gives up the submission lane, so another run may start. |
+| `retain` | The run is waiting for a parent decision and keeps the lane; a new foreground run is rejected and a background run stays queued. |
+| `release` | A retained run is resolved or cancelled and gives up the lane. |
+
+Current parallel failure uses `detach`; current business block eventually uses `retain`.
+
+## 6. Target decision-pause model
+
+### Goal
+
+Any actionable business problem returns control to the parent immediately and stops new task dispatch until the parent decides what to do. Already-running siblings are allowed to finish safely.
+
+```text
+A reports failed or blocked
+        |
+        +---- persist task/report/attempt state
+        +---- pause new queue claims
+        +---- return pause details to the parent immediately
+        +---- retain the dispatcher lane
+        |
+B and C were already running ---- continue to a terminal report
+D and E were queued ------------- remain queued
+```
+
+"Pause" means pausing **dispatch**, not freezing an Agent process at an arbitrary instruction. Forcibly suspending or cancelling running siblings could leave tools, file writes, or external operations in an unknown state.
+
+### Run control state must be separate from task outcome
+
+The current `RunStatus` reuses task statuses and aggregates them into `running`, `blocked`, `partial`, and terminal values. That combines two different questions:
+
+1. May the scheduler dispatch more work?
+2. What outcomes have tasks produced?
+
+The target model separates them conceptually:
+
+```ts
+type RunPhase = "queued" | "running" | "paused" | "cancelling" | "settled";
+type RunOutcome = "completed" | "partial" | "failed" | "cancelled";
+```
+
+The public status projection may continue exposing `status: "paused"` for convenience, but durable control logic should use the phase. While a run is paused, some task activities may still be `running` as already-started siblings settle.
+
+### Durable pause reasons
+
+A pause is tied to a specific task attempt so stale answers cannot resolve newer work:
+
+```ts
+interface PauseReason {
+  taskId: string;
+  taskOrder: number;
+  attemptId: string;
+  kind: "blocked" | "failed";
+  resolution: "pending" | "responded" | "retried" | "continued" | "cancelled";
+  createdAt: string;
+  resolvedAt?: string;
+}
+```
+
+The durable reason should reference authoritative task/report records instead of duplicating mutable summary, question, and error text. Status and tool responses project a detailed view:
+
+```json
+{
+  "status": "paused",
+  "pauseReasons": [
+    {
+      "task": 1,
+      "kind": "failed",
+      "summary": "Authentication review failed.",
+      "error": "Provider request failed.",
+      "allowedActions": ["retry", "continue", "cancel"]
+    }
+  ]
+}
+```
+
+Multiple already-running siblings may subsequently fail or block. Their reasons accumulate. No queued task starts while any pending reason remains.
+
+### Decision actions
+
+| Reason | Action | Effect |
+| --- | --- | --- |
+| `blocked` | `respond` | Continue the same live/saved session with the answer. |
+| `failed` | `retry` | Retry or continue the selected task explicitly; never infer a task. |
+| `failed` | `continue` | Accept that task's failure and allow the run to proceed without retrying it. |
+| Any | `cancel` | Cancel running and queued work and settle the run as cancelled. |
+
+`respond` should no longer be overloaded for failed tasks once `retry` exists. This makes control intent and audit history explicit.
+
+The queue resumes only when every pending pause reason is resolved. A retry or response that blocks/fails again creates a reason for the new attempt.
+
+### Failure classification
+
+Both child-reported failures and generated terminal failures can pause a run:
+
+- valid `subagent_report(status="failed")`;
+- child process or prompt API terminal error without a valid report;
+- Agent settled without publishing a report after the grace period;
+- pane or Agent startup failure.
+
+Ambiguous prompt delivery remains `delivery_unknown` while the child is alive and must not be converted into a retryable failure. Retry safety should be projected explicitly when the implementation can prove whether a prompt was submitted; the system must never automatically replay an attempt with uncertain side effects.
+
+### Foreground handoff
+
+Failure and block should share one foreground-handoff mechanism:
+
+1. observe an actionable, durably persisted task attempt;
+2. atomically pause dispatch and register its reason;
+3. detach the parent tool-call abort signal without cancelling the run;
+4. retain dispatcher ownership;
+5. return the projected pause details immediately;
+6. keep already-running siblings and final background lifecycle tracking alive;
+7. send at most one terminal follow-up after the run eventually settles.
+
+The event-specific policy only determines allowed decisions and response rendering. It should not duplicate lifecycle, persistence, or notification machinery.
+
+## 7. Target flows
+
+### Independent parallel tasks
+
+```text
+Submit A, B, C, D with concurrency 3
+A/B/C start; D queued
+A fails
+  -> run phase paused
+  -> D remains queued
+  -> parent receives A failure immediately
+B/C continue safely
+Parent retries A, continues past A, or cancels
+  -> once all pending reasons are resolved, dispatch may resume
+```
+
+### Serial tasks
+
+```text
+Submit A, B, C with concurrency 1
+A starts; B/C queued
+A fails or blocks
+  -> run phase paused
+  -> B/C do not start
+  -> parent decides
+```
+
+This makes serial execution safer, but still does not make B consume A's result. A real `A -> B` workflow remains parent-orchestrated as separate runs.
+
+### Runtime-only Herdr block
+
+```text
+Herdr reports blocked
+  -> task remains business running
+  -> Fleet shows waiting_interaction
+  -> no decision pause yet
+Child publishes matching structured blocked report
+  -> create pause reason
+  -> return exact question
+```
+
+## 8. Configuration: keep fewer concepts, not necessarily fewer files
+
+### Current user-facing sources
+
+| Scope | Runtime settings and persona overrides | Persona definitions and prompts |
+| --- | --- | --- |
+| Project | `.pi/herdr-subagents.json` | `.pi/herdr-subagents/agents/*.md` |
+| Global | `~/.pi/agent/herdr-subagents.json` | `~/.pi/agent/herdr-subagents/agents/*.md` |
+| Package | Built-in defaults | Built-in `agents/*.md` |
+
+The two formats have distinct jobs:
+
+- JSON is suitable for environment policy and small overrides.
+- Markdown frontmatter plus body is suitable for a named persona and its system prompt.
+
+Merging them into one physical file would either put long prompts into JSON or require runtime policy to be parsed from Markdown. It would also force users to copy an entire built-in persona merely to override its model. Therefore the two physical forms should remain.
+
+### Sources of confusion to remove
+
+1. Persona Markdown and JSON both expose `model`, `thinking`, and `skills`; this is intentional override layering but must be described as one resolution pipeline.
+2. Call-level task model overrides are resolved later in `tool.ts`, after configuration loading.
+3. TypeBox validates shape while `validation.ts` validates action-dependent requirements; these are complementary but currently look like duplicated validation.
+4. Downstream modules receive partially resolved values instead of one canonical run plan.
+
+### Canonical normalization boundary
+
+All sources should be normalized once before persistence or dispatch:
+
+```text
+Built-in defaults
+  <- global JSON
+  <- project JSON
+  <- effective persona Markdown
+  <- global persona override
+  <- project persona override
+  <- call/task override
+        |
+        v
+ResolvedRunPlan + diagnostics + source metadata
+```
+
+A target canonical plan can contain only execution-ready values:
+
+```ts
+interface ResolvedRunPlan {
+  label: string;
+  requestedConcurrency: number;
+  effectiveConcurrency: number;
+  tasks: Array<{
+    name: string;
+    prompt: string;
+    persona: string;
+    access: "read" | "write";
+    model?: string;
+    thinking?: string;
+    tools?: string[];
+    skills: string[];
+    systemPrompt: string;
+  }>;
+  provenance: Record<string, string>;
+  diagnostics: string[];
+}
+```
+
+After this boundary, the batch runner, persistence, recovery, and UI should not know about global/project/package precedence.
+
+### Configuration reductions
+
+Do:
+
+- retain one JSON settings file per scope and one persona directory per scope;
+- centralize precedence and call overrides in a single `resolveRunPlan` step;
+- expose resolved values and provenance through `list/settings` diagnostics;
+- state prominently that batch tasks are independent;
+- make decision pause the safe fixed behavior rather than adding a new failure-policy option;
+- keep runtime-only Herdr states out of business configuration.
+
+Do not add now:
+
+- DAG or `dependsOn` configuration;
+- configurable `failurePolicy` variants;
+- separate block/failure handoff settings;
+- automatic retry counts;
+- configuration for dispatcher `detach`/`retain` behavior.
+
+These options would multiply state-machine branches before a demonstrated need. The safe decision gate should be the invariant.
+
+### Validation ownership
+
+- `parameters.ts`: public schema, field types, basic bounds, and model-visible descriptions.
+- `validation.ts`: cross-field and action-specific requirements.
+- `resolveRunPlan`: persona existence, precedence, capability constraints, effective concurrency, and canonical values.
+- runtime state machine: whether an action is legal for the selected run/task/attempt.
+
+This division avoids both duplicated validation and an oversized configuration loader.
+
+## 9. Implementation seams for the target model
+
+| Area | Required change |
+| --- | --- |
+| `records.ts` | Separate run phase/outcome, persist attempt-scoped pause reasons, and preserve backward-compatible reads. |
+| `run-status.ts` | Aggregate task outcomes independently from scheduler phase. |
+| `batch-runner.ts` | Add a shared dispatch gate; stop queue claims immediately when a reason is registered. |
+| `extensions/herdr-subagents.ts` | Replace failure-only early return with shared actionable-event handoff. |
+| `dispatcher.ts` | Retain paused runs and release only after resolution/cancellation; keep ownership transitions explicit. |
+| `blocking.ts` / control | Split blocked `respond` from failed `retry`; add explicit `continue`. |
+| `continue-run.ts` | Resume queued dispatch only when no pending reason remains. |
+| `reconcile.ts` | Recover paused runs and cancel them when their owning parent session disappears. |
+| `status.ts` / Fleet | Show pause reasons, allowed actions, and still-running sibling activity together. |
+| `parameters.ts` / `validation.ts` | Add `retry` and `continue`, clarify independent-task semantics. |
+| tests | Cover immediate handoff, dispatch pause, multiple reasons, resolution races, restart recovery, and exactly-once final notification. |
+
+## 10. Required tests
+
+1. Serial failure pauses before the next queued task starts.
+2. Serial block pauses before the next queued task starts.
+3. Parallel failure returns immediately while already-running siblings continue.
+4. Parallel block returns immediately while already-running siblings continue.
+5. Queued siblings never start while a reason is pending.
+6. A second already-running sibling can add another pause reason without losing the first.
+7. Resolving only one of multiple reasons does not resume dispatch.
+8. `continue` preserves the failed task result and eventually produces `partial` when other tasks succeed.
+9. Retry/response is scoped to task and attempt; stale resolution is rejected.
+10. Herdr UI `blocked` alone never pauses business dispatch.
+11. `delivery_unknown` never causes automatic replay.
+12. A paused run retains the dispatcher lane; foreground submissions fail fast and background submissions remain queued.
+13. Cancellation settles running/queued tasks and releases the retained lane.
+14. Parent-session shutdown and startup reconciliation do not leave ownerless paused work.
+15. Foreground handoff and final follow-up are each delivered at most once.
+
+## 11. Non-goals
+
+- Inferring dependencies from task order or prompt text.
+- Freezing arbitrary live Agent processes.
+- Automatically retrying failed or ambiguously delivered prompts.
+- Treating Herdr UI state as business truth.
+- Loading complete child results into parent context.
+- Adding policy configuration for every state transition.
+
+## 12. Summary
+
+The architecture becomes clearer when it separates four concerns:
+
+1. **Task outcome:** what each child authoritatively reported.
+2. **Run phase:** whether new work may be dispatched or a parent decision is required.
+3. **Runtime telemetry:** what Herdr currently observes without changing business truth.
+4. **Dispatcher ownership:** whether another run may enter the global submission lane.
+
+The immediate next design step is a shared decision-pause and foreground-handoff mechanism for business failure and block. Configuration should be simplified through one canonical resolution boundary and fewer policy choices, not by forcing settings and persona prompts into one file.

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,16 @@
+## Unreleased
+
+- Make lifecycle tests accept both valid report-first and observation-first execution orderings.
+
+## 2026-10-12 - v0.4.12
+
+- enable codemode for child agents while preserving persona tool boundaries
+- Enable `codemode` for every child Pi while preserving each persona's existing tool allowlist and read/write boundary.
+
+## 2026-10-12 - v0.4.11
+
+- add architecture documentation and clear-output guidance evaluation
+
 ## 2026-10-12 - v0.4.10
 
 - Stabilize concurrency checks and cancellation synchronization on slower CI runners.

package/packages/herdr-subagents/README.md

@@ -32,6 +32,8 @@ Inside a Herdr workspace, the package registers `herdr_subagents`, `herdr_subage
 
 The design replaces hidden print-mode subprocesses with ordinary interactive Pi Agents managed through Herdr, so delegated work stays visible, inspectable, resumable, and durably recorded.
 
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the current execution architecture, the proposed decision-pause state machine, and configuration-normalization boundaries.
+
 ## Usage
 
 Discover the effective personas first:
@@ -170,6 +172,8 @@ Each `personas.<name>` object supports exactly these overrides:
 
 JSON persona overrides cannot change `name`, `description`, `access`, `tools`, or the system prompt; define those in persona Markdown.
 
+Every child Pi explicitly loads and enables `codemode`. Built-in personas include it in their tool allowlists. Custom personas may omit `tools` and inherit Pi's defaults plus `codemode`, or list `codemode` explicitly alongside their allowed tools. A read-only persona remains read-only because codemode can call only the tools enabled for that child session.
+
 A global configuration can establish shared defaults:
 
 ```json

package/packages/herdr-subagents/agents/analyst.md

@@ -2,7 +2,7 @@
 name: analyst
 description: Neutral read-only analyst for dynamically assigned roles
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.

package/packages/herdr-subagents/agents/explorer.md

@@ -2,7 +2,7 @@
 name: explorer
 description: Read-only explorer for fast codebase investigation
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Investigate the assigned question without modifying files. Report concrete evidence and useful paths.

package/packages/herdr-subagents/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: Read-only reviewer for correctness and maintainability risks
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Review the assigned work without modifying files. Report actionable findings with concrete evidence.

package/packages/herdr-subagents/agents/worker.md

@@ -2,7 +2,7 @@
 name: worker
 description: General-purpose worker for one focused task
 access: write
-tools: read, bash, edit, write, grep, find, ls
+tools: read, bash, edit, write, grep, find, ls, codemode
 ---
 
 You are a focused worker subagent.

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -15,6 +15,7 @@
     "tests",
     "docs",
     "README.md",
+    "ARCHITECTURE.md",
     "TESTING.md",
     "CHANGELOG.md",
     "package.json"

package/packages/herdr-subagents/src/live-agent.ts

@@ -36,13 +36,15 @@ export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): str
 		"--session", task.sessionFile,
 		"--name", `Subagent: ${task.name ?? task.agent ?? "worker"}`,
 		"--no-extensions",
+		"--extension", "builtin:codemode",
 		"--extension", fileURLToPath(new URL("../extensions/subagent-report.ts", import.meta.url)),
 		"--no-skills",
 		"--append-system-prompt", systemPromptFile,
 	];
 	if (task.model) args.push("--model", task.model);
 	if (task.thinking) args.push("--thinking", task.thinking);
-	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "subagent_report"])].join(","));
+	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "codemode", "subagent_report"])].join(","));
+	else args.push("--tools", "+codemode");
 	for (const skill of task.skills ?? []) args.push("--skill", skill);
 	return args;
 }

package/packages/herdr-subagents/src/personas.ts

@@ -10,6 +10,7 @@ export const BUILTIN_TOOLS = new Set([
 	"find",
 	"ls",
 	"powershell",
+	"codemode",
 ]);
 
 export interface AgentDefinition {

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -24,6 +24,7 @@ import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
 import { aggregateTaskStatus } from "../src/run-status.ts";
 import { isAbortError } from "../src/errors.ts";
 import { acquireDirectoryLock, withRunStateLock } from "../src/run-state.ts";
+import { childPiArgs } from "../src/live-agent.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
 
 /** Drives one task through the batch runner and projects its single result like a task-scoped run. */
@@ -457,13 +458,13 @@ try {
 		herdr,
 	});
 	check("compact successful report", success.ok && success.status === "completed" && success.summary === "Authentication review completed." && success.documents.length === 1 && !success.output.includes("FULL RESULT"));
-	check("Herdr lifecycle", herdr.calls.map(([name]) => name).join(",") === "createTab,renamePane,startAgent,promptAgent,getAgentState,isTabFocused,closeTab");
+	check("Herdr lifecycle", herdr.calls.map(([name]) => name).filter((name) => name !== "getAgentState").join(",") === "createTab,renamePane,startAgent,promptAgent,isTabFocused,closeTab");
 	const createRequest = herdr.calls.find(([name]) => name === "createTab")[1];
 	const startRequest = herdr.calls.find(([name]) => name === "startAgent")[1];
 	check("named unfocused tab in parent workspace", createRequest.workspaceId === "w1" && createRequest.cwd === root && createRequest.label === "SA · auth-review" && createRequest.focus === false);
 	check("ordinary execution never steals pane focus", !herdr.calls.some(([name]) => name === "focusPane"));
 	check("child environment points at durable task and parent pane", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")) && createRequest.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID === "w1:p-parent");
-	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,subagent_report"));
+	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("builtin:codemode") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,codemode,subagent_report"));
 	const promptRequest = herdr.calls.find(([name]) => name === "promptAgent")[1];
 	check("prompt submitted through Herdr", promptRequest.prompt === "Review authentication" && promptRequest.target === startRequest.name);
 
@@ -480,7 +481,7 @@ try {
 		model: { provider: "fake", id: "model" },
 		thinkingLevel: "medium",
 	}, { agentsDirectory: join(process.cwd(), "agents"), herdr: extensionHerdr });
-	check("public extension behavior uses injectable Herdr", !publicResult.isError && publicResult.content[0].text.includes("Authentication review completed.") && !publicResult.content[0].text.includes("FULL RESULT") && extensionHerdr.calls.map(([name]) => name).join(",") === "createTab,renamePane,startAgent,promptAgent,getAgentState,isTabFocused,closeTab", JSON.stringify({ publicResult, calls: extensionHerdr.calls.map(([name]) => name) }));
+	check("public extension behavior uses injectable Herdr", !publicResult.isError && publicResult.content[0].text.includes("Authentication review completed.") && !publicResult.content[0].text.includes("FULL RESULT") && extensionHerdr.calls.map(([name]) => name).filter((name) => name !== "getAgentState").join(",") === "createTab,renamePane,startAgent,promptAgent,isTabFocused,closeTab", JSON.stringify({ publicResult, calls: extensionHerdr.calls.map(([name]) => name) }));
 	let singleStalledWarning = "";
 	await runSingleTask("single slow task", { cwd: root, herdr: fakeHerdr(), stalledWarningSeconds: 0.001, onStalled: (message) => { singleStalledWarning = message; } });
 	check("single-task execution emits configured stalled warning", singleStalledWarning.includes("appears stalled"));
@@ -570,6 +571,10 @@ try {
 
 	const definition = parseAgentMarkdown(`---\nname: reviewer\ndescription: Review code\nmodel: fake/model\ntools: read, grep\n---\nReview carefully.`, "reviewer.md");
 	check("persona frontmatter parsing", definition.name === "reviewer" && definition.model === "fake/model" && definition.tools?.join(",") === "read,grep" && definition.systemPrompt === "Review carefully.");
+	const inheritedToolArgs = childPiArgs({ id: "inherited", sessionFile: "/tmp/inherited.jsonl" }, "/tmp/system.md");
+	check("child Pi enables codemode when a persona inherits default tools", inheritedToolArgs.includes("builtin:codemode") && inheritedToolArgs[inheritedToolArgs.indexOf("--tools") + 1] === "+codemode");
+	const explicitToolArgs = childPiArgs({ id: "explicit", sessionFile: "/tmp/explicit.jsonl", tools: ["read"] }, "/tmp/system.md");
+	check("child Pi enables codemode with an explicit tool allowlist", explicitToolArgs.includes("builtin:codemode") && explicitToolArgs.includes("read,codemode,subagent_report"));
 	const agentsDir = join(root, "agents");
 	await import("node:fs/promises").then(({ mkdir }) => mkdir(agentsDir));
 	writeFileSync(join(agentsDir, "worker.md"), `---\nname: worker\ndescription: Worker\n---\nDo work.`);
@@ -578,7 +583,7 @@ try {
 	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
 	const packageDiscovery = discoverPackageAgents(join(process.cwd(), "agents"));
 	const analystPersona = packageDiscovery.agents.find((persona) => persona.name === "analyst");
-	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
+	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
 
 	const configRoot = join(root, "configuration");
 	const packageAgents = join(configRoot, "package-agents");