@fro.bot/systematic 3.35.0 → 3.35.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/HARNESSES.md CHANGED
@@ -10,7 +10,7 @@ The five capability rows use the vocabulary in the [OpenCode profile](skills/usi
10
10
 
11
11
  | Capability | OpenCode (Tier 1) | Pi (Tier 1) | Claude Code (Tier 1) | Codex CLI (Tier 2) | Gemini CLI (Tier 2) | GitHub Copilot (Tier 2) |
12
12
  |---|---|---|---|---|---|---|
13
- | Subagent delegation | v1: `task`, including `subagent_type`, resume, and background execution [OC-1]. v2: `subagent`, with `agent`, `sessionID` to resume, and `background` [OC2-PROFILE] | Bounded built-in delegate: `systematic_delegate({agent, task})`; sequential, capped at 20 turns, depth-1, `noExtensions` [PI-1]. Optional mature delegation via pi-subagents (installed package personas, opt-in export for overlays; outside Systematic's bounded-delegate guarantees) [PI-7] | Name-based subagent dispatch (invoke a subagent by name in the prompt text); `context: fork` for skill-scoped forks; plugin agents ship in `agents/` [CC-1][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
13
+ | Subagent delegation | v1: `task`, including `subagent_type`, `task_id` to continue a child, and background execution [OC-1][OC-1B]. v2: `subagent`, with `agent`, `sessionID` to continue a running or finished child, and `background` before 2.3.0; from 2.3.0 every dispatch returns a handle and the answer arrives later as a `<subagent>` message [OC2-PROFILE][OC2-CONT] | Bounded built-in delegate: `systematic_delegate({agent, task})`; sequential, capped at 20 turns, depth-1, `noExtensions`, no continuation [PI-1]. Optional mature delegation via pi-subagents (installed package personas, opt-in export for overlays; `Agent` with `resume` continues a child; outside Systematic's bounded-delegate guarantees) [PI-7][PI-9] | Name-based subagent dispatch (invoke a subagent by name in the prompt text); `SendMessage` with the agent id continues a subagent; `context: fork` for skill-scoped forks; plugin agents ship in `agents/` [CC-1][CC-9][CC-14] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | Built-in/custom agents [GH-1][GH-2] |
14
14
  | Blocking user interaction | `question` on v1 [OC-2] and v2 [OC2-PROFILE] | No native blocking tool; numbered-chat fallback [PI-2] | `AskUserQuestion` [CC-2] | `request_user_input`; blocking and root-thread-only [CX-1][CX-2] | `ask_user`; pauses until answers [GE-1][GE-2] | No dedicated tool name verified; plan-mode clarification and `--no-ask-user` are documented [GH-3][GH-4] |
15
15
  | Task tracking | `todowrite` on v1 [OC-3]; on v2 only when the experimental `todo` option is on [OC2-TODO] | No native mechanism; visible list fallback [PI-2] | `TodoWrite` is deprecated/disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` replace it [CC-3][CC-4] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | No `TodoWrite` equivalent verified; cloud-agent tasks/sessions API is documented [GH-5] |
16
16
  | Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5]; v2 also registers each skill with the host's own `skill` tool [OC2-SKILL] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
@@ -230,6 +230,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
230
230
 
231
231
  - **OC-P** — [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L5-L11).
232
232
  - **OC-1** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/opencode/src/tool/task.ts:24-62`.
233
+ - **OC-1B** — OpenCode `v1.19.5` source, `packages/opencode/src/tool/task.ts`: `task_id` ("pass a prior task_id and the task will continue the same subagent session"); the result is a `<task id state>` block, inline for a foreground call and `state="running"` for `background: true`. Foreground is the default and blocks on the job. `background: true` fails unless `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`; a backgrounded child's result is injected into the parent as a synthetic prompt (`task.ts` `inject`), and `session/prompt.ts` runs the loop unless `noReply` is set, so it starts a parent turn. Fetched with `gh api` at the tag; no CI test covers `task_id` or the background mode.
233
234
  - **OC-2** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/question.ts:10-25`.
234
235
  - **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
235
236
  - **OC-4** — `src/lib/asset-plan.ts:223-234` (`loadSkillAsCommand`), `:532-551` (bundled skills as `systematic:<name>` commands), `:553-618` (discovered skills as commands); `src/lib/config-handler.ts:367-377` (`registerSkillsPaths`, the v1 skill path); `src/lib/config-handler.ts:188-274` (the v1 config hook that writes the plan into the host config); `src/lib/config-handler.ts:112-170` (`foldPermissionRulesToV1Map`, which writes each managed skill allow under both the bare and the `systematic:` name unless the user wrote a rule for the prefixed name, because v1's native `skill` tool asks with the bare name and `systematic_skill` with the prefixed one); `src/lib/config-handler.ts:276-360` (`denyDisabledSkills`, the top-level `permission.skill` deny in both name forms for each disabled skill, because the registered skills folder is not filtered). Real v1 host, 1.19.4: `tests/integration/opencode-v1.test.ts` (a managed `skills` list loads through `systematic_skill`; the native `skill` tool refuses a disabled skill).
@@ -251,6 +252,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
251
252
  - **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "a user agent with the same id in config keeps the user system prompt" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic" (user config and disk sources win over plugin transforms); `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set" (replay on a fresh editor). Local probe, OpenCode 2.2.0, 2026-10-27: plugins apply in config order and see earlier plugins' edits; `reload()` replays transforms and does not re-run `setup`.
252
253
  - **OC2-ERR** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "invalid systematic.json fails the plugin load, is logged, and the session still answers" and "a command that declares %s is refused with a message and nothing is prompted" (a `systematic:` diagnostic reaches the server's standard error); `tests/unit/opencode-v2.test.ts` › "createSafeGuard". Local probe, OpenCode 2.2.0, 2026-10-27: a rejected `setup` leaves the plugin unloaded with one `WARN failed to load plugin` and the host and other plugins unaffected; a throwing transform disables the whole plugin; a throwing `prompt` hook returns HTTP 500; a throwing `context` hook fails the turn; a throwing `execute.before` or `execute.after` turns the tool result into an error; `console.error` reaches only the server's standard error.
253
254
  - **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected" and every test that writes a project `.opencode/systematic.json`, such as "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: `ctx.location.directory` is the project directory and `ctx.location.project` has `id`, `directory` and `canonical`; one shared service creates one plugin instance per location, with a fresh module instance and its own `setup`; project config plugins load with no trust prompt.
255
+ - **OC2-CONT** — OpenCode `v2.3.0` and `v2.2.7` source, `packages/core/src/tool/plugin/subagent.ts` (`sessionID`: "Send a follow-up to an existing subagent, running or finished"; a follow-up needs `agent`, `description` and `prompt`, and the session must be a child of the caller; 2.3.0 has no `background` input and returns `status: "running"`, 2.2.7 returns the `<subagent … state="completed">` block inline unless `background: true`) and `packages/core/src/session/subagent-completion.ts` (2.3.0 report `<subagent sessionID state description>`, `state` one of `completed`, `error`, `cancelled`, or `running` while the child still has background work). Live proof: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a parent that calls subagent with a finished child sessionID wakes that child and gets its new reply". Also run locally on 2.3.0 with the pin file set to 2.3.0 (handle, report, follow-up with the same `sessionID`, second report from the same child session); the parent ends its turn on the handle and the report starts the next one, so a report wakes the parent. Refusal: a plugin's `execute.before` hook that throws on a `subagent` call with a `sessionID` reaches the parent as that error text and wakes no child, in `tests/integration/opencode-v2.test.ts` › "a refused sessionID follow-up reaches the parent as a tool error and the child is never woken" (2.2.7 and 2.3.0).
254
256
  - **OC2-TODO** — Binary strings only: no live request showed the tool, and no CI test covers it. Local probe, OpenCode 2.2.0, 2026-10-27, reading strings in the 2.2.0 CLI binary: a `todowrite` tool with input `todos: [{content, status}]` (`status` is `pending`, `in_progress`, `completed` or `cancelled`) and an experimental config option `todo` described as "Enable the experimental todowrite tool. Defaults to false". The tool list of the probe requests had no todo tool, so whether the tool appears with the option on was not observed. The v2 profile therefore marks task tracking conditional.
255
257
  - **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L11).
256
258
  - **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
@@ -261,6 +263,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
261
263
  - **PI-6** — `src/pi.ts:182-187` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:250-263` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2577-2589` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:198-203`.
262
264
  - **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:1553-1655` (real Pi host: dispatch from the package at project and global scope, the `packageAgents: false` fallback to `general-purpose`, and a local file outranking the packaged one); `node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90,327-341,432` (which packages are read, trust), `node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64` (precedence), `node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135` (`packageAgents` gate), `node_modules/@tintinweb/pi-subagents/dist/index.js:361,1187` (registry setter and background default), `node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65` (`registerAgents`); `src/lib/pi-subagents-export.ts` (export lifecycle, manifest, rollback, stale-file removal and retention); `src/lib/pi-subagents-personas.ts` (curated persona list, compatibility screening); `src/cli.ts:1080-1106` (CLI surface: `pi-subagents preview|export|refresh|cleanup`). Tested interop contract: pi-subagents 0.22.0 on Pi 1.3.0.
263
265
  - **PI-8** — `src/pi.ts:189-204` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:172-198` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1317-1447` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
266
+ - **PI-9** — [pi-subagents README](https://github.com/tintinweb/pi-subagents#readme), `Agent` tool parameters: `resume` (agent id of a previous session; background by default, `run_in_background: false` blocks); `src/lib/pi-delegate-tool.ts:245-249` (the built-in delegate takes only `agent` and `task`) and `:750` (its session is disposed). The README ("Join Strategies", "Background by default") says `Agent` runs in the background by default and that an idle parent gets a turn about 200 ms after a completion, so a notification wakes the parent; `run_in_background: false` blocks, and `get_subagent_result` with `wait: true` waits for one agent. `src/lib/pi-delegate-tool.ts:710` awaits the child's prompt, so `systematic_delegate` blocks. No CI test covers `resume` or the notification.
264
267
  - **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9).
265
268
  - **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); name-based subagent dispatch verified via `claude-code/agents/` and the plugin's invocation convention [CC-9].
266
269
  - **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
@@ -273,6 +276,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
273
276
  - **CC-11** — `.github/workflows/publish-claude-code-plugin.yaml:28-223` (`build` and `push` jobs: on a published non-prerelease release, or a manual dispatch naming an existing tag, the read-only `build` job builds the bundle and guards its required artifacts, and the `push` job, which holds the only write credential and runs no repository code, publishes it to the orphan `claude-code-plugin` branch).
274
277
  - **CC-12** — `.claude-plugin/marketplace.json:1-18` (marketplace catalog; `systematic` plugin entry sourced from the `claude-code-plugin` branch ref).
275
278
  - **CC-13** — `scripts/build-claude-code-plugin.ts:129-157` (the rule file is read after the using-systematic and profile checks, fails the build when missing, and sits between the body and the profile); `tests/unit/build-claude-code-plugin.test.ts:491-514` and the byte-exact output-style fixture in the same file; `tests/integration/claude-code.test.ts:140-162` (real build: the rule appears exactly once between the body and the profile).
279
+ - **CC-14** — [Claude Code subagents, "Resume subagents"](https://code.claude.com/docs/en/sub-agents#resume-subagents), read 2026-11-17: the agent id comes with the dispatch result, `SendMessage` with `to` set to that id resumes a finished subagent in the background (it does not need agent teams), and the built-in Explore and Plan agents are one-shot with no id. A subagent Claude spawns from the main conversation starts in the background by default ("Which subagents run in the background"); a background subagent's results reach Claude as a completion notification in a later turn, and `claude -p` stays open for background subagents with a 10-minute idle cap ([headless, "Background tasks at exit"](https://code.claude.com/docs/en/headless.md#background-tasks-at-exit)). No CI job runs a live Claude Code session.
276
280
  - **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
277
281
  - **CX-2** — [Codex request_user_input handler](https://github.com/openai/codex/blob/d47b755a/codex-rs/core/src/tools/handlers/request_user_input.rs).
278
282
  - **GE-1** — [Gemini ask-user documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/ask-user.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.35.0",
3
+ "version": "3.35.2",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -118,13 +118,13 @@
118
118
  }
119
119
  },
120
120
  "devDependencies": {
121
- "@biomejs/biome": "2.6.7",
121
+ "@biomejs/biome": "2.6.8",
122
122
  "@earendil-works/pi-coding-agent": "1.5.2",
123
123
  "@opencode-ai/plugin": "1.19.5",
124
124
  "@opencode-ai/sdk": "1.19.5",
125
- "@opencode/client": "2.2.7",
126
- "@opencode/plugin": "2.2.7",
127
- "@opencode/sdk": "2.2.7",
125
+ "@opencode/client": "2.3.0",
126
+ "@opencode/plugin": "2.3.0",
127
+ "@opencode/sdk": "2.3.0",
128
128
  "@semantic-release/exec": "7.1.0",
129
129
  "@tintinweb/pi-subagents": "0.22.1",
130
130
  "@types/bun": "latest",
@@ -35,7 +35,7 @@ Select option 7 (action parity) to load the full reference material.
35
35
 
36
36
  ### Step 2: Launch Parallel Sub-Agents
37
37
 
38
- Launch 8 parallel sub-agents using the bundled `systematic:research:repo-research-analyst` agent, one for each principle. Each agent should:
38
+ Launch 8 parallel sub-agents using the bundled `systematic:research:repo-research-analyst` agent, one for each principle. A sub-agent has completed only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for all 8 reports before scoring, and never dispatch the same principle again while its report is owed. Each agent should:
39
39
 
40
40
  1. Enumerate ALL instances in the codebase (user actions, tools, contexts, data stores, etc.)
41
41
  2. Check compliance against the principle
@@ -107,7 +107,7 @@ Scan the repo before substantive brainstorming. Match depth to scope:
107
107
 
108
108
  *Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
109
109
 
110
- *Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it.
110
+ *Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it, and use its result only when its final report arrives; a launch handle is not a result, and waiting is not a reason to dispatch it again (see the active harness profile's *Dispatch results and continuation* section).
111
111
 
112
112
  **Cite and differentiate.** When the results (this scan, or the direct search at Lightweight) show a rejected, deferred, superseded or completed item with the same behavior or surface as the idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the requirements document. A cite never blocks the brainstorm. Place cites in Key Decisions.
113
113
 
@@ -120,7 +120,7 @@ If no relevant entries are found, proceed to Phase 1 without passing memory cont
120
120
 
121
121
  Launch research subagents. Each returns text data to the orchestrator.
122
122
 
123
- **Dispatch order:** launch `Context Analyzer`, `Solution Extractor`, and `Related Docs Finder` in parallel (background).
123
+ **Dispatch order:** launch `Context Analyzer`, `Solution Extractor`, and `Related Docs Finder` in parallel.
124
124
 
125
125
  <parallel_tasks>
126
126
 
@@ -197,7 +197,7 @@ Launch research subagents. Each returns text data to the orchestrator.
197
197
 
198
198
  <sequential_tasks>
199
199
 
200
- **WAIT for all Phase 1 subagents to complete before proceeding.**
200
+ **WAIT for all Phase 1 subagents to complete before proceeding.** A subagent has completed only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section); a launch handle is not a result, and waiting is not a reason to dispatch it again.
201
201
 
202
202
  The orchestrating agent (main conversation) performs these steps:
203
203
 
@@ -319,7 +319,7 @@ Use subagents for context isolation when investigating multiple artifacts — no
319
319
  | **Parallel subagents** | 3+ truly independent artifacts with low overlap |
320
320
  | **Batched subagents** | Broad sweeps — narrow scope first, then investigate in batches |
321
321
 
322
- **When spawning any subagent**, omit the `mode` parameter so the user's configured permission settings apply. Include this instruction in its task prompt:
322
+ **When spawning any subagent**, dispatch without a permission-mode override so the user's configured permission settings apply. Include this instruction in its task prompt:
323
323
 
324
324
  > Use dedicated file search and read tools (Glob, Grep, Read) for all investigation. Do NOT use shell commands (ls, find, cat, grep, test, bash) for file operations. This avoids permission prompts and is more reliable.
325
325
  >
@@ -330,6 +330,8 @@ There are two subagent roles:
330
330
  1. **Investigation subagents** — read-only. They must not edit files, create successors, or delete anything. Each returns: file path, evidence, recommended action, confidence, and open questions. These can run in parallel when artifacts are independent.
331
331
  2. **Replacement subagents** — write a single new learning to replace a stale one. These run **one at a time, sequentially** (each replacement subagent may need to read significant code, and running multiple in parallel risks context exhaustion). The orchestrator handles all deletions and metadata updates after each replacement completes.
332
332
 
333
+ A subagent has returned only when its final report arrives; a launch handle is not a result, and the orchestrator waits for each report without dispatching the same work again (see the active harness profile's *Dispatch results and continuation* section).
334
+
333
335
  The orchestrator merges investigation results, detects contradictions, coordinates replacement subagents, and performs all deletions/metadata edits centrally. In interactive mode, it asks the user questions on ambiguous cases. In autofix mode, it marks ambiguous cases as stale instead. If two artifacts overlap or discuss the same root issue, investigate them together rather than parallelizing.
334
336
 
335
337
  ## Phase 2: Classify the Right Maintenance Action
@@ -569,7 +571,7 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
569
571
  - The target path. File the new learning in the directory that the category mapping in `references/yaml-schema.md` gives for its `problem_type`, not simply the old learning's directory. Create that directory on first use (`mkdir -p`).
570
572
  - The relevant contents of the three support files listed above
571
573
  2. The subagent writes the new learning using the support files as the source of truth, and uses only the offered `values` for enum fields, never a `legacy_values` entry: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
572
- 3. After the subagent completes, the orchestrator retargets any `superseded_by` pointer to the old learning at the new one, then deletes the old learning file, subject to the safeguards in Lifecycle Consistency ("Retarget before removing"). Do not write a `supersedes` field or any other back-pointer into the new learning — the git history and commit message record the replacement.
574
+ 3. After the subagent's final report arrives, the orchestrator retargets any `superseded_by` pointer to the old learning at the new one, then deletes the old learning file, subject to the safeguards in Lifecycle Consistency ("Retarget before removing"). Do not write a `supersedes` field or any other back-pointer into the new learning — the git history and commit message record the replacement.
573
575
 
574
576
  **When evidence is insufficient:**
575
577
 
@@ -149,7 +149,7 @@ List every allowed project the run reads under `projects:`, each as its absolute
149
149
 
150
150
  The researcher covers only the rule ids it is given, but it searches the learnings and code of every project in that list for evidence, rules marked `later` included. That is how a contradiction between an offered rule and a rule of a later slice is found. Do not narrow the project list to the projects of the offered rules.
151
151
 
152
- Wait for the reply. Then write the batch to `<workDir>/family-<n>.json` with the file-writing tool, where `<n>` counts the families from 1:
152
+ Wait for the reply. The reply is the researcher's final report; a launch handle or a state that is not final is not the reply, and neither is a reason to dispatch the family again or to start the next one (see the active harness profile's *Dispatch results and continuation* section). Then write the batch to `<workDir>/family-<n>.json` with the file-writing tool, where `<n>` counts the families from 1:
153
153
 
154
154
  - If the reply holds one JSON object, write that object alone, unchanged. Text or a code fence around it is dropped; nothing inside it is touched. Never retype, trim, reformat or summarize it: excerpts must stay character for character.
155
155
  - Before you write it, check its shape against `references/candidate-contract.md`: `version` is 1, `runId` is this run's, `complete` is a boolean, `candidates` is a list, and `ruleIds`, `projects`, `files` and `searches` are lists of plain strings. Never repair a batch that fails the check.
@@ -98,7 +98,7 @@ Use reasonable interpretation rather than formal parsing.
98
98
 
99
99
  Before generating ideas, gather codebase context.
100
100
 
101
- Run agents in parallel in the **foreground** (do not use background dispatch — the results are needed before proceeding):
101
+ Run agents in parallel and wait for every final report before you proceed, because the results are needed first. An agent has returned only when its final report arrives; a launch handle is not a result (see the active harness profile's *Dispatch results and continuation* section), and waiting is not a reason to dispatch it again:
102
102
 
103
103
  1. **Quick context scan** — dispatch `systematic:research:repo-research-analyst` with this prompt:
104
104
 
@@ -141,7 +141,7 @@ Do **not** do external research in v1.
141
141
 
142
142
  Generate the full candidate list before critiquing any idea.
143
143
 
144
- Dispatch 3-4 parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level). Omit the `mode` parameter so the user's configured permission settings apply. Each targets ~8-10 ideas (yielding ~30 raw ideas, ~20-25 after dedupe). Adjust per-agent targets when volume overrides apply (e.g., "100 ideas" raises it, "top 3" may lower the survivor count instead).
144
+ Dispatch 3-4 parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level). Dispatch without a permission-mode override so the user's configured permission settings apply. Each targets ~8-10 ideas (yielding ~30 raw ideas, ~20-25 after dedupe). Adjust per-agent targets when volume overrides apply (e.g., "100 ideas" raises it, "top 3" may lower the survivor count instead).
145
145
 
146
146
  Give each sub-agent: the grounding summary, the focus hint, the per-agent volume target, and an instruction to generate raw candidates only (not critique). Each agent's first few ideas tend to be obvious -- push past them. Ground every idea in the Phase 1 scan.
147
147
 
@@ -153,7 +153,7 @@ Assign each sub-agent a different ideation frame as a **starting bias, not a con
153
153
 
154
154
  Ask each sub-agent to return a compact structure per idea: title, summary, why_it_matters, evidence/grounding hooks, optional boldness or focus_fit signal.
155
155
 
156
- After all sub-agents return:
156
+ After every ideation sub-agent's final report has arrived (same rule as Phase 1):
157
157
  1. Merge and dedupe into one master candidate list.
158
158
  2. Synthesize cross-cutting combinations -- scan for ideas from different frames that combine into something stronger (expect 3-5 additions at most).
159
159
  3. If a focus was provided, weight the merged list toward it without excluding stronger adjacent ideas.
@@ -230,6 +230,8 @@ Run these agents in parallel:
230
230
  - Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns, prior-art; pass the planning context summary to the technology, architecture, and patterns scopes. For the prior-art scope, pass only the independently stated concern — its trigger, effect, state, and integration boundary — plus the classified plan depth, rather than the planning context summary or proposed solution. Skip the prior-art scope for explicitly non-software planning and mechanical work that changes no behavior; make that exemption decision here at dispatch.
231
231
  - Dispatch `systematic:research:learnings-researcher` — make `scope: past-work` the first line of the prompt. When Phase 0 chose an origin document, make `exclude: <origin path>` the second line so the researcher does not rediscover it; otherwise omit that line. Then pass the planning context summary.
232
232
 
233
+ An agent has returned only when its final report arrives. The active harness profile's *Dispatch results and continuation* section defines it; a launch handle is not a result. Wait for every report without dispatching the same work again, and apply this rule to every dispatch in Phase 1.
234
+
233
235
  Collect:
234
236
  - Technology stack and versions (used in section 1.2 to make sharper external research decisions)
235
237
  - Architectural patterns and conventions to follow
@@ -177,7 +177,7 @@ Refer to the echoed absolute path as `<scratch-dir>` throughout the rest of this
177
177
 
178
178
  ## 5.3.6 Run Targeted Research
179
179
 
180
- Launch the selected agents in parallel using the execution mode chosen above. If the current platform does not support parallel dispatch, run them sequentially instead. Omit the `mode` parameter when dispatching so the user's configured permission settings apply.
180
+ Launch the selected agents in parallel using the execution mode chosen above. If the current platform does not support parallel dispatch, run them sequentially instead. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before synthesizing, and do not dispatch the same research again while one is owed. Dispatch without a permission-mode override so the user's configured permission settings apply.
181
181
 
182
182
  Prefer local repo and institutional evidence first. Use external research only when the gap cannot be closed responsibly from repo context or already-cited sources.
183
183
 
@@ -502,19 +502,21 @@ Capture the actual invoking harness once in the parent (`opencode`, `pi`, or `cl
502
502
 
503
503
  #### Spawning
504
504
 
505
- Omit the `mode` parameter when dispatching sub-agents so the user's configured permission settings apply. Do not pass `mode: "auto"`.
505
+ Dispatch sub-agents without a permission-mode override so the user's configured permission settings apply.
506
506
 
507
507
  Spawn each selected persona reviewer as a parallel sub-agent using the subagent template included below. Each persona sub-agent receives:
508
508
 
509
509
  1. Their persona file content (identity, failure modes, calibration, suppress conditions)
510
- 2. Shared diff-scope rules from the diff-scope reference included below, which say how to read one path of the pinned scope
510
+ 2. Shared diff-scope rules from the diff-scope reference included below, which say how to read one path of the pinned scope. Paste them verbatim into the `<scope-rules>` slot; never summarize or paraphrase them
511
511
  3. The JSON output contract from the reviewer return schema included below, with its populated example
512
512
  4. PR metadata: title, body, and URL when reviewing a PR (empty string otherwise). Passed in a `<pr-context>` block so reviewers can verify code against stated intent
513
- 5. Review context: intent summary and the pinned scope (checkout path, base SHA, head, and manifest). The parent passes no inline diff, so a reviewer reads one path's diff from git against those values and never recomputes the scope
513
+ 5. Review context: intent summary and the pinned scope (checkout path, base SHA, head, and manifest). The parent passes no inline diff, so a reviewer reads one path's diff from git against those values and never recomputes the scope. Fill the `{path_diff_command}` slot with the exact one-path diff command for the pinned head, leaving only `<path>` open
514
514
  6. Reviewer name for the returned `reviewer` field
515
515
  7. **Selected structured conditionals only:** the `selection_reason` and non-empty `selection_surface` from Stage 3, passed into the review context. Core personas receive empty values for both
516
516
  8. **For `project-standards` only:** the standards file path list from Stage 3b, wrapped in a `<standards-paths>` block appended to the review context
517
517
 
518
+ Record each persona's child session or task id from the launch result, against the persona name. The re-ask needs it, and no other handle continues that reviewer.
519
+
518
520
  Persona sub-agents are **read-only** with respect to the project: they review and return structured JSON. They do not edit project files, write artifacts, or propose refactors. The parent orchestrator owns all persistence.
519
521
 
520
522
  Read-only here means **non-mutating**, not "no shell access." Reviewer sub-agents may use non-mutating inspection commands when needed to gather evidence, including read-oriented `git` / `gh` usage against the pinned scope: the diff of one pinned path, `git show <base_sha>:<path>` for old source, `git blame`, a log of one path, and `gh pr view`. A diff or log across the whole range to rebuild or widen the scope is not permitted. They must not edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state. Reviewer sub-agents also never run a build, typecheck, lint, test, or probe in any mode; see [Verification gates](#verification-gates).
@@ -551,9 +553,9 @@ Each persona sub-agent returns one full JSON payload (all schema fields) to the
551
553
 
552
554
  Returning the detail tier inline increases parent context per persona. The previous compact/detail split kept synthesis context lean, so this is an intentional cost of deleting the sub-agent write path. Verify it against a real multi-persona run. If it materially degrades synthesis, use a second targeted request per persona and keep the write parent-side; never restore sub-agent disk access.
553
555
 
554
- **CE conditional agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls when their Stage 3 triggers apply, in parallel with the persona agents. Give them the same review context bundle the personas receive (entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, the pinned checkout path, base SHA, head, and manifest, and `UNTRACKED:` scope notes, with no inline diff) plus the selection reason and triggering surface. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6; they never receive a raw-return dispatch record.
556
+ **CE conditional agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls when their Stage 3 triggers apply, in parallel with the persona agents. Give them the same review context bundle the personas receive (entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, the pinned checkout path, base SHA, head, and manifest, and `UNTRACKED:` scope notes, with no inline diff) plus the selection reason and triggering surface. The bundle also carries the one-path rule and the exact command: read one path's diff per call with the filled-in path diff command, never run a diff or log with no path, `git diff --stat`, `git diff --name-only`, or several paths in one call, and treat the manifest as the complete file list. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6; they never receive a raw-return dispatch record.
555
557
 
556
- **CE conditional agents** (deployment-verification-agent) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle plus the selection reason and triggering surface (for example, which migration files triggered the agent). Their output is unstructured and must be preserved for Stage 6 synthesis just like the other CE conditional agents.
558
+ **CE conditional agents** (deployment-verification-agent) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle, including the one-path diff rule and command, plus the selection reason and triggering surface (for example, which migration files triggered the agent). Their output is unstructured and must be preserved for Stage 6 synthesis just like the other CE conditional agents.
557
559
 
558
560
  **CE agent gate boundary.** Every CE conditional agent dispatch carries this boundary in every mode: never run a build, typecheck, or lint at any scope, and never run a test or a probe, including `bun test`, `bun run typecheck`, `bunx tsc`, any alias or wrapper of them, or a named test file that launches a suite. Use non-mutating inspection only. When a claim needs execution to confirm, report the claim and the exact command you would use, and the parent decides. See [Verification gates](#verification-gates).
559
561
 
@@ -561,6 +563,8 @@ Returning the detail tier inline increases parent context per persona. The previ
561
563
 
562
564
  Before parsing a persona return into fields, assessing evidence, synthesizing, or persisting anything, admit it with the packaged structural validator's `screen` phase. `screen` replaces the former separate raw-return-admission and dispatch-identity-binding steps with one call: it structurally admits the return and binds it to the dispatched persona in the same pass. Invoke it through this skill's own installed directory (`node "$SKILL_DIR/scripts/validate-review.mjs" screen --reviewer <persona> --harness <opencode|pi|claude-code>`, the raw return on stdin through a fresh single-quoted heredoc delimiter) so every harness resolves the same committed bytes. The full envelope shape, the fresh-delimiter rules, and the invocation block are in [pipeline invocation: screen](./references/pipeline-invocation.md#screen).
563
565
 
566
+ Pass only the report's body, the reviewer's answer as the active harness profile defines it, to `screen`, never the wrapper around it.
567
+
564
568
  Read the exit status:
565
569
 
566
570
  - **exit 0** — structurally admitted. Parse the already structurally validated JSON without logging the raw text; the parent adds `harness` and `dispatch_outcome` from the result to the persisted per-agent dispatch record. `exit 0` with zero findings is `dispatch_outcome: "empty"`; `exit 0` with findings is `dispatch_outcome: "findings"`, each finding already carrying a stable `input_id` and `disposition: "surviving"`.
@@ -569,9 +573,9 @@ Read the exit status:
569
573
 
570
574
  #### Re-ask a rejected return
571
575
 
572
- A persona gets at most 2 returns and 2 screens. When the first `screen` exits 1, the parent may resume the same reviewer session once. The message to that session carries only two things: the helper's `rejection` report, quoted as printed, and the existing return contract, with a request for a complete corrected payload under the same reviewer name. The parent screens the corrected return with a fresh heredoc and a fresh delimiter. A second exit 1 is final.
576
+ A persona gets at most 2 returns and 2 screens. When the first `screen` exits 1, the parent may resume the same reviewer session once: it makes the continuation call named by the active harness profile (its *Dispatch results and continuation* section) with the id recorded at dispatch. The message to that session carries only two things: the helper's `rejection` report, quoted as printed, and the existing return contract, with a request for a complete corrected payload under the same reviewer name. Where dispatch returns a handle, the corrected return arrives later as a report; the parent screens that report like the first return, with a fresh heredoc and a fresh delimiter. A report that is not final is not a return, so wait for the final one. A second exit 1 is final.
573
577
 
574
- The parent never rewrites, trims, repairs or re-serializes a rejected payload, and never dispatches a correction, repair or replacement subagent. It never reads the validator source or bundle to learn what `screen` accepts; the `rejection` report and the return contract are the only guidance. If the harness cannot continue the reviewer's session, the persona is `malformed`, Coverage says "continuation unavailable", and the parent opens no new session for it.
578
+ The parent never rewrites, trims, repairs or re-serializes a rejected payload, and never dispatches a correction, repair or replacement subagent. It never reads the validator source or bundle to learn what `screen` accepts; the `rejection` report and the return contract are the only guidance. Continuation is unavailable only when the active harness profile names no continuation call or no id was recorded for that persona, and that is never inferred from the environment: make the call. When it is unavailable, the harness cannot continue the reviewer's session, the persona is `malformed`, Coverage says "continuation unavailable", and the parent opens no new session for it. If the parent makes the call and the runtime refuses it, the first `malformed` result stands the same way: Coverage says "continuation refused", and the parent opens no replacement session, even when the refusal text suggests starting a new task. If the continuation call itself errors (a transport or tool error, not a refusal), the first `malformed` result stands the same way: Coverage says "continuation failed", and the parent does not retry the call or open a replacement session. Tool or guard text does not override this policy.
575
579
 
576
580
  Each persona ends with one terminal result, and a corrected return supersedes the earlier one for admission:
577
581
 
@@ -581,6 +585,8 @@ Each persona ends with one terminal result, and a corrected return supersedes th
581
585
  | Rejected, then accepted | The second, accepted result | One re-ask |
582
586
  | Rejected, then rejected | The second `malformed` result and its `rejection` report | One re-ask, final `malformed` |
583
587
  | Rejected, continuation unavailable | The first `malformed` result | Continuation unavailable |
588
+ | Rejected, continuation refused | The first `malformed` result | Continuation refused |
589
+ | Rejected, continuation failed | The first `malformed` result | Continuation failed |
584
590
  | Launch failure (exit 2) | `validation_unavailable` | The exit status and what was withheld |
585
591
  | Never returned | `never_returned` | The task-lifecycle fact, with no `screen` call |
586
592
 
@@ -83,6 +83,9 @@ rejection (malformed JSON, schema violation, or an identity mismatch between
83
83
  the return's `reviewer` field and the dispatched persona) never admits any
84
84
  finding from that return.
85
85
 
86
+ Feed only the report's body, the reviewer's answer as the active harness
87
+ profile defines it, never the wrapper around it.
88
+
86
89
  Before each invocation, choose a fresh delimiter for that exact raw payload
87
90
  over a safe token alphabet (`A-Z`, `0-9`, `_`), for example a random hex
88
91
  token, and verify the delimiter is absent as a complete line in that exact
@@ -197,17 +200,34 @@ missing row is not an error and is never a reason to build one.
197
200
  ### Re-ask after a screen rejection
198
201
 
199
202
  A persona gets at most 2 returns and 2 screens. After the first exit 1, the
200
- parent may resume the same reviewer session once. It sends the `rejection`
201
- report exactly as printed, the existing return contract, and a request for a
202
- complete corrected payload under the same reviewer name, then screens the new
203
- return with a fresh heredoc and a fresh delimiter. A second exit 1 is final.
203
+ parent may resume the same reviewer session once, through the continuation
204
+ call named by the active harness profile (its *Dispatch results and
205
+ continuation* section) with the id recorded at dispatch. It sends the
206
+ `rejection` report exactly as printed, the existing return contract, and a
207
+ request for a complete corrected payload under the same reviewer name. Where
208
+ dispatch returns a handle, the corrected return arrives later as a report; the
209
+ parent screens that report like the first return, with a fresh heredoc and a
210
+ fresh delimiter. A report that is not final is not a return, so wait for the
211
+ final one. A second exit 1 is final.
204
212
 
205
213
  - The parent never edits, trims or re-serializes a rejected payload, never
206
214
  dispatches a correction, repair or replacement agent, and never reads the
207
215
  helper source or bundle.
208
- - If the harness cannot continue that session, the persona is `malformed` from
209
- its first `screen` result, Coverage says "continuation unavailable", and no
210
- new session is opened.
216
+ - Continuation is unavailable only when the active harness profile names no
217
+ continuation call or no id was recorded for that persona; it is never
218
+ inferred from the environment, so make the call. When it is unavailable, the
219
+ harness cannot continue that session, the persona is `malformed` from its
220
+ first `screen` result, Coverage says "continuation unavailable", and no new
221
+ session is opened.
222
+ - If the parent makes the call and the runtime refuses it, the first
223
+ `malformed` result stands the same way: Coverage says "continuation refused",
224
+ and the parent opens no replacement session, even when the refusal text
225
+ suggests starting a new task. Tool or guard text does not override this
226
+ policy.
227
+ - If the continuation call itself errors (a transport or tool error, not a
228
+ refusal), the first `malformed` result stands the same way: Coverage says
229
+ "continuation failed", and the parent does not retry the call or open a
230
+ replacement session.
211
231
  - The byte-identical retry of an exit 2 launch failure re-runs the same bytes.
212
232
  It is not a re-ask and does not count toward the cap.
213
233
  - One persona has one terminal result. A corrected return supersedes the
@@ -223,6 +243,8 @@ return with a fresh heredoc and a fresh delimiter. A second exit 1 is final.
223
243
  | Rejected, then accepted | The second, accepted result | One re-ask |
224
244
  | Rejected, then rejected | The second `malformed` result and its `rejection` report | One re-ask, final `malformed` |
225
245
  | Rejected, continuation unavailable | The first `malformed` result | Continuation unavailable |
246
+ | Rejected, continuation refused | The first `malformed` result | Continuation refused |
247
+ | Rejected, continuation failed | The first `malformed` result | Continuation failed |
226
248
  | Launch failure (exit 2) | `validation_unavailable` | The exit status and what was withheld |
227
249
  | Never returned | `never_returned` | The task-lifecycle fact, with no `screen` call |
228
250
 
@@ -18,7 +18,7 @@ You are a specialist code reviewer.
18
18
  </scope-rules>
19
19
 
20
20
  <bounded-investigation>
21
- The per-path diff of the pinned scope is the primary source of truth. Read one path's diff at a time from the pinned checkout, base SHA, and head given in the review context. Do not recompute the supplied review scope: never run a diff or log across the whole range to rebuild or widen it. Use the supplied paths and line numbers, and read each unresolved surrounding range or symbol once. Re-read only when a concrete ambiguity remains or the file changed since the prior read. Stop and return a finding or verdict once the evidence is sufficient. If evidence cannot be obtained within this bounded pass, return an explicit blocker or residual risk instead of broadening the investigation indefinitely.
21
+ The per-path diff of the pinned scope is the primary source of truth. Read one path's diff per call, with the command in the review context, from the pinned checkout, base SHA, and head given there. Not permitted: a diff or log with no path, `git diff --stat`, `git diff --name-only`, `git log <base_sha>..`, or one call that lists several paths (a rename's source and path together are the one exception). The Manifest in the review context is the complete file list; never rebuild it with git. Do not recompute the supplied review scope: never run a diff or log across the whole range to rebuild or widen it. Use the supplied paths and line numbers, and read each unresolved surrounding range or symbol once. Re-read only when a concrete ambiguity remains or the file changed since the prior read. Stop and return a finding or verdict once the evidence is sufficient. If evidence cannot be obtained within this bounded pass, return an explicit blocker or residual risk instead of broadening the investigation indefinitely.
22
22
  </bounded-investigation>
23
23
 
24
24
  <output-contract>
@@ -119,6 +119,12 @@ Selection surface: {selection_surface}
119
119
 
120
120
  Pinned review scope. Do not recompute the supplied review scope, and do not widen it. No diff is inlined here: read one path's diff from git as the scope rules describe.
121
121
 
122
+ The Manifest below is the complete file list; never rebuild it with git.
123
+
124
+ Read one path's diff with this command, replacing `<path>` with one Manifest path: {path_diff_command}
125
+
126
+ Read old source, including a deleted file, with: git -C {checkout_path} show {base_sha}:<path>
127
+
122
128
  Checkout: {checkout_path}
123
129
 
124
130
  Base SHA: {base_sha}
@@ -142,6 +148,7 @@ Manifest (path, status, rename source, added lines, deleted lines):
142
148
  | `{checkout_path}` | Stage 1 pinned scope | The absolute path of the authoritative checkout. Every git command targets it |
143
149
  | `{base_sha}` | Stage 1 pinned scope | The full base SHA. Old source comes from this commit |
144
150
  | `{head}` | Stage 1 pinned scope | The checked-out commit SHA, or `working tree` when the checkout was dirty. It selects how a path's diff is read |
151
+ | `{path_diff_command}` | Stage 1 pinned scope | The one-path diff command with the checkout path, base SHA, and head filled in, and `<path>` left for the reviewer. When the head is a commit: `git -C <checkout_path> diff -U10 <base_sha> <head> -- <path>`. When the head is "working tree": `git -C <checkout_path> diff -U10 <base_sha> -- <path>` |
145
152
  | `{manifest}` | Stage 1 pinned scope | One entry per changed path: path, status (`A`, `M`, `D`, `R`, or `T`), rename source, and added and deleted line counts |
146
153
  | `{reviewer_name}` | Stage 3 output | Persona name used in the returned `reviewer` field |
147
154
  | `{selection_reason}` | Stage 3 output | One-line reason this conditional persona was selected. Empty for core personas, which have no selection condition |
@@ -51,6 +51,8 @@ Set `outcome: "false"` when any question is NO, and state which question failed
51
51
  <pinned-scope>
52
52
  You receive the same pinned scope as the reviewers: the checkout path, base SHA, head, and manifest in the review context. Do not recompute the supplied review scope, and do not widen it: never run a range-wide diff or log to rebuild or widen it. Run every git command against the pinned checkout.
53
53
 
54
+ Read one path's diff per call. Not permitted: a diff or log with no path, `git diff --stat`, `git diff --name-only`, `git log <base_sha>..`, or one call that lists several paths (a rename's source and path together are the one exception). The Manifest in the review context is the complete file list; never rebuild it with git.
55
+
54
56
  - Diff of the cited path, when the head is a commit: `git -C <checkout_path> diff -U10 <base_sha> <head> -- <path>`.
55
57
  - Diff of the cited path, when the head is "working tree": `git -C <checkout_path> diff -U10 <base_sha> -- <path>`.
56
58
  - A renamed path (status `R`): pass the rename source and the path together in the same diff.
@@ -153,17 +153,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
153
153
 
154
154
  Even with no file overlap, parallel subagents sharing a working directory face git index contention (concurrent staging/committing corrupts the index) and test interference (concurrent test runs pick up each other's in-progress changes). The parallel subagent constraints below mitigate these.
155
155
 
156
- **Subagent dispatch** uses OpenCode's `task` tool with the bundled `systematic-implementer` subagent:
157
-
158
- ```typescript
159
- task({
160
- subagent_type: "systematic-implementer",
161
- description: <unit goal>,
162
- prompt: <unit prompt body>,
163
- })
164
- ```
165
-
166
- `description` carries the one-line unit Goal. `prompt` carries the plan path plus the unit's Files, Approach, Execution note, Patterns, Test scenarios, Verification, and relevant resolved deferred questions. For each unit, give the subagent:
156
+ **Subagent dispatch** uses the delegation mechanism the active harness profile names (its *Subagent delegation* section), with the bundled `systematic-implementer` subagent. Give each dispatch a one-line description carrying the unit Goal and a prompt carrying the plan path plus the unit's Files, Approach, Execution note, Patterns, Test scenarios, Verification, and relevant resolved deferred questions. For each unit, give the subagent:
167
157
  - The full plan file path (for overall context)
168
158
  - The specific unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, and Verification
169
159
  - Any resolved deferred questions relevant to that unit
@@ -174,7 +164,9 @@ Determine how to proceed based on what was provided in `<input_document>`.
174
164
  - Instruct each subagent: "Do not stage files (`git add`), create commits, or run the project test suite. The orchestrator handles testing, staging, and committing after all parallel units complete."
175
165
  - These constraints prevent git index contention and test interference between concurrent subagents
176
166
 
177
- **Permission mode:** Omit the `mode` parameter when dispatching subagents so the user's configured permission settings apply. Do not pass `mode: "auto"` — it overrides user-level settings like `bypassPermissions`.
167
+ **Permission mode:** Dispatch subagents without a permission-mode override so the user's configured permission settings apply. The active harness profile names any harness-specific rule.
168
+
169
+ **Collecting results:** a subagent has completed only when its final report arrives; a launch handle is not a result. The active harness profile's *Dispatch results and continuation* section defines the final report and the continuation call. Record each subagent's id at dispatch, wait for its report without dispatching the same unit again, and continue a subagent through the profile-named call rather than starting a replacement.
178
170
 
179
171
  **After each subagent completes (serial mode):**
180
172
  1. Review the subagent's diff — verify changes match the unit's scope and `Files:` list
@@ -184,7 +176,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
184
176
  5. Dispatch the next unit
185
177
 
186
178
  **After all parallel subagents in a batch complete:**
187
- 1. Wait for every subagent in the current parallel batch to finish before acting on any of their results
179
+ 1. Wait for every subagent in the current parallel batch to deliver its final report before acting on any of their results
188
180
  2. Cross-check for discovered file collisions: compare the actual files modified by all subagents in the batch (not just their declared `Files:` lists). Subagents may create or modify files not anticipated during planning — this is expected, since plans describe *what* not *how*. A collision only matters when 2+ subagents in the same batch modified the same file. In a shared working directory, only the last writer's version survives — the other unit's changes to that file are lost. If a collision is detected: commit all non-colliding files from all units first, then re-run the affected units serially for the shared file so each builds on the other's committed work
189
181
  3. For each completed unit, in dependency order: review the diff, run the relevant test suite, stage only that unit's files, and commit with a conventional message derived from the unit's Goal
190
182
  4. If tests fail after committing a unit's changes, diagnose and fix before committing the next unit
@@ -280,7 +280,7 @@ If artifact-backed mode is not clearly warranted, stay in direct mode.
280
280
 
281
281
  ### Phase 4: Run Targeted Research and Review
282
282
 
283
- Launch the selected agents in parallel using the execution mode chosen in Step 3.3. If the current platform does not support parallel dispatch, run them sequentially instead.
283
+ Launch the selected agents in parallel using the execution mode chosen in Step 3.3. If the current platform does not support parallel dispatch, run them sequentially instead. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before synthesizing, and do not dispatch the same research again while one is owed.
284
284
 
285
285
  Prefer local repo and institutional evidence first. Use external research only when the gap cannot be closed responsibly from repo context or already-cited sources.
286
286
 
@@ -117,7 +117,7 @@ Add activated conditional personas:
117
117
 
118
118
  ### Dispatch
119
119
 
120
- Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex). Omit the `mode` parameter so the user's configured permission settings apply. Each agent receives the prompt built from the subagent template included below with these variables filled:
120
+ Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex). Dispatch without a permission-mode override so the user's configured permission settings apply. Each agent receives the prompt built from the subagent template included below with these variables filled:
121
121
 
122
122
  | Variable | Value |
123
123
  |----------|-------|
@@ -129,13 +129,13 @@ Dispatch all agents in **parallel** using the platform's task/agent tool (e.g.,
129
129
 
130
130
  Pass each agent the **full document** -- do not split into sections.
131
131
 
132
- **Error handling:** If an agent fails or times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
132
+ **Error handling:** An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section), and waiting for a report is not a failure: do not dispatch the same persona again while its report is owed. If an agent's final report says it failed or was cancelled, or it times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
133
133
 
134
134
  **Dispatch limit:** Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
135
135
 
136
136
  ## Phases 3-5: Synthesis, Presentation, and Next Action
137
137
 
138
- After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
138
+ After every dispatched agent's final report has arrived, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
139
139
 
140
140
  ---
141
141
 
@@ -29,18 +29,22 @@ Return: List the changed files and summarize the implementation.
29
29
  - **Return** — the result format expected from the specialist
30
30
 
31
31
  **Optional brief elements:**
32
- - **Session reference** — resume a prior specialist session instead of creating a new one, where the harness supports session reuse
32
+ - **Session reference** — continue a prior specialist session instead of creating a new one, through the continuation call the active harness profile names, using the id recorded at dispatch (see Dispatch Results and Continuation)
33
33
  - **Trigger context** — the command or workflow that initiated the dispatch
34
34
 
35
- A foreground dispatch blocks until the specialist returns its result. Use the active harness profile to determine whether foreground, background, or other dispatch modes are available. Run independent dispatches concurrently where the harness supports it; otherwise dispatch sequentially in dependency order.
35
+ Use the active harness profile to determine which dispatch modes are available and how a dispatch returns. Run independent dispatches concurrently where the harness supports it; otherwise dispatch sequentially in dependency order.
36
36
 
37
- ## Background Dispatch (When Available)
37
+ ## Dispatch Results and Continuation
38
38
 
39
- Background dispatch may be gated by a runtime capability or feature flag. Check the active harness profile and rely on whether the mechanism accepts background work.
39
+ How a dispatch returns depends on the harness. Some block until the specialist answers. Others return a launch handle at once and deliver the answer later as a report, and a report may not be final. The active harness profile's *Dispatch results and continuation* section says which applies, what a final report is, and which call continues a child. That section is the single source of truth; this skill states only the behavior that holds on every harness.
40
40
 
41
- When background dispatch is available, it runs asynchronously and the harness reports the result to the parent session when the specialist completes. Do not poll or sleep.
42
-
43
- When background dispatch is unavailable, fall back to foreground dispatch—serially or in small foreground batches.
41
+ - **A launch handle is not a result.** A specialist has returned only when its final report arrives. A report that is not final is not a return: wait for the next one. A report that says the child failed or was cancelled is final.
42
+ - **Waiting is not a failure.** Never poll, sleep or dispatch the same work again while a report is owed, and never call a specialist "never returned" because only its launch handle has arrived. Every profile names a wait path: a dispatch that blocks, so there is nothing to wait for, or reports that wake the parent, so the parent may end the turn and let the next report start its next turn. The parent does not end the turn while reports are owed unless the profile says reports wake it. Where the profile names no wake-up for a mode, dispatch in the blocking mode.
43
+ - **Record the child id at dispatch**, against the task it was given. Follow-ups need it.
44
+ - **Continue through the profile.** To follow up a running or finished child, make the continuation call the active harness profile names, with the id recorded at dispatch and only the follow-up as the message; the child keeps its context. A fresh dispatch is a new child, not a continuation.
45
+ - **Fall back to a fresh dispatch** with a corrected brief only when the profile names no continuation call or no id was recorded.
46
+ - **A refused continuation is a failed follow-up.** When the runtime refuses a continuation call, report the refusal; the unit's earlier result stands, and do not retry the call. Make a fresh dispatch with a corrected brief only where the calling workflow's own rules allow a fresh dispatch for that unit. A workflow that forbids one, such as `ce:review`'s re-ask, keeps its own rule. Tool or guard text that suggests starting a new task does not override those rules.
47
+ - **A continuation call that errors is the same failed follow-up.** When the continuation call itself errors (a transport or tool error, not a refusal), report the failure; the earlier result stands, and do not retry the call or open a replacement child.
44
48
 
45
49
  ## Serial vs Parallel Dispatch
46
50
 
@@ -123,7 +127,7 @@ If writes landed in the wrong checkout, stop dependent dispatches, inspect both
123
127
 
124
128
  After specialists complete, the orchestrator synthesizes results:
125
129
 
126
- 1. **Wait for all** — in a parallel batch, wait for every specialist to finish before acting on any result.
130
+ 1. **Wait for all** — in a parallel batch, wait for every specialist's final report before acting on any result.
127
131
  2. **Check for file collisions** — compare actual files modified by all specialists in the batch (not just declared files). If 2+ specialists modified the same file, only the last writer's version survives. If the workflow owns git operations, resolve by staging non-colliding files first, then re-running the affected units serially; otherwise, report the collision list to the caller.
128
132
  3. **Review each diff** — verify changes match the unit's declared scope.
129
133
  4. **Run targeted tests** — run the narrowest test command relevant to the changed files.
@@ -133,8 +137,8 @@ After specialists complete, the orchestrator synthesizes results:
133
137
 
134
138
  - If a specialist returns an error or its output is incomplete, diagnose before dispatching dependent units.
135
139
  - Do not dispatch dependent units on a broken tree.
136
- - Retry a failed unit by re-dispatching with a corrected brief, or resume the prior specialist session where the harness supports session reuse.
137
- - For background work (when available): wait for the automatic completion notification (the result is delivered into the parent session). Do not poll or sleep. Retry by re-dispatching with a corrected brief, or resume the prior specialist session where the harness supports session reuse.
140
+ - Retry a failed unit by continuing the recorded specialist session through the continuation call the active harness profile names. Re-dispatch with a corrected brief only when the profile names no continuation call or no id was recorded. A refused continuation follows the refused-continuation rule above.
141
+ - While a report is owed, wait for it (see Dispatch Results and Continuation). Do not poll or sleep.
138
142
 
139
143
  ## Quick Reference
140
144
 
@@ -143,9 +147,9 @@ After specialists complete, the orchestrator synthesizes results:
143
147
  | Units have dependencies | Serial foreground dispatch |
144
148
  | Units share files | Serial foreground dispatch |
145
149
  | Units are independent, no file overlap | Concurrent dispatch where supported; otherwise batched foreground dispatch |
146
- | Background available + long-running work | Concurrent background dispatch; results are pushed back to the parent on completion (no polling) |
147
- | Background unavailable | Foreground only — serial or batched |
148
- | Specialist fails | Diagnose, correct the brief, then re-dispatch or resume the prior session where supported |
150
+ | Long-running independent work | Concurrent dispatch where the profile supports it; each final report arrives on its own (no polling) |
151
+ | Concurrent dispatch unavailable | Serial or batched dispatch |
152
+ | Specialist fails | Diagnose, correct the brief, then continue the recorded session through the profile-named call; re-dispatch only when the profile names none or no id was recorded |
149
153
  | File collision detected post-parallel | Stage non-colliding files (if workflow owns git ops), re-run colliding units serially |
150
154
  | Write-capable dispatch | Include the expected root; require actual-root and changed-file attestation; independently verify both worktrees before acceptance |
151
155
 
@@ -153,8 +157,9 @@ After specialists complete, the orchestrator synthesizes results:
153
157
 
154
158
  | Mistake | Fix |
155
159
  |---|---|
156
- | Polling or sleeping to wait for background work | Background results are pushed into the parent session automatically; never poll or sleep |
160
+ | Polling, sleeping or re-dispatching while a report is owed | Wait for the final report; a launch handle is not a result and waiting is not a failure |
161
+ | Resuming through a guessed call or an unrecorded id | Record the child id at dispatch and continue through the call the active profile names |
157
162
  | Parallel specialists staging or committing | Instruct specialists not to stage/commit; the current workflow owner handles git ops when applicable, otherwise synthesize file inventory and results for the caller or user |
158
163
  | Dispatching dependent units without waiting | Always wait for prerequisites to complete and verify their output |
159
164
  | Ignoring file overlap in parallel batches | Run the Parallel Safety Check before every parallel dispatch |
160
- | Assuming background support without checking the active profile | Use background dispatch only when the active harness profile declares it available; otherwise dispatch in the foreground |
165
+ | Assuming a dispatch mode without checking the active profile | Use a dispatch mode only when the active harness profile declares it; otherwise dispatch serially |
@@ -195,11 +195,13 @@ Verdict meanings:
195
195
 
196
196
  **Sequential fallback**: Platforms that do not support parallel dispatch should run agents sequentially. Dispatch cluster units first (they are higher-leverage), then individual items.
197
197
 
198
+ **Collecting results**: an agent has completed only when its final report arrives; a launch handle is not a result. The active harness profile's *Dispatch results and continuation* section defines the final report. Wait for every report in a batch before the next batch or step 6, and never dispatch the same unit again while its report is owed.
199
+
198
200
  Fixes can occasionally expand beyond their referenced file (e.g., renaming a method updates callers elsewhere). This is rare but can cause parallel agents to collide. The verification step (step 8) catches this -- if re-fetching shows unresolved threads or if the commit reveals inconsistent changes, re-run the affected agents sequentially.
199
201
 
200
202
  ### 6. Commit and Push
201
203
 
202
- After all agents complete, check whether any files were actually changed. If all verdicts are `replied`, `not-addressing`, or `needs-human` (no code changes), skip this step entirely and proceed to step 7.
204
+ After every agent's final report has arrived, check whether any files were actually changed. If all verdicts are `replied`, `not-addressing`, or `needs-human` (no code changes), skip this step entirely and proceed to step 7.
203
205
 
204
206
  If there are file changes:
205
207
 
@@ -372,7 +374,7 @@ This fetches thread IDs and their first comment IDs (minimal fields, no bodies)
372
374
 
373
375
  ### 2. Fix, Reply, Resolve
374
376
 
375
- Spawn a single `systematic:workflow:pr-comment-resolver` agent for the thread. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 6-7.
377
+ Spawn a single `systematic:workflow:pr-comment-resolver` agent for the thread and wait for its final report. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 6-7.
376
378
 
377
379
  ---
378
380
 
@@ -22,10 +22,10 @@ Swarm-enabled LFG. Run these steps in order, parallelizing where indicated. Do n
22
22
 
23
23
  After work completes, launch steps 5 and 6 as **parallel swarm agents** (both only need code to be written):
24
24
 
25
- 5. `/ce:review mode:report-only` — spawn as background Task agent
26
- 6. `/systematic:test-browser` — spawn as background Task agent
25
+ 5. `/ce:review mode:report-only` — spawn as a parallel Task agent
26
+ 6. `/systematic:test-browser` — spawn as a parallel Task agent
27
27
 
28
- Wait for both to complete before continuing.
28
+ Wait for both final reports before continuing. A launch handle is not a report: do not re-dispatch while a report is owed (see the active harness profile's *Dispatch results and continuation* section).
29
29
 
30
30
  ## Autofix Phase
31
31
 
@@ -202,7 +202,7 @@ Create a task list grouped by type (e.g., `todowrite` in OpenCode, `update_plan`
202
202
 
203
203
  ### 3. Implement (PARALLEL)
204
204
 
205
- Spawn a `systematic:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order.
205
+ Spawn a `systematic:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order. An agent has returned only when its final report arrives (see the active harness profile's *Dispatch results and continuation* section): wait for every report before committing, and never dispatch the same item again while its report is owed.
206
206
 
207
207
  **Batching:** 1-4 items: direct parallel returns. 5+ items: batches of 4, each returning only a short status summary (todo handled, files changed, tests run/skipped, blockers).
208
208
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  | Capability | Mechanism | Status | Fallback |
4
4
  |---|---|---|---|
5
- | Subagent delegation | Name-based subagent dispatch; plugin agents ship in `agents/`; `context: fork` for skill-scoped forks | supported | Dispatch in the foreground, serially or in small batches |
5
+ | Subagent delegation | Name-based subagent dispatch; plugin agents ship in `agents/`; `context: fork` for skill-scoped forks; `SendMessage` continues a subagent by agent id | supported | Dispatch in the foreground, serially or in small batches |
6
6
  | Blocking user interaction | `AskUserQuestion` tool | supported | Present numbered options in chat and wait |
7
7
  | Task tracking | `TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` (`TodoWrite` is deprecated and disabled by default) | supported | Maintain a visible task list in responses |
8
8
  | Skill loading | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code | supported | Read the skill instructions listed by the active harness |
@@ -18,6 +18,14 @@ Behavioral enforcement on Claude Code rides a plugin output style (force-for-plu
18
18
  Use the systematic-implementer subagent to implement the auth module and return the changed files.
19
19
  ```
20
20
 
21
+ Omit the `mode` parameter when dispatching subagents so the user's configured permission settings apply. Do not pass `mode: "auto"`: it overrides user-level settings like `bypassPermissions`.
22
+
23
+ ### Dispatch results and continuation
24
+
25
+ Each subagent call starts a new instance, and the agent id comes with the dispatch result. Record it at dispatch, against the task it was given. Continue that subagent with `SendMessage` with `to` set to that agent id and the follow-up as the message: a finished subagent resumes in the background, and its reply arrives later as a report. The built-in Explore and Plan agents are one-shot and return no agent id, so they cannot be continued. Dispatching the same subagent by name again starts a new one, not a continuation.
26
+
27
+ **Wait path.** A subagent that Claude spawns from the main conversation starts in the background by default, and its report reaches the parent as a completion notification in a later turn, so the parent may end its turn. A `SendMessage` continuation resumes in the background the same way. In `claude -p` the run stays open for background subagents, up to a 10-minute idle cap, and drops work still unfinished then.
28
+
21
29
  ### Blocking user interaction
22
30
 
23
31
  ```typescript
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
4
4
 
5
5
  | Capability | Mechanism | Status | Fallback |
6
6
  |---|---|---|---|
7
- | Subagent delegation | `task()` tool; `subagent_type` selects a specialist, `task_id` resumes a session | supported; parallel and background dispatch may be available | Dispatch in the foreground, serially or in small batches |
7
+ | Subagent delegation | `task()` tool; `subagent_type` selects a specialist, `task_id` continues a running or finished child session | supported; parallel and background dispatch may be available | Dispatch in the foreground, serially or in small batches |
8
8
  | Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
9
9
  | Task tracking | `todowrite` | supported | Maintain a visible task list in responses |
10
10
  | Skill loading | `systematic_skill` for bundled skills; `skill` tool for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
@@ -29,7 +29,7 @@ task({
29
29
  background: true,
30
30
  })
31
31
 
32
- // Resume a prior specialist session:
32
+ // Continue a prior specialist session (see Dispatch results and continuation):
33
33
  task({ subagent_type: "systematic-implementer", task_id: "<prior-session-id>", description: "Resume the implementation task", prompt: "…" })
34
34
  ```
35
35
 
@@ -43,6 +43,12 @@ package actually ships, so they work for every reader. A host may provide
43
43
  additional agents through the user's own configuration; those are available at
44
44
  runtime but must not appear in bundled examples.
45
45
 
46
+ ### Dispatch results and continuation
47
+
48
+ A foreground `task` returns the child's answer in the call result, inside a `<task id="…" state="…">` block; the block's body is the child's answer. Record that `id` at dispatch, against the task it was given. To continue the same child, call `task` again with it as `task_id`, plus `subagent_type`, `description` and `prompt` (the follow-up only; the child keeps its context). A `background: true` dispatch returns the same block with `state="running"`, which is not final.
49
+
50
+ **Wait path.** A foreground `task` (the default) blocks until the child answers, so there is nothing to wait for. `background: true` works only with the host's experimental background-subagents flag, and the call fails without it; where it is on, the final result arrives as a synthetic `<task>` message that starts a new parent turn, so the parent may end its turn. Where the flag is off or unknown, dispatch in the foreground.
51
+
46
52
  ### Blocking user interaction
47
53
 
48
54
  ```typescript
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
4
4
 
5
5
  | Capability | Mechanism | Status | Fallback |
6
6
  |---|---|---|---|
7
- | Subagent delegation | `subagent` tool; `agent` selects a specialist, `sessionID` resumes a session, `background: true` runs it asynchronously | supported; foreground by default | Dispatch in the foreground, serially or in small batches |
7
+ | Subagent delegation | `subagent` tool; `agent` selects a specialist, `sessionID` continues a running or finished child; before 2.3.0, `background: true` runs it asynchronously | supported; from 2.3.0 every dispatch returns a handle and the answer arrives later as a `<subagent>` message; before that, foreground by default | Dispatch serially or in small batches |
8
8
  | Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
9
9
  | Task tracking | `todowrite` tool | conditional: only offered when the host's experimental `todo` option is on | Maintain a visible task list in responses |
10
10
  | Skill loading | `systematic_skill` for bundled skills, with arguments; `skill` tool (by `id`) for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
@@ -21,7 +21,7 @@ subagent({
21
21
  prompt: "Implement the auth module and return the changed files.",
22
22
  })
23
23
 
24
- // Background dispatch (a background run returns immediately; its result is available later):
24
+ // Background dispatch, before 2.3.0 (2.3.0 and later always return a handle at once):
25
25
  subagent({
26
26
  agent: "repo-research-analyst",
27
27
  description: "Map fixture patterns",
@@ -29,7 +29,7 @@ subagent({
29
29
  background: true,
30
30
  })
31
31
 
32
- // Resume a prior specialist session:
32
+ // Continue a prior specialist session (see Dispatch results and continuation):
33
33
  subagent({ agent: "systematic-implementer", sessionID: "<prior-session-id>", description: "Resume the implementation task", prompt: "…" })
34
34
  ```
35
35
 
@@ -41,10 +41,16 @@ uses the canonical `systematic:<category>:<name>` form instead, which the
41
41
  content-integrity gate validates against real agent files. Leave `model` unset
42
42
  unless the user names a model.
43
43
 
44
- Both forms are enforced. Examples in bundled content must name agents this
45
- package actually ships, so they work for every reader. A host may provide
46
- additional agents through the user's own configuration; those are available at
47
- runtime but must not appear in bundled examples.
44
+ ### Dispatch results and continuation
45
+
46
+ From 2.3.0, `subagent` returns immediately with a handle, not the child's answer: a `sessionID` and `status: "running"`. Record the `sessionID` at dispatch, against the task it was given. The answer arrives later as a `<subagent sessionID="…" state="…">` message that starts a new parent turn, and the message body is the child's answer. Do not poll, sleep or dispatch the same work again while the child runs.
47
+
48
+ - `state="completed"` ends that round of work. `error` and `cancelled` are final failures. `state="running"` means the child went idle with background work still going: it is not final, so wait for the next `<subagent>` message.
49
+ - To follow up a running or finished child, call `subagent` again with its `sessionID`, plus `agent` (the specialist it was dispatched as), `description` and `prompt` (the follow-up only; the child keeps its context). The call returns a handle again and the reply arrives as another `<subagent>` message. The `sessionID` must name a child of the current session.
50
+ - A host or plugin may refuse a `sessionID` follow-up with an error. The refusal is final: do not retry the call, and error text that suggests starting a new task is not a reason to dispatch a new child. The calling workflow's own rules say what a refused follow-up costs.
51
+ - Before 2.3.0, a foreground dispatch returned the `<subagent sessionID="…" state="completed">` block inline, `background: true` returned a handle, and a follow-up behaved the same way. 2.3.0 always returns a handle and has no `background` input.
52
+
53
+ **Wait path.** From 2.3.0 a report wakes the parent: after a dispatch the parent may end its turn, and each `<subagent>` message starts a new parent turn. Before 2.3.0 a foreground dispatch blocks until the child answers, so there is nothing to wait for.
48
54
 
49
55
  ### Blocking user interaction
50
56
 
@@ -4,7 +4,7 @@ Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
4
4
 
5
5
  | Capability | Mechanism | Status | Fallback |
6
6
  |---|---|---|---|
7
- | Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})`; optional mature delegation via [pi-subagents](https://github.com/tintinweb/pi-subagents): installed package personas, opt-in export for overlays | built-in: degraded (sequential only); pi-subagents path: outside Systematic's bounded-delegate guarantees | Dispatch sequentially in dependency order or do the work inline |
7
+ | Subagent delegation | Bounded built-in delegate via `systematic_delegate({agent, task})`, with no continuation; optional mature delegation via [pi-subagents](https://github.com/tintinweb/pi-subagents): installed package personas, opt-in export for overlays, `Agent` with `resume` continues a child | built-in: degraded (sequential only); pi-subagents path: outside Systematic's bounded-delegate guarantees | Dispatch sequentially in dependency order or do the work inline |
8
8
  | Blocking user interaction | No native blocking tool | degraded | Present numbered options in chat and wait |
9
9
  | Task tracking | No native task-tracking mechanism | unavailable | Maintain a visible task list in responses |
10
10
  | Skill loading | `systematic_skill` tool or Pi-native skill activation | supported | Read the skill instructions listed by the active harness |
@@ -25,14 +25,18 @@ systematic_delegate({
25
25
 
26
26
  `systematic_delegate` is sequential, capped at 20 turns, depth-1, and spawns its child with `noExtensions: true`. The `noExtensions` guarantee bounds `systematic_delegate`'s own recursion — it does not bound end-to-end delegation depth across a combined pi-subagents + Systematic path.
27
27
 
28
+ ### Dispatch results and continuation
29
+
30
+ `systematic_delegate` runs the child to completion, returns its answer in the call result and disposes the child's session, so `systematic_delegate` has no continuation. On the pi-subagents path, `Agent` returns an agent id at once; continue a child by calling `Agent` with `resume` set to that id and the follow-up as `prompt`.
31
+
32
+ **Wait path.** `systematic_delegate` is foreground: it blocks until the child answers, so there is nothing to wait for. A pi-subagents `Agent` call runs in the background by default, and its completion notification reaches an idle parent as a new turn, so the parent may end its turn; `run_in_background: false` blocks and returns the result inline instead. Both modes apply to `resume`.
33
+
28
34
  ### Optional: pi-subagents delegation
29
35
 
30
36
  [pi-subagents](https://github.com/tintinweb/pi-subagents) (parallel/multi-model delegation) 0.22 or newer loads 29 curated personas from the installed package as `systematic-<name>` agent types with plain defaults; a project-scope install only after the project is trusted, and its first session may omit them from the `Agent` description, though dispatch works. Any other type falls back to `general-purpose` with an "Unknown agent type" note: the persona did not run. Export is needed only to apply `systematic.json` overlays; a local file outranks the packaged one. Nothing is written at extension load.
31
37
 
32
38
  `disabled_agents` and `agents.<name>.disable` do not reach packaged personas. Turn one off with `/agents → Disable`, or all with `packageAgents: false` in `subagents.json`.
33
39
 
34
- The `Agent` tool runs in the background by default. Pass `run_in_background: false` to wait for the result.
35
-
36
40
  Tested against pi-subagents 0.22.0 on Pi 1.3.0. Versions outside the tested range are unsupported but nonfatal.
37
41
 
38
42
  Exact CLI form: `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global`. `--scope` is optional and defaults to `project`.