@maxiaochao/pi-toolkit 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 2026-10-08 - v0.10.2
+
+- bundle herdr-subagents v0.3.0: split execution and control tools and unify task runs
+- Bundle the Herdr Subagents execution/control tool split and unified non-empty `tasks` input for single and multi-task runs.
+
+## 2026-10-08 - v0.10.1
+
+- bundle herdr-subagents v0.2.1: add default thinking configuration and inline Herdr workflow video
+- remove the bundled `calldiff` skill
+- add merged global/project `defaultThinking` for Herdr Subagents, below persona-specific thinking and above parent-session fallback
+- embed the Herdr workflow video directly in the GitHub README, retain the reproducible WebM source, and remove the GIF preview
+- document every Herdr Subagents settings and persona option, accepted values, defaults, configuration paths, examples, and exact precedence
+- add a full real-time Herdr Subagents WebM recording that focuses every child Agent pane before returning to the parent summary
+
+- replace the rendered Herdr transcript demo with a real UI recording of a parent Pi conversation opening and completing three concurrent interactive Agent panes
+
 ## 2026-10-08 - v0.10.0
 
 - bundle herdr-subagents v0.2.0: replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows

package/README.md

@@ -66,7 +66,6 @@ bash scripts/install.sh
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
 | `agent-team` | Run cross-vendor adversarial review through Herdr |
 | `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
-| `calldiff` | Diff call stacks across commits |
 
 Package-specific skills, such as `pi-worktree`, are documented by their child package.
 

package/global/AGENTS.md

@@ -4,71 +4,54 @@ Behavioral guidelines to reduce common LLM coding mistakes. Project-specific ins
 
 ## 1. Think Before Coding
 
-**Surface tradeoffs. Name confusion instead of resolving it silently.**
+- 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.
 
-- State your material assumptions explicitly.
-- If multiple interpretations exist, present them rather than picking one silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If requirements conflict (durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
-- When unresolved ambiguity would materially change the result, ask. When no human is reachable (headless, async, subagent), choose the interpretation you can defend, state it as an assumption, and proceed under Rule 4.
+## 2. Minimal Solution
 
-## 2. Simplicity First
+Understand the problem and relevant code flow before choosing the first rung that works:
 
-**YAGNI cuts what you don't need; KISS keeps what remains simple.**
+1. Skip functionality that is speculative or was not requested.
+2. Reuse an existing project abstraction when it encodes the required semantics.
+3. Otherwise use the standard library or a native platform feature.
+4. Otherwise use a direct dependency already declared by the project.
+5. Only then write the minimum custom code that works.
 
-- Build what was asked, for the callers that exist today.
-- Introduce an abstraction after repeated use reveals a stable concept.
+- Introduce abstractions only after repeated use reveals a stable concept.
+- Prefer boring, focused code; review long or deeply nested functions for splitting.
+- Never simplify away explicit requirements, trust-boundary validation, data-loss protection, security, or accessibility.
 - For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
-- Each function you write does one thing. If it runs past a couple of screens or nests past three levels, review whether splitting it improves clarity.
+- State the ceiling and upgrade trigger of any deliberate simplification that cuts a real corner.
 
-## 3. Surgical Changes
+## 3. Skill Boundaries
 
-**Touch only what you must. Clean up only your own mess.**
+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.
 
-The test: every changed line traces to the user's request, or to a defect that request reveals.
+## 4. Read, Then Change Surgically
 
-- Match existing style, even if you'd do it differently.
-- Remove imports, variables, and functions that YOUR changes made unused. Leave pre-existing dead code in place and mention it.
+Before editing, read the affected public API and its immediate callers. For a bug, find every statically discoverable caller and relevant implementation.
 
-When fixing a bug, fix the root cause, not the symptom. Find where the defect actually lives:
-- Find every statically discoverable caller and relevant implementation; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
-- If the shared function is wrong, fix it once - do not scatter per-caller guards. Name the sibling callers the fix now affects.
-- If one caller is wrong, fix that caller - do not add defensive handling to a correct shared function.
+Every changed line traces to the user's request or to a defect that request reveals.
 
-## 4. Goal-Driven Execution
+- Match existing style.
+- 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.
 
-**Define success criteria. Loop until verified.**
+## 5. Goal-Driven Execution
 
-Transform tasks into verifiable goals:
-- "Add validation" -> "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
-- "Refactor X" -> "Ensure tests pass before and after"
-- "Make X fast" -> "Write and test a simple reference implementation, then optimize against its results"
+- 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.
 
-For multi-step or materially ambiguous tasks, state a brief plan where every step carries its own check:
-1. [Step] -> verify: [check]
+## 6. Fail Visibly
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-## 5. Read Before You Write
-
-**Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
-
-Before changing a file:
-- Read the file's exports and public API.
-- Read the immediate callers of the function you're modifying.
-
-## 6. Fail Visibly, Not Silently
-
-**Silent skips are failures.**
-
-- "Completed" is wrong if anything was silently skipped.
+- "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), do NOT fabricate it to make a check pass. Report what is missing and what you need.
+- 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. Worktree Isolation
 
-## 7. Reuse Before Writing
+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.
 
-**Before writing new code, check in order:**
-1. Reuse an existing project abstraction when it encodes project semantics. (If it is itself the bug, fix it once - see Rule 3.)
-2. Otherwise use the standard library or a direct dependency already declared by the project.
-3. Only then write it yourself.
+If the user agrees, read the `pi-worktree` skill and establish the worktree before changing code. When no human is reachable, create a worktree only when the task explicitly requests one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2026-10-08 - v0.3.0
+
+- split execution and control tools and unify task runs
+- Split execution and control into `herdr_subagents` and `herdr_subagents_control`; require a non-empty `tasks` array for new runs so one-item runs and batches share background and concurrency semantics.
+- Normalize legacy top-level single-task prompts into one-item task arrays before schema validation.
+
+## 2026-10-08 - v0.2.1
+
+- add default thinking configuration and inline Herdr workflow video
+- Add merged global/project `defaultThinking`, below persona-specific thinking and above parent-session fallback, with effective source reporting.
+- Embed the workflow video directly in the GitHub README, retain the reproducible WebM source, and remove the GIF preview.
+- Expand the README with every settings and persona option, accepted values, defaults, paths, examples, and exact model, thinking, skills, and definition precedence.
+- Add a full WebM recording that focuses all three live child Agent panes before returning to the parent summary.
+- Replace the rendered transcript media with a real Herdr UI recording that follows a parent Pi conversation through a three-Agent batch and final compact response.
+
 ## 2026-10-08 - v0.2.0
 
 - replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows

package/packages/herdr-subagents/README.md

@@ -2,11 +2,16 @@
 
 A Pi extension that runs focused foreground or background work as normal interactive Pi Agents in visible Herdr panes. Full answers and sessions stay in project-local records while the parent receives only concise summaries and document paths.
 
-![Herdr Subagents production runner screenshot](docs/screenshot.png)
+![A parent Pi conversation running three visible Herdr Subagents panes](docs/screenshot.png)
 
 ## Demo
 
-![Herdr Subagents demo](docs/demo.gif)
+The recording shows a real Pi conversation invoking a three-task read-only batch, Herdr opening one interactive Agent pane per task, and the compact results returning to the parent.
+
+https://github.com/user-attachments/assets/8ddf3ae6-a11a-492b-9cae-d9496ba65b67
+
+The video starts a three-agent batch, focuses each live child pane in turn, then returns
+to the parent summary. The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
 
 ## Requirements and install
 
@@ -24,7 +29,7 @@ pi update npm:@maxiaochao/pi-herdr-subagents
 
 The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
 
-Inside a Herdr workspace, the package registers `herdr_subagents` and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers neither, so the tool is absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
+Inside a Herdr workspace, the package registers `herdr_subagents`, `herdr_subagents_control`, and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers none of them, so these capabilities are absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
 
 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.
 
@@ -33,16 +38,17 @@ The design replaces hidden print-mode subprocesses with ordinary interactive Pi
 Discover the effective personas first:
 
 ```text
-herdr_subagents({ action: "list" })
+herdr_subagents_control({ action: "list" })
 ```
 
 Then run one self-contained task:
 
 ```text
 herdr_subagents({
-  agent: "worker",
   label: "auth-review",
-  prompt: "Inspect the authentication flow and summarize the risks"
+  tasks: [
+    { name: "auth", agent: "worker", prompt: "Inspect the authentication flow and summarize the risks" }
+  ]
 })
 ```
 
@@ -59,21 +65,21 @@ herdr_subagents({
 })
 ```
 
-Set `background: true` to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+`tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
 
-A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the same tool to continue the original session:
+A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the control tool to continue the original session:
 
 ```text
-herdr_subagents({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
 While a batch is active, its task rows stay below the editor. With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
 
 ## History
 
-Run `/herdr-subagents history` or `herdr_subagents({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
 
-Continue a saved conversation in a new Herdr tab with `herdr_subagents({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
+Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents_control({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
 
 Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
 
@@ -98,49 +104,172 @@ The complete result is not copied into the parent model context. Each run is ret
 
 The task directory contains the full result, structured report, task metadata, system prompt, and persistent Pi session. Run-level metadata is stored in the parent run directory.
 
-## Personas
+## Configuration and personas
 
-The package includes `worker` (write access), `explorer` (read access), and `reviewer` (read access). Persona definitions are discovered in this order, with the first available higher-precedence definition replacing the lower one:
+Herdr Subagents loads settings and persona definitions from separate files:
 
-1. `.pi/herdr-subagents/agents/*.md` in the project
-2. `~/.pi/agent/herdr-subagents/agents/*.md` globally
-3. this package's `agents/*.md`
+| Scope | Settings | Persona definitions |
+| --- | --- | --- |
+| 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 | installed package `agents/*.md` |
 
-A custom persona without `access` is treated as write-capable. Definitions may set `access`, `model`, `thinking`, `tools`, and `skills` in frontmatter.
+Project JSON values recursively override global JSON values. The built-in setting defaults are `defaultConcurrency: 1`, `maxConcurrency: 4`, and `stalledWarningSeconds: 300`. `defaultModel` and `defaultThinking` are unset, so the parent Pi model and its thinking level are inherited unless another setting wins.
 
-The default `agents/worker.md` uses this format:
+### Settings file option reference
 
-```md
----
-name: worker
-description: General-purpose worker for one focused task
-tools: read, bash, edit, write, grep, find, ls
----
+These are all supported top-level fields in `herdr-subagents.json`:
 
-You are a focused worker subagent.
-```
+| Option | Accepted value | Default | Effect |
+| --- | --- | --- | --- |
+| `defaultConcurrency` | Positive integer | `1` | Number of read-only tasks allowed to run together when a batch call omits `concurrency`. It is capped to `maxConcurrency`. |
+| `maxConcurrency` | Positive integer | `4` | Hard ceiling for requested/default batch concurrency. A batch containing any write-capable persona still runs serially. |
+| `stalledWarningSeconds` | Positive integer | `300` | Seconds before a still-running child emits a warning. This is not a timeout and does not stop the child. |
+| `defaultModel` | Non-empty Pi model string, normally `provider/model` | Unset | Model used when neither JSON persona settings nor persona Markdown select one. If unset, the parent model is inherited. Use `/herdr-subagents models` to list authenticated models. |
+| `defaultThinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Unset | Thinking level below persona-specific settings. Provider/model support can vary. If unset, parent thinking is inherited only when the parent model is also inherited. |
+| `personas` | Object keyed by an existing persona name | `{}` | Per-persona JSON overrides described below. This does not create a persona; a matching Markdown definition must exist. |
+
+Known fields with an invalid JSON type, an empty required string, or a non-positive integer are ignored with a diagnostic shown by `/herdr-subagents settings`. Model IDs, thinking-level compatibility, and skill availability are ultimately validated by Pi when the child starts. When `defaultConcurrency` exceeds `maxConcurrency`, the effective default is reduced to the maximum.
 
-Supported frontmatter:
+Each `personas.<name>` object supports exactly these overrides:
 
-- `name` and `description` are required.
-- `model` optionally selects a child model. A call-level `model` overrides it; otherwise the current session model is inherited.
-- `tools` optionally restricts built-in tools. `subagent_report` is always added so the child can settle the task.
-- `access` is `read` or `write`; omitted custom values default to `write`.
-- `thinking` and `skills` provide persona defaults.
+| Option | Accepted value | Effect |
+| --- | --- | --- |
+| `model` | Non-empty Pi model string | Overrides the model from the effective persona Markdown and `defaultModel`. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Overrides persona Markdown and `defaultThinking`. The value is passed to Pi's `--thinking` option. |
+| `skills` | Array of non-empty strings | Replaces the entire lower-precedence skill list. Use `[]` to clear inherited skills. Each item is passed to child Pi as `--skill`. |
 
-Global settings live at `~/.pi/agent/herdr-subagents.json`; project overrides live at `.pi/herdr-subagents.json`. Both support `defaultConcurrency`, `maxConcurrency`, `stalledWarningSeconds`, `defaultModel`, and a `personas` object whose entries can override `model`, `thinking`, and `skills`.
+JSON persona overrides cannot change `name`, `description`, `access`, `tools`, or the system prompt; define those in persona Markdown.
+
+A global configuration can establish shared defaults:
 
 ```json
 {
-  "defaultModel": "provider/model",
-  "maxConcurrency": 3,
+  "defaultConcurrency": 2,
+  "maxConcurrency": 4,
+  "stalledWarningSeconds": 300,
+  "defaultModel": "anthropic/claude-sonnet-4-5",
+  "defaultThinking": "medium",
   "personas": {
-    "reviewer": { "thinking": "high", "skills": ["code-review"] }
+    "explorer": {
+      "model": "anthropic/claude-haiku-4-5",
+      "thinking": "medium",
+      "skills": ["code-search"]
+    },
+    "reviewer": {
+      "thinking": "high",
+      "skills": ["code-review"]
+    }
   }
 }
 ```
 
-Project values override global values recursively. Model resolution is: task override, project persona setting, global persona setting, persona frontmatter, global/project default model, then parent model. Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents settings` to inspect effective values and their sources.
+The project file can override only the fields that differ. Persona fields are merged by persona name:
+
+```json
+{
+  "defaultConcurrency": 3,
+  "stalledWarningSeconds": 600,
+  "defaultThinking": "high",
+  "personas": {
+    "explorer": {
+      "model": "openai/gpt-5.2"
+    },
+    "reviewer": {
+      "skills": ["security-review", "code-review"]
+    }
+  }
+}
+```
+
+The package includes these personas:
+
+| Persona | Access | Built-in tools | Intended use |
+| --- | --- | --- | --- |
+| `worker` | write | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` | Focused implementation work |
+| `explorer` | read | `read`, `bash`, `grep`, `find`, `ls` | Fast codebase investigation |
+| `reviewer` | read | `read`, `bash`, `grep`, `find`, `ls` | Correctness and maintainability review |
+
+Persona definitions use Markdown frontmatter followed by the child system prompt. For example, save this as `.pi/herdr-subagents/agents/security-reviewer.md`:
+
+```md
+---
+name: security-reviewer
+description: Read-only reviewer for security risks
+access: read
+model: anthropic/claude-sonnet-4-5
+thinking: high
+tools: read, bash, grep, find, ls
+skills: security-review, code-review
+---
+
+Review the assigned scope without modifying files. Report concrete risks and evidence.
+```
+
+Persona Markdown supports these frontmatter fields:
+
+| Field | Accepted value | Required/default | Effect |
+| --- | --- | --- | --- |
+| `name` | Non-empty string | Required | Persona identifier used by `agent`. Names must be unique within one persona directory. |
+| `description` | Non-empty string | Required | Description shown to the parent when agents are listed. |
+| `access` | `read` or `write` | `write` | Scheduling declaration. Any batch containing `write` is forced to concurrency one. `read` permits parallel scheduling but does not itself remove tools. |
+| `model` | Non-empty Pi model string | Unset | Persona model default. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Unset | Persona thinking default passed to Pi's `--thinking` option. |
+| `tools` | Non-empty comma-separated list, optionally bracketed | Child Pi defaults | Restricts built-in tools. Supported names are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, and `powershell`. `subagent_report` is always added. |
+| `skills` | Comma-separated list, optionally bracketed | None | Skills loaded explicitly into child Pi; automatic skill discovery is disabled. |
+
+The Markdown body after the frontmatter is the child system prompt and may be empty. To make a custom persona operationally read-only, set `access: read` **and** choose an appropriate `tools` allowlist; `access` alone is not a tool sandbox. Model names and skill values are passed to Pi, so they must be available in the installed Pi environment.
+
+Persona Markdown definitions use replacement precedence, not field merging. A same-name project definition replaces the entire global or package definition:
+
+1. project `.pi/herdr-subagents/agents/*.md`
+2. global `~/.pi/agent/herdr-subagents/agents/*.md`
+3. package built-ins
+
+### Model and persona-option precedence
+
+The child model is selected in this exact order:
+
+1. `model` on the task or call
+2. project `personas.<name>.model` JSON setting
+3. global `personas.<name>.model` JSON setting
+4. `model` in the effective persona Markdown frontmatter
+5. effective `defaultModel` JSON setting (project overrides global)
+6. parent Pi model
+
+The child thinking level is selected in this order:
+
+1. project `personas.<name>.thinking` JSON setting
+2. global `personas.<name>.thinking` JSON setting
+3. `thinking` in the effective persona Markdown frontmatter
+4. effective `defaultThinking` JSON setting (project overrides global)
+5. parent Pi thinking level when the child also inherits the parent model
+
+Thinking has no call-level override. `skills` uses the first three persona-level steps and has no global default; a project `skills` array replaces, rather than appends to, the global or Markdown list.
+
+Override the model for one task:
+
+```text
+herdr_subagents({
+  tasks: [
+    { name: "authorization", agent: "reviewer", model: "anthropic/claude-opus-4-1:high", prompt: "Review the authorization boundary" }
+  ]
+})
+```
+
+Each task in a batch can select its own model:
+
+```text
+herdr_subagents({
+  concurrency: 2,
+  tasks: [
+    { name: "map", agent: "explorer", model: "anthropic/claude-haiku-4-5", prompt: "Map the request flow" },
+    { name: "review", agent: "reviewer", model: "anthropic/claude-sonnet-4-5", prompt: "Review input validation" }
+  ]
+})
+```
+
+Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents settings` to inspect effective values and their sources.
 
 ## Recovery and failures
 

package/packages/herdr-subagents/TESTING.md

@@ -4,8 +4,9 @@
 
 1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests.
 2. `pi -ne -ns --no-session -e ./packages/herdr-subagents/extensions/herdr-subagents.ts` verifies extension loading.
-3. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
-4. Verify the README example and the production-runner media `docs/screenshot.png` and `docs/demo.gif` are present in the tarball.
+3. From a visible X11 Herdr client with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, and the final compact parent response.
+4. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
+5. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → parent sequence.
 
 ## Cases
 
@@ -15,10 +16,10 @@
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
-- Verify the flat public contract and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
 - Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 133 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 137 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.