pi-subagents 0.66.0 → 0.68.0

package/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 ## [Unreleased]
 
+## [0.68.0] - 2026-09-15
+
+### Highlights
+- Run Pi, Claude Code, Codex, and Cursor subagents on saved remote machines through Herdr.
+- Reuse workflow scripts with different JSON inputs, including scheduled runs.
+- Start npm-installed children much faster and let slow local models use Pi's configured HTTP timeout.
+- Keep local foreground children on the same extension-provided models as their parent without sharing provider state between sessions.
+- Get simpler, more predictable failures: each launch uses one resolved model instead of switching models automatically.
+
+### Added
+
+- Accept bounded JSON `args` for inline, file-backed, validated, and scheduled workflow scripts. Scripts receive immutable arguments, and schedules retain them for later runs (#2233).
+- Left-click the async widget header in mouse-enabled Pi fullscreen mode to fold it into a live status summary and unfold it again, independently of global tool expansion. Progress updates preserve the fold state; run execution and notifications are unchanged. Thanks to [@pstanton237](https://github.com/pstanton237) for #2235.
+- Allow agents to declare an inline JSON Schema `outputSchema` default, with launch objects overriding it and explicit `false` opting out. Thanks to [@peedrr](https://github.com/peedrr) for #2180.
+- Add `PI_SUBAGENT_CACHE_RETENTION` to set a prompt-cache retention tier for child sessions only, so a parent on the 1h tier can keep children on the cheaper-to-write 5m tier they are too short-lived to benefit from. Unset by default, leaving children on the parent's retention. Spawned children take it through the launch environment; in-process children pin it per request on their own session rather than on shared process state. Thanks to [@johnwards](https://github.com/johnwards) for #2190.
+- Add a session-scoped host API for extensions that every native child must load. Required extensions survive agent overrides and nested launches, and child startup fails clearly when one is denied or cannot load. Thanks to [@gkoreli](https://github.com/gkoreli) for #2153.
+- Run Pi, Claude Code, Codex, and Cursor subagents on another computer by setting `machine` to a saved Herdr machine.
+- Add `checkpointBeforeDeadlineMs` for async single-agent runs. It asks the child to checkpoint and stop before the hard `timeoutMs` deadline; without it, timeout behavior is unchanged. Thanks to [@freezscholte](https://github.com/freezscholte) for #2141.
+- Add `subagents.agentExcludeDirs` to exclude directory trees from agent discovery, including nested plugin sources and symlink aliases. Thanks to [@xarillian](https://github.com/xarillian) for #2131.
+
+### Changed
+
+- Add `inspectorOpen` and `projectOpen` to `authorityPolicy`. Inspector opening remains automatic by default, while project opening now asks for confirmation because it starts Herdr and opens another Pi session. Set `"projectOpen": "auto"` to restore unprompted project opening. The Fleet TUI is unchanged. Thanks to [@kevthedawg](https://github.com/kevthedawg) for #2269.
+- Ship compiled JavaScript in the npm package so Pi no longer transpiles the extension and detached runner when they load. On the reported cold-start path, the extension entry loaded in about 226 ms instead of 2,831 ms. Thanks to [@821869798](https://github.com/821869798) for #2248.
+
+### Removed
+
+- Remove `fallbackModels`, all same-launch model switching (including read-only HTTP 429 continuation), and persistent model exclusions. Retry another model only with a later explicit launch; guarded retained-session compaction recovery may continue once on the already resolved model.
+- Drop the bundled `@earendil-works/pi-server` copy that filled in the dependency Pi 0.85.0 forgot to ship. Background children on a Pi 0.85.0 host now fail to launch with a clear error; upgrade to Pi 0.85.1 or newer, which ships the package itself. Foreground children on 0.85.0 are unaffected.
+
+### Fixed
+
+- Preserve the main watchdog's user scope across session compaction while clearing temporary activity state. Thanks to [@nimeetshah0](https://github.com/nimeetshah0) for #2263.
+- Resolve provider-extension models in local, in-process foreground children. Such a child never loads the parent's ambient extensions, so its model runtime only knew Pi's built-in providers and every model from an extension-registered provider failed with `Model "…" not found`; the child now inherits the providers registered in the parent session before resolving its model. Pane-native remote foreground children continue to use the remote machine's provider discovery and configuration. Builtin agents on such a model no longer need `async: true`. Thanks to [@lallenlowe](https://github.com/lallenlowe) for #2274.
+- Preserve a readable async result when result indexing or archiving fails, then retry saving it without delivering it twice. Thanks to [@shaharmor](https://github.com/shaharmor) for #2267 and #2266.
+- Honor `PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT` for background children, fixing launches from wrapper installs and other non-standard Pi layouts. Thanks to [@Yaphet2015](https://github.com/Yaphet2015) for #2254.
+- Keep a foreground child's report available when acceptance rejects saved output instead of replacing it with only a file reference. Thanks to [@pgoodjohn](https://github.com/pgoodjohn) for #2255.
+- Add the ambient-extension rule to Pi's model-not-found error when a child's model comes from an extension-registered provider that was not loaded for it: a foreground child now reports that agents needing a provider extension's models must run as background children (`async: true`) or load the extension explicitly through `subagentOnlyExtensions`/`extensions`, and a background child launched without the ambient extensions gets the matching remedies. When `capabilityCeiling.denyExtensions` blocks every extension, both hosts report the policy instead of remedies the ceiling discards. The core error, exit code, and failure detection are unchanged. Thanks to [@pwguler](https://github.com/pwguler) for #2240.
+- Remote Herdr bridge discovery no longer blocks the parent session while waiting for the remote Pi to start.
+- Recognize Windows Bun virtual entrypoints when launching standalone background children, retaining the existing Linux and npm paths. Windows coverage remains experimental; see `docs/standalone-background.md`. Thanks to [@JohnsonRan](https://github.com/JohnsonRan) for #2241.
+- Keep supervisor progress updates out of parent model turns while still waking for decisions and structured questions. Thanks to [@moofone](https://github.com/moofone) for #2229 and [@dajiaohuang](https://github.com/dajiaohuang) for #2230.
+- Keep routine successful child updates out of parent model turns, and wake the parent when saving an async workflow result fails. Thanks to [@moofone](https://github.com/moofone) for #2262.
+- Start background cleanup, wait reconciliation, and retention timers with the session and clear them during shutdown. Thanks to [@freezscholte](https://github.com/freezscholte) for #2244.
+- Apply Pi's `httpIdleTimeoutMs` setting to the detached async runner's HTTP dispatcher on both the Node and standalone binary host launch paths (project `.pi/settings.json` over `~/.pi/agent/settings.json`, `0` disables; an invalid value warns and falls back to 300s). The runner previously kept undici's 300s header/body defaults, so async children against a slow local model were cut at about five minutes while foreground children waited as configured. Thanks to [@JordiPosthumus](https://github.com/JordiPosthumus) for the incident analysis in #2199.
+- Restore direct parent ownership as the default. The bundled skill delegates only when the operator asks; complexity alone no longer starts child workflows. Thanks to [@AlexDochioiu](https://github.com/AlexDochioiu) for #2216.
+- Stop external runs from leaving Windows worktrees locked by Git fsmonitor processes after cancellation (#2207 recurrence).
+- Include each agent's acceptance policy and role in `capabilities: true` results. Thanks to [@Alice39s](https://github.com/Alice39s) for #2210.
+- Recover when a parent workflow's previous checkout directory was removed before another child starts. Thanks to [@trewwwsec](https://github.com/trewwwsec) for #2211.
+- Keep resumed-run startup non-blocking and fail clearly when the runner exits before it is ready. Thanks to [@qsgy-edge](https://github.com/qsgy-edge) for #2219.
+- Prefer exact agent names over packaged short-name matches, and never treat home-level agent directories as project configuration. This prevents names such as `scout` and `code-analysis.scout` from becoming ambiguous. Thanks to [@ton77v](https://github.com/ton77v) for #2214.
+- Avoid Jiti for native async runner startup on supported Node versions. Thanks to [@qsgy-edge](https://github.com/qsgy-edge) for #2220.
+- Stop registering and advertising a default global `Ctrl+Alt+F` Fleet shortcut; `/subagents-fleet` and FleetView remain available. Thanks to [@miaomiaozii](https://github.com/miaomiaozii) for #2196.
+- Require low, medium, or high importance on watchdog findings. Low and medium stay visible to the user without entering model context; high findings still reach the model (#2201).
+- Let headless parents and nested coordinators answer blocking child questions without deadlocking shutdown. Thanks to [@ProDrifterDK](https://github.com/ProDrifterDK) for #2185.
+- Keep nested stop, interrupt, and timeout propagation inside the issuing run's descendant subtree while preserving root-wide controls. Thanks to [@freezscholte](https://github.com/freezscholte) for #2243.
+- Keep read-only reviews free of implementation acceptance requirements when their topic mentions releases, migrations, or security. Explicit acceptance and write tasks are unchanged. Thanks to [@qsgy-edge](https://github.com/qsgy-edge) for #2191.
+- Include async result, output, and structured-output paths in completion notices. Thanks to [@peedrr](https://github.com/peedrr) for #2181.
+- Remove one-shot workflow result files and their indexes after successful consumption. Thanks to [@peedrr](https://github.com/peedrr) for #2182.
+- Show runtime-registered agents in `/subagents` while keeping their extension-owned definitions read-only and rejecting collisions with disabled configured agents. Thanks to [@mystery4f](https://github.com/mystery4f) for #2169.
+- Save readable JSON to configured background output files when a successful child returns structured output without final prose. Thanks to [@rtbe](https://github.com/rtbe) for #2163.
+- Surface the provider error text of a failed watchdog review in `/subagents-watchdog status` `Last error` (bounded to 600 chars). Previously only `stop reason 'error'` was recorded, so a watchdog failing every review (rate limit, rejected model, auth) was indistinguishable from a clean one. Thanks to [@freezscholte](https://github.com/freezscholte) for #2166.
+- Finalize paused async runs after the runner has actually stopped, while keeping them resumable until then. Thanks to [@neruok](https://github.com/neruok) for #2170.
+- Keep explicitly stopped aggregate children non-resumable while allowing completed siblings to resume. Thanks to [@freezscholte](https://github.com/freezscholte) for #2242.
+- Group workflow children under their status rows without duplicate entries and show reliable completion times. Thanks to [@niko-operal](https://github.com/niko-operal) for #2168.
+- Refresh external-run activity from stdout, stderr, and Git changes without repeatedly polling Git. Thanks to [@DeLuke84](https://github.com/DeLuke84) for #2167.
+- Remove expired partial and rejected jobs from the widget while preserving live nested children. Thanks to [@ashlineldridge](https://github.com/ashlineldridge) for #2159.
+- Reject unsupported bare acceptance strings at the provider schema boundary while preserving shorthand levels and JSON-encoded acceptance objects. Thanks to [@vrolok](https://github.com/vrolok) for #2152.
+- Let Pi finish automatic compaction without an extra extension resume while preserving manual continuation for active async work. Thanks to [@mxp7064](https://github.com/mxp7064) for #2144.
+- Preserve wrapped Pi core tools and explicitly requested non-core tools in child launches. Core slots still respect host availability; non-core tools are validated in the child's runtime after ceilings and exclusions (#2132, #2133, #2134, #2135, #2140). Thanks to [@carlesba](https://github.com/carlesba) for #2137 and [@clementprevot](https://github.com/clementprevot) for #2138.
+
+## [0.67.0] - 2026-09-10
+
+### Highlights
+- Launch previews now match what actually runs, including Intercom and prompt and tool customization.
+- Parallel workflows are easier to write and follow, with natural promise composition and per-child completion updates.
+- Child-facing tool instructions use less context, leaving more of the token budget available for the task itself.
+- Steering, follow-ups, resumed work, and detached processes finish more reliably.
+- FleetView and workflow status are clearer, with better grouping, timing, usage, and colors.
+
+### Added
+- Add optional watchdog fallback models for the main session, children, and individual agents. Fallback happens only for provider failures before tool use and within the existing review timeout. Thanks to [@dwizzle204](https://github.com/dwizzle204) for #2075.
+- Add portable Inspect commands and a terminal-neutral integration point, including open-only Ghostty 1.3+ right splits on macOS. Thanks to [@tiratatp](https://github.com/tiratatp) for #2046.
+- Add `quiet: true` for recurring schedules. Successful automatic runs stay visible without waking the parent; failures, stops, and pauses still wake it. One-shot and manually started schedules remain noisy unless explicitly made quiet. Thanks to [@pablontiv](https://github.com/pablontiv) for #2055.
+- Add optional watchdog questions that flag possible task drift before a main-session change finishes (#2010).
+- Add the built-in `evidence-auditor` for checking whether important research claims are supported by their sources. Thanks to [@Muskos](https://github.com/Muskos) for #2023.
+- Notify the parent as each asynchronous workflow child finishes instead of waiting for every sibling. Notifications include the workflow, child, outcome, and result location (#2027).
+- Add per-launch `intercomBridge` overrides to delegation and preflight, plus `orchestratorTarget` for custom bridge templates that name the parent. Invalid overrides now fail clearly (#2127). Thanks to [@Yivas](https://github.com/Yivas) for the instrumented reproduction.
+
+### Changed
+- Make the default Intercom bridge prompt independent of the parent session while preserving `{orchestratorTarget}` in custom templates. Launch contracts are now version 3 and launch-binding projections version 2, so launch-contract digests change in this release; existing saved runs still resume (#2127). Thanks to [@Yivas](https://github.com/Yivas) for the instrumented reproduction.
+- Include removed child tools and their active restrictions in launch warnings without changing launch behavior. Follow-up for #2058.
+- Shorten the default child-facing instructions while keeping the full typed API and detailed guides. Thanks to [@Whamp](https://github.com/Whamp) for the prompt-footprint measurements and proposal in #2048.
+- Give FleetView agents stable identity colors. Thanks to [@savinofiore](https://github.com/savinofiore) for #2056.
+- Preserve a forked child's requested thinking level after incompatible signed Anthropic thinking blocks are removed. This requires Pi 0.85.0 or newer. Thanks to [@hank-warren](https://github.com/hank-warren) for #2021.
+- Scope parallel-review findings to the requested target, while diff reviews continue to report only issues caused or exposed by the diff. Thanks to [@jmclaughlin724](https://github.com/jmclaughlin724) for #2042.
+- Simplify watchdog clarification to one visible question followed by native continuation, removing reply tracking and mandatory follow-up reviews.
+- Show task-based labels for workflow launches, reviews, and continued child work.
+
+### Fixed
+- Accept `runs.run(...)` promises in `runs.all(...)`, including the natural `items.map(...)` form, instead of reporting an invalid key. A one-time warning explains when config objects are still required for batch validation, grouping, and `collectFailure`. Thanks to [@karandhillon1995](https://github.com/karandhillon1995) for #2128.
+- Make Intercom-aware preflight produce the same launch digest as foreground and background execution, while keeping the parsed agent definition independent of runtime bridge changes (#2127 and #2112). Thanks to [@Yivas](https://github.com/Yivas) for the instrumented reproduction.
+- Apply project refinements during preflight so its launch digest matches the completed run. Thanks to [@Yivas](https://github.com/Yivas) for #2112.
+- Report steering and follow-up requests as delivered only after the child consumes them, and report unconsumed requests accurately when the child finishes (#2116 and #2121). Thanks to [@yanqianglu](https://github.com/yanqianglu) for #2057.
+- Keep native children alive during final shutdown when queued steering or follow-up work is still pending (#2117). Thanks to [@yanqianglu](https://github.com/yanqianglu) for #2057.
+- Prevent stale shutdown timers from aborting resumed foreground or background work. Thanks to [@harche](https://github.com/harche) for #2025.
+- Wait for remembered detached descendants before their parent finishes, without aborting children that already produced a result. Thanks to [@shaharmor](https://github.com/shaharmor) for #2051.
+- Keep paused background runs from failing on checks that apply only at completion. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #2022.
+- Report process-tree cleanup as complete only after detached descendants have actually stopped. Thanks to [@rtbe](https://github.com/rtbe) for #2053.
+- Let approved child coordinators answer supervisor questions from their own children while preserving immediate-parent ownership and tool restrictions. Thanks to [@shaharmor](https://github.com/shaharmor) for #2087.
+- Allow read-only reviewers to quote phrases such as “must fix before” without being mistaken for implementation requests. Thanks to [@freezscholte](https://github.com/freezscholte) for #2079.
+- Preserve explicitly read-only requests after tool restrictions are applied, while still rejecting implementation work without write tools. Thanks to [@stekman08](https://github.com/stekman08) for #2060.
+- Stop review and scout launches before startup when requested repository tools are unavailable. Explicitly empty or restricted tool sets remain valid. Follow-up for #2058.
+- Keep workflow child tools aligned with the selected agent when extensions wrap Pi built-ins, and place automatic extension-repository worktrees outside extension discovery (#2059).
+- Validate worktree repositories and cleanliness before starting parallel workflow children. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #2076.
+- Reject workflows whose known child count exceeds `maxSubagentSpawnsPerRun` before starting any child; dynamic counts remain limited at runtime. Thanks to [@ton77v](https://github.com/ton77v) for #2101.
+- Show workflow usage on child rows instead of displaying overlapping or misleading wrapper totals. Thanks to [@expoli](https://github.com/expoli) for #2085.
+- Keep live workflow timers advancing, nest loaded children correctly, collapse only fully represented duplicate groups, and freeze completed durations accurately. Thanks to [@expoli](https://github.com/expoli) for #2085.
+- Preserve the parent's theme in foreground children, initialize themes in detached children, and refresh command-result rendering. Thanks to [@kubahasek](https://github.com/kubahasek) for #2089.
+- Parse complete Orca creation output so observer handles, tab IDs, and titles are stored correctly. Thanks to [@G0-0000](https://github.com/G0-0000) for #2063.
+- Keep the configured watchdog model and thinking level when recommending models. Thanks to [@freezscholte](https://github.com/freezscholte) for #2078.
+- Recognize OpenRouter's status-prefixed 401 response as eligible for configured fallback before tool use. Thanks to [@freezscholte](https://github.com/freezscholte) for #2077.
+- Keep internal OpenCode helper requests in the same provider session as normal Pi traffic. Thanks to [@IdrisGit](https://github.com/IdrisGit) for #2041.
+- Run the child prompt filter before extensions inspect the final prompt, preserving intentional global-context and parent-only skill exclusions. Thanks to [@leftytennis](https://github.com/leftytennis) for #2043.
+- Intersect agent tool declarations with tools available from the host, so restricted hosts reject unavailable tools before starting a child. Thanks to [@BioInfo](https://github.com/BioInfo) for #2034.
+- Allow `fast` to round-trip through background recovery and follow-up. Thanks to [@isty2e](https://github.com/isty2e) for #2045.
+- Use the detected npm Pi package root in detached runners instead of an inherited host path. Thanks to [@alvarosevilla95](https://github.com/alvarosevilla95) for #2050.
+- Restore background SDK sessions for the official Pi 0.85.1 Linux standalone while retaining Pi 0.85.0 support. Thanks to [@xz-dev](https://github.com/xz-dev) for #2049.
+- Resolve Pi TUI aliases correctly in unusual package layouts. Thanks to [@kroediger](https://github.com/kroediger) for #2020.
+- Avoid requiring newer chord aliases on Pi versions before 0.85 while keeping required runtime aliases strict. Thanks to [@samuela](https://github.com/samuela) for #2026.
+- Use `git wt` for Worktrunk on Windows to avoid the Windows Terminal `wt.exe` conflict. Thanks to [@Zethu5](https://github.com/Zethu5) for #2033.
+- Prevent manually started schedules from firing again at their next natural time. Thanks to [@brandonmwest](https://github.com/brandonmwest) for #2052.
+- Allow terminal schedules owned by an earlier session to be deleted when their exact run is known to have finished (#2125).
+- Show exact child IDs and usable steering guidance in workflow status when a workflow no longer has a foreground route (#2011).
+- Ignore action-like words inside filenames and paths when deciding whether a task requests implementation. Thanks to [@SiebertLanhove](https://github.com/SiebertLanhove) for #2039.
+- Bound transcript previews by line and total size while preserving recent context and artifact links. Thanks to [@rtbe](https://github.com/rtbe) for #2015.
+- Refresh the local model registry before opening model and thinking selectors, and warn when refresh fails. Thanks to [@ianbmacdonald](https://github.com/ianbmacdonald) for #2008.
+- Preserve string, string-array, and undefined system-prompt shapes in `before_agent_start`. Thanks to [@luqman-v1](https://github.com/luqman-v1) for #2107.
+
 ## [0.66.0] - 2026-09-06
 
 ### Highlights

package/README.md

@@ -14,7 +14,7 @@
 pi install npm:pi-subagents
 ```
 
-That is the only required step. Background children require pi installed as the npm package (`@earendil-works/pi-coding-agent`): the detached runner imports pi's packages from that package directory. A standalone single-file pi binary has no package directory and cannot run background children; foreground children (`async: false`) still work there.
+That is the only required step. Background children use the host's SDK: npm Pi keeps its detached Node runner; the official Pi 0.85.1 Linux x64 standalone release loads the same runner through Pi's embedded SDK, without a separate SDK install. See [Standalone background execution](docs/standalone-background.md) for the supported boundary and validation gate.
 
 ## Try this first
 
@@ -57,13 +57,14 @@ The extension ships with agents you can use immediately:
 | Agent | Use it when you want... |
 |-------|--------------------------|
 | `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks. |
-| `researcher` | Web/docs research with sources and a concise research brief. |
+| `researcher` | Web/docs research with sources and a concise research brief. Requires [pi-web-access in the child](docs/agents.md#web-research-prerequisites). |
+| `evidence-auditor` | Independently checks whether important research claims are supported by their sources. Requires [pi-web-access in the child](docs/agents.md#web-research-prerequisites). |
 | `worker` | Implementation work. Edits files, validates, escalates unapproved decisions instead of guessing. |
 | `reviewer` | Code review and small fixes against the task/plan, tests, edge cases, and simplicity. |
 | `oracle` | A second opinion before acting. Challenges assumptions without editing. |
 | `delegate` | A lightweight general delegate that behaves close to the parent session. |
 
-Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
+Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `evidence-auditor` before you rely on important research, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
 
 ## Common workflows
 
@@ -116,7 +117,7 @@ The full reference lives in `docs/`:
 | Doc | What's in it |
 |-----|--------------|
 | [Agents](https://github.com/nicobailon/pi-subagents/blob/main/docs/agents.md) | Custom agents, frontmatter reference, overriding builtins, tools, extensions, skills, per-agent memory. |
-| [Models](https://github.com/nicobailon/pi-subagents/blob/main/docs/models.md) | Default models, per-role overrides, recommended tiering, fallbacks, thinking levels, model scope enforcement, profiles. |
+| [Models](https://github.com/nicobailon/pi-subagents/blob/main/docs/models.md) | Single-model selection and launch, defaults, per-role overrides, recommended tiering, thinking levels, model scope enforcement, profiles. |
 | [Workflows](https://github.com/nicobailon/pi-subagents/blob/main/docs/workflows.md) | Orchestration patterns, prompt shortcuts, scripted workflows, worktree isolation, child-to-parent coordination, the recursion guard. |
 | [Watchdog](https://github.com/nicobailon/pi-subagents/blob/main/docs/watchdog.md) | The opt-in adversarial change reviewer, scope monitoring, LSP checks, and child tool permissions. |
 | [Tool reference](https://github.com/nicobailon/pi-subagents/blob/main/docs/tool-reference.md) | Every `subagent` parameter, management actions, status/control actions, acceptance gates, external CLI runners. |

package/agents/evidence-auditor.md

@@ -0,0 +1,34 @@
+---
+name: evidence-auditor
+description: Independent evidence reviewer for checking whether important research claims are supported by their sources
+tools: read, web_search, fetch_content, get_search_content, source_check
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+You are an evidence-auditing subagent.
+
+Given research findings or a brief produced by another agent, independently audit the evidence behind the small set of claims that could change the conclusion. Do not redo the original research or treat a supplied citation as proof. A URL is not evidence by itself: inspect the underlying source for material claims.
+
+Working rules:
+- Identify the decision-critical claims and prioritize claims that materially affect the recommendation or conclusion. Do not audit trivial details.
+- Distinguish evidence, source interpretation, and inference. Check whether the source actually supports the researcher's wording and level of certainty.
+- Prefer original, official, authoritative, and directly relevant sources. Flag material stale, weak, secondary, or circular sourcing.
+- Use `source_check` for important, disputed, surprising, or decision-relevant claims. It can return `supported`, `contradicted`, `unclear`, or `missing-evidence` assessments, source-quality hints, content hashes, and exact passage citations. Treat its result as validation evidence, not as a reason to skip inspecting the source.
+- Use `fetch_content` to inspect cited source pages and `get_search_content` to retrieve bounded slices of stored search or source-check content. Use `web_search` only for targeted follow-up searches needed to verify or challenge a material claim.
+- Record contradictions between claims or sources instead of silently resolving them. Preserve uncertainty when evidence is incomplete or conflicting.
+- Keep verification bounded. Report the material claims audited and any important claims left unverified; do not restart the entire research process.
+
+Output a concise audit with these sections:
+
+1. Verified claims
+2. Contradicted claims
+3. Weak / unclear / unsupported claims
+4. Material source-quality concerns
+5. Missing evidence
+6. Material contradictions
+7. Implications for the original conclusion
+
+For each material claim, include the claim, status (`supported`, `contradicted`, `unclear`, or `missing evidence`), relevant source(s), short reasoning, and confidence where useful. Explicitly label interpretation or inference. Say when no material issues were found.

package/agents/reviewer.md

@@ -79,8 +79,9 @@ Structure your findings clearly:
 When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.
 
 Filter findings by evidence, not by severity. Report only concrete current issues
-that are caused or made reachable by the target diff, and support each one with
-source proof, a test or repro, or a contract contradiction. Use P0 for issues
+within the named review target, and support each one with source proof, a test
+or repro, or a contract contradiction. For a diff review, require that the issue
+is caused or made reachable by that diff. Use P0 for issues
 that block merge, P1 for issues that should be fixed before release, and P2 for
 report-only notes. Say exactly `No issues found.` when nothing qualifies.
 

package/docs/agents.md

@@ -28,6 +28,7 @@ Discovery notes:
 - Project discovery also reads legacy `.agents/**/*.md` files. If both `.agents/` and the project config agents directory define the same parsed runtime agent name, the project config directory wins.
 - Nested subdirectories are discovered recursively. `.chain.md` files do not define agents.
 - User and project settings can add extra recursive scan roots with `subagents.agentScanDirs`; fixed user/project agent directories keep higher priority than same-name agents from scan roots.
+- Use `subagents.agentExcludeDirs` to prune literal directory subtrees without disabling legacy agents. See [configuration.md](configuration.md#excluded-agent-directories-settings) for path resolution, scope, and exemptions.
 - Installed Pi packages can expose agent directories from either `{"pi-subagents":{"agents":["./agents"]}}` or `{"pi":{"subagents":{"agents":["./agents"]}}}` in their package manifest. Package agents load above builtins and below user/project agents.
 - Use `agentScope: "user" | "project" | "both"` to control discovery. `both` is the default, and project definitions win runtime-name collisions.
 
@@ -39,12 +40,13 @@ Builtins load at the lowest priority, so a user or project agent with the same n
 |-------|--------------------------|
 | `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks, and where another agent should start. |
 | `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
+| `evidence-auditor` | Independent evidence review of important claims in an existing research brief. |
 | `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
 | `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
 | `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
 | `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
 
-Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
+Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `evidence-auditor` before you rely on important research, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
 
 `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `advisor` is the same bundled role under the Claude Code-compatible name.
 
@@ -184,13 +186,15 @@ Native `oracle` runs inside Pi and can use its configured read tools. The Claude
 | `external-job-requests/` and `external-job-responses/` | Host-mediated provider bridge | pending request, terminal response | Host process writes a matching response and removes the request | Bridge timeout or malformed request response | Requests are operation-scoped. Recovery sends `reattach`/`result`, not `start` or `follow-up`, when job metadata exists. `start` and `follow-up` use durable dispatch claims | Provider not registered, host bridge not loaded, malformed request, provider exception, ambiguous dispatch without a provider job id |
 | Provider artifact path | External provider | provider-defined terminal artifact | Provider returns `artifactPath`, or Pi writes returned text to `external-job-<index>.result.md` | Provider reports failure or no result | Existing artifact path is retained in `status.json` | Missing artifact with no text output returns a terminal message instead of inventing content |
 
-The `researcher` builtin uses `web_search`, `fetch_content`, `get_search_content`, and selective `source_check` validation. Those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
+### Web research prerequisites
+
+The `researcher` and `evidence-auditor` builtins use `web_search`, `fetch_content`, `get_search_content`, and selective `source_check` validation. Those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
 
 ```bash
 pi install npm:pi-web-access
 ```
 
-The loaded provider must register all four tools, including `source_check`, before launch; a missing required tool prevents a successful run. Fetched-source inspection is a fallback for a registered `source_check` call failing, not for missing registration.
+The provider must be loaded in the child and register all four tools, including `source_check`, before launch; a missing required tool prevents a successful run. Foreground children do not load ambient parent extensions: configure `extensions` or `subagentOnlyExtensions` explicitly, or use background extension discovery as described in [Tool and extension selection](#tool-and-extension-selection). For `researcher`, fetched-source inspection is a fallback for a registered `source_check` call failing, not for missing registration.
 
 ## Overriding builtins and custom agents
 
@@ -212,10 +216,10 @@ You can override selected agent fields without copying the whole agent. Override
 }
 ```
 
-Supported override fields: `description`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, and `systemPrompt`.
+Supported override fields: `description`, `machine`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, and `systemPrompt`.
 
 - `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
-- Use `output: false`, `defaultReads: false`, `defaultContext: false`, or `acceptanceRole: false` to clear an inherited value.
+- Use `output: false`, `defaultReads: false`, `defaultContext: false`, `acceptanceRole: false`, or `machine: false` to clear an inherited value.
 - Use `tools: "inherit"` when that one role should omit its bundled or frontmatter tool allowlist and receive Pi's normal builtins (plus ambient extensions when it runs as a background child).
 - Project overrides beat user overrides.
 - Matching package, user, and project agents also receive override fields, which replace the same fields declared in their frontmatter. This lets a shared agent keep its persona while local settings choose the effective model, context, tools, or other supported options.
@@ -230,6 +234,29 @@ Disable and restore:
 
 `eject`, `disable`, `enable`, and `reset` accept `agentScope: "user" | "project"` and operate in one scope at a time. Project overrides still win over user ones, so a project-scope disable survives a user-scope `enable` until you target the project scope.
 
+## Running external CLI agents on a Herdr saved machine
+
+Native Pi and the six code-owned Claude Code, Codex, and Cursor profiles can run on a Herdr machine (`herdr machine add <target> --label <name>`). Herdr owns each visible agent process in a fresh no-focus pane; SSH is used only as bounded transport for Herdr RPC and ownership checks. Herdr's catalog is the host allowlist; raw ssh targets are rejected.
+
+`machine` is a top-level frontmatter key, a settings override (`subagents.agentOverrides.<agent>.machine`, project beats user, `false` clears a pin), and a launch option on the `subagent` tool, workflow `runs.run`, chain, parallel, and dynamic-fanout steps. The launch option wins. Placement survives `subagent({ action: "disable" })`, `reset`, and model profile switches.
+
+`cwd` means the directory on that machine when a machine is set. An absolute path or `~/...` is used as given; a relative path joins the repo's configured machine root; with no cwd the root is used; with no root the launch fails closed naming the setting:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": { "claude-code": { "machine": "workmac" } },
+    "machines": { "workmac": { "cwd": "/home/nico/proj" } }
+  }
+}
+```
+
+`machines.<label-or-id>.env` is rejected. No local API key, vendor environment, expanded prompt resource, extension path, or callback is copied. Remote runs use the machine's own credentials and managed model registry. Bounded probes and ownership checks use a fixed machine-owned PATH without sourcing shell profiles.
+
+Placed external profiles are one-shot and stop-only: they cannot steer, resume, or claim a Pi supervisor. Their result is always `partial` and begins `[best-effort/unverified]`, because only bounded sanitized terminal snapshots are exposed; no vendor-private transcript, database, JSONL, or blob is used as authoritative settlement evidence. Reconnect observes the same pane and process without redispatching the prompt.
+
+pi-subagents never clones, pulls, or checks out on the machine. Generic `external-cli` commands and managed worktrees are rejected before launch; saved-machine placement accepts native Pi and only the six code-owned external profiles.
+
 ## Parent prompt discovery
 
 Set `advertise: true` in a specialist's agent file frontmatter for parent-prompt discovery. When the `subagent` tool is active, pi-subagents adds an agent-owned catalog of names and descriptions to the parent system prompt. Disabled agents and agents excluded by the current capability ceiling are omitted. Advertisement is not supported through settings overrides or runtime registration.
@@ -271,7 +298,6 @@ excludeTools: bash
 extensions:
 subagentOnlyExtensions: ./tools/child-only-search.ts
 model: claude-haiku-4-5
-fallbackModels: openai-codex/gpt-5.6-luna:low, anthropic/claude-sonnet-4
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: false
@@ -296,15 +322,12 @@ allowNestedSubagents: true
 Your system prompt goes here.
 ```
 
-Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `fallbackModels`, `extensions`, and `subagentOnlyExtensions`:
+Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
 
 ```yaml
 tools:
   - read
   - mcp:github/search_repositories
-fallbackModels:
-  - openai-codex/gpt-5.6-luna:low
-  - anthropic/claude-sonnet-4
 ```
 
 Field notes:
@@ -320,7 +343,6 @@ Field notes:
 | `extensions` | Omitted means a background child loads the parent's ambient extensions; empty means no ambient extensions; list values load exactly those extensions. Foreground children never load ambient extensions, so for them only listed values apply. |
 | `subagentOnlyExtensions` | Extension paths loaded only in this agent's child sessions. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
 | `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
-| `fallbackModels` | Ordered backup models for retryable provider/model failures before any tool activity. After tool work, only an eligible native foreground or background read-only HTTP 429 can continue once on a compatible same-configured-provider model, reopening the exact retained file with a fixed continuation prompt rather than replaying the task. This shares one recovery allowance with compaction-abort recovery and preserves the original deadline/cancellation. Ordinary task/deadline failures and external runners do not gain this exception. Requires the owned builtin `read`/`ls` profile without wait, coordination, custom tools or configured tool budgets. Foreground denies any configured usage budget; background permits only an authoritative remaining token allowance, not cost or unknown coverage. Retained history alone is insufficient. See [supported configuration and compatibility limits](models.md#native-read-only-continuation-after-http-429). |
 | `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
 | `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
 | `inheritProjectContext` | Keeps or strips inherited repository instruction blocks. |
@@ -343,6 +365,12 @@ Field notes:
 | `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
 | `memory` | Opt-in role-specific persistent memory. See below. |
 
+### Required host extensions
+
+Hosts can import `registerRequiredChildExtensions` from `pi-subagents/required-child-extensions` and register `{ sessionId, extensions: [{ id, path }] }`. Paths resolve to existing files and are canonicalized into an immutable launch snapshot; bounded safe IDs appear in evidence instead of paths. One registration is allowed per parent session until its idempotent `dispose()` runs, normally on `session_shutdown`.
+
+Required paths follow ordinary extension resolution and survive agent defaults and `extensions: []` across native foreground, detached, nested, and recovery launches. A `capabilityCeiling.denyExtensions` conflict or required load/provider-registration failure rejects before model resolution. External runners are excluded, and status/watch paths do not query the registry.
+
 When the completion guard would flag missing edits, a model intent arbiter can rescue only a confident read-only task. Foreground uses the parent model; native background uses the child attempt's existing model services after child shutdown. Ordinary completions do not invoke classification or resolve arbiter auth. Disabled arbitration (`PI_SUBAGENTS_LLM_INTENT_ARBITER=0`), unavailable model/auth, errors, ambiguous intent, and tasks over 8,000 characters keep the guard result. The classification prompt has a 10-second timeout; preceding auth and module loading are outside that bound. This does not change capability limits or the v1 contract's default-off guard and explicit missing-effect semantics.
 
 ## Per-agent persistent memory
@@ -406,7 +434,7 @@ How `tools` behaves:
 
 An allowlisted name does not load the extension that registers it. Load that provider through `extensions`, `subagentOnlyExtensions`, a path-like `tools` entry, or (background children only) normal Pi extension discovery.
 
-Ambient extensions depend on where the child runs. Foreground children are sessions inside the parent Pi process and never load the parent's ambient extensions; otherwise the parent would start a second copy of each ambient extension, including this one. Background children are sessions inside the detached runner process and load the ambient extensions unless the agent sets `extensions` or the capability ceiling denies extensions. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must therefore run as background children (`async: true`). A foreground launch of such an agent fails with a diagnostic that says exactly that.
+Ambient extensions depend on where the child runs. Local foreground children are sessions inside the parent Pi process and never load the parent's ambient extensions; otherwise the parent would start a second copy of each ambient extension, including this one. Background children are sessions inside the detached runner process and load the ambient extensions unless the agent sets `extensions` or the capability ceiling denies extensions. Local foreground children do inherit the providers the parent's extensions registered (`pi.registerProvider`), so their models resolve without loading those extensions again. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must therefore run as background children (`async: true`). A foreground launch of such an agent fails with a diagnostic that says exactly that.
 
 More rules:
 
@@ -495,15 +523,15 @@ Agent-local `skillPath` candidates never enter Pi's parent/global skills catalog
 
 ## The bundled pi-subagents skill
 
-The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. It is for the orchestrating parent only: child subagents never receive it, and their context is explicitly filtered to strip parent-only orchestration instructions.
+The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. Availability is not automatic routing or permission to delegate: the parent works directly unless the operator requests delegation in the current request or through applicable user/project instructions. Once authorized, use the smallest bounded child or workflow whose evidence, independent review, specialization, parallelism, or isolation benefit earns its overhead. It is for the orchestrating parent only: child subagents never receive it, and their context is explicitly filtered to strip parent-only orchestration instructions.
 
 What it covers:
 
-- **Delegation patterns**: when to launch which agent, whether to use single, parallel, chain, or async mode, and whether to use fresh or forked context.
+- **Delegation patterns**: how to select a bounded agent and single, parallel, scripted, or async shape after delegation is authorized, including fresh or forked context.
 - **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup.
 - **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers.
 - **Safety boundaries**: child agents must not run subagents unless their resolved builtin tools explicitly include `subagent`, must not invent intercom targets, and must escalate unapproved decisions.
 - **Intercom conventions**: when to ask vs send, and how parent-side supervisor/result delivery works through the native channel.
 - **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
 
-If you are writing an agent that orchestrates subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.
+If you are writing an agent that has been asked to orchestrate subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.