pi-subagents 0.21.1 → 0.21.3

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.21.3] - 2026-04-30
+
+### Fixed
+- Debounce foreground `needs_attention` notices, make them non-triggering, and cancel them when the run finishes so stale chain-step alerts do not launch parent turns after completion.
+
+## [0.21.2] - 2026-04-30
+
+### Added
+- Added a packaged `/parallel-context-build` prompt for parallel `context-builder` handoff passes.
+- Added a packaged `/parallel-handoff-plan` prompt for external-reference research plus local `context-builder` passes that produce an implementation handoff meta-prompt.
+
+### Changed
+- Strengthened `context-builder` guidance so handoffs require reading all relevant files and doing needed tool-available research before summarizing.
+- Expanded the bundled `pi-subagents` skill with tool-level recipes for the packaged prompt workflows, including context-build and handoff-plan patterns that parent agents can apply without slash commands.
+- Updated `README.md` to explain the bundled `pi-subagents` skill, what it covers, and how it helps the orchestrating agent.
+
+### Fixed
+- Make active-long-running notices time-based by default, with turn and token thresholds available only as explicit opt-in budget guards.
+- Stop async status listing from inventing `needs_attention` with default thresholds when the runner has not persisted a control state.
+- Treat string `"false"` output settings as disabled output so parallel reviewers do not collide on a `/false` output path, including chain-parallel agent defaults.
+- Wrap long `/subagents-status` detail output/event lines instead of truncating them with ellipses.
+- Treat cleanup after a clean terminal assistant stop as success even when the final assistant text is empty, using a short grace period before terminating lingering child processes without surfacing scary final-drain warnings.
+- Express flexible tool schema fields as `anyOf` unions without parent-level `type` arrays, avoiding schema shapes rejected by strict providers such as Moonshot/opencode-go.
+
 ## [0.21.1] - 2026-04-30
 
 ### Changed

package/README.md

@@ -1,5 +1,5 @@
 <p>
-  <img src="banner.png" alt="pi-subagents" width="1100">
+  <img src="https://raw.githubusercontent.com/nicobailon/pi-subagents/main/banner.png" alt="pi-subagents" width="1100">
 </p>
 
 # pi-subagents
@@ -196,6 +196,8 @@ The package includes reusable prompt templates for common workflows. You do not
 |--------|------------|
 | `/parallel-review` | Launch fresh-context reviewers with distinct angles, then synthesize what to fix. |
 | `/parallel-research` | Combine `researcher` and `scout` for external evidence, local code context, and practical tradeoffs. |
+| `/parallel-context-build` | Run `context-builder` agents in parallel to produce planning handoff context and meta-prompts. |
+| `/parallel-handoff-plan` | Combine external research and `context-builder` passes into an implementation handoff plan and meta-prompt. |
 | `/gather-context-and-clarify` | Scout/research first, then ask the user the clarification questions that matter. |
 | `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
 
@@ -618,6 +620,20 @@ Injected skills use this shape:
 
 Missing skills do not fail execution. The result summary shows a warning.
 
+### Bundled 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.
+
+What the bundled skill 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
+- **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, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup
+- **GPT-5.5 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, must not invent intercom targets, and must escalate unapproved decisions
+- **Intercom conventions**: when to ask vs send, and how parent-side result delivery works with `pi-intercom`
+- **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 directly; the README and prompt shortcuts encode the same workflows in user-facing form.
+
 ## Programmatic tool usage
 
 These are the parameters the LLM passes when it calls the `subagent` tool. Most users ask naturally or use slash commands instead.
@@ -719,7 +735,7 @@ Agent definitions are not loaded into context by default. Management actions let
 |-------|------|---------|-------------|
 | `agent` | string | - | Agent name for single mode, or target for management actions. |
 | `task` | string | - | Task string for single mode. |
-| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, `interrupt`, or `doctor`. |
+| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, `interrupt`, `resume`, or `doctor`. |
 | `chainName` | string | - | Chain name for management actions. |
 | `config` | object/string | - | Agent or chain config for create/update. |
 | `output` | `string \| false` | agent default | Override single-agent output file. |
@@ -751,9 +767,12 @@ Status and control actions:
 subagent({ action: "status" })
 subagent({ action: "status", id: "<run-id>" })
 subagent({ action: "interrupt", id: "<run-id>" })
+subagent({ action: "resume", id: "<async-run-id>", message: "follow-up question" })
 subagent({ action: "doctor" })
 ```
 
+`resume` sends the follow-up directly when the async child is still reachable over intercom. After completion, it starts a new async child from the stored single-child session file.
+
 ## Worktree isolation
 
 Parallel agents can clobber each other if they edit the same checkout. `worktree: true` gives each parallel child its own git worktree branched from `HEAD`.
@@ -971,7 +990,7 @@ Intercom delivery events:
 - `subagent:control-intercom`
 - `subagent:result-intercom`
 
-The result watcher emits `subagent:async-complete`; `index.ts` registers the notification handler that consumes it. Control/attention events are surfaced as visible parent notices and persisted for async runs. With `pi-intercom`, needs-attention notices and grouped parent-side subagent result deliveries can reach the orchestrator over intercom.
+The result watcher emits `subagent:async-complete`; `src/extension/index.ts` registers the notification handler that consumes it. Control/attention events are surfaced as visible parent notices and persisted for async runs. With `pi-intercom`, needs-attention notices and grouped parent-side subagent result deliveries can reach the orchestrator over intercom.
 
 ## Prompt-template integration
 
@@ -999,17 +1018,17 @@ The main runtime files are:
 
 | File | Purpose |
 |------|---------|
-| `index.ts` | Extension registration, tool registration, message/render wiring. |
-| `agents.ts` | Agent and chain discovery, frontmatter parsing. |
-| `subagent-executor.ts` | Main execution routing for single, parallel, chain, management, status, interrupt, and doctor actions. |
-| `execution.ts` | Core foreground `runSync` handling. |
-| `subagent-runner.ts` | Detached async runner. |
-| `async-execution.ts` | Background launch support. |
-| `async-status.ts` / `subagents-status.ts` | Status discovery and overlay UI. |
-| `chain-execution.ts` / `chain-serializer.ts` | Chain orchestration and `.chain.md` parsing. |
-| `agent-manager*.ts` | Agents Manager screens and editing flows. |
-| `settings.ts` | Chain behavior, instructions, and config helpers. |
-| `worktree.ts` | Git worktree isolation. |
-| `intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
-| `schemas.ts` / `types.ts` | Tool schemas, shared types, and event constants. |
+| `src/extension/index.ts` | Extension registration, tool registration, message/render wiring. |
+| `src/agents/agents.ts` | Agent and chain discovery, frontmatter parsing. |
+| `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, chain, management, status, interrupt, and doctor actions. |
+| `src/runs/foreground/execution.ts` | Core foreground `runSync` handling. |
+| `src/runs/background/subagent-runner.ts` | Detached async runner. |
+| `src/runs/background/async-execution.ts` | Background launch support. |
+| `src/runs/background/async-status.ts` / `src/tui/subagents-status.ts` | Status discovery and overlay UI. |
+| `src/runs/foreground/chain-execution.ts` / `src/agents/chain-serializer.ts` | Chain orchestration and `.chain.md` parsing. |
+| `src/manager-ui/agent-manager*.ts` | Agents Manager screens and editing flows. |
+| `src/shared/settings.ts` | Chain behavior, instructions, and config helpers. |
+| `src/runs/shared/worktree.ts` | Git worktree isolation. |
+| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
+| `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
 | `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |

package/agents/context-builder.md

@@ -12,14 +12,17 @@ output: context.md
 
 You are a requirements-to-context subagent.
 
-Analyze the user request against the codebase, gather the minimum high-value context, and produce structured handoff material for planning and GPT-5.5 subagent prompts.
+Analyze the user request against the codebase, gather the relevant high-value context, and produce structured handoff material for planning and GPT-5.5 subagent prompts. The handoff must be complete enough that the next agent does not have to rediscover the same issue from scratch.
 
 Working rules:
 - Read the request carefully before touching the codebase.
 - Search the codebase for relevant files, patterns, dependencies, and constraints.
-- Use `web_search` only when the task depends on external APIs, libraries, or current best practices.
+- Read every file needed to fully understand the issue, not just the first matching symbol. Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the problem, likely solution space, and validation path are clear.
+- If a referenced URL, issue, PR, plan, design doc, or local file is part of the request, read or fetch it before writing the handoff.
+- Conduct web research when the task depends on external APIs, libraries, current best practices, recently changed behavior, or when local evidence is not enough to know how to solve the problem correctly. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
+- Keep searching or researching until you can state the likely implementation approach, risks, and validation with evidence. If a gap remains, call it out explicitly instead of implying certainty.
 - Write the requested output files clearly and concretely.
-- Prefer distilled, high-signal context over exhaustive dumps.
+- Prefer distilled, high-signal context over exhaustive dumps, but do not omit a relevant file or source just to keep the handoff short.
 
 When running in a chain, expect to generate two files in the chain directory:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -26,8 +26,7 @@
     "pi-subagents": "install.mjs"
   },
   "files": [
-    "*.ts",
-    "!*.test.ts",
+    "src/**/*.ts",
     "*.mjs",
     "agents/",
     "skills/**/*",
@@ -43,7 +42,7 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./src/extension/index.ts"
     ],
     "skills": [
       "./skills"

package/prompts/parallel-context-build.md

@@ -0,0 +1,53 @@
+---
+description: Parallel context builders for planning handoff
+---
+
+Launch fresh-context `context-builder` subagents in parallel to build grounded handoff context for planning or implementation.
+
+Use the `subagent` tool in chain mode with a single parallel step, not top-level parallel tasks, so relative output files live under the temporary chain directory. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, for example:
+
+- `context-build/request-and-scope.md`
+- `context-build/codebase-and-patterns.md`
+- `context-build/validation-and-risks.md`
+
+Do not write these context artifacts into the repository unless I explicitly ask for persistent files.
+
+Treat the slash command arguments as the primary request, target, or focus:
+
+$@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform request, read or fetch that target before assigning builder angles, then pass the target explicitly into every `context-builder` task.
+
+Choose two or three strong builders based on the request. Prefer three only when the scope benefits from independent context slices. These are examples, not fixed defaults:
+
+1. Request and scope
+   Clarify the actual goal, user intent, constraints, non-goals, open questions, and decisions that affect the handoff.
+
+2. Codebase and patterns
+   Inspect relevant files, call paths, existing abstractions, tests, package constraints, and local conventions that the next agent must follow.
+
+3. Validation and risks
+   Identify likely failure modes, edge cases, test strategy, commands to run, dependency/API concerns, and escalation rules.
+
+Adapt the angles when the request calls for it:
+- Issue or PR URL: include issue requirements, acceptance criteria, linked discussion, and likely affected files.
+- Plan file: include plan consistency, missing context, implementation sequence, and validation readiness.
+- External API/library work: include current docs or primary sources through `web_search` when needed.
+- Large refactor: include module boundaries, dependency direction, migration/cutover risks, and testability.
+- UI/product work: include user flow, accessibility, copy, visual constraints, and implementation touchpoints.
+
+Ask each builder to produce a compact handoff file with:
+- relevant files and line ranges;
+- key snippets or patterns, not full dumps;
+- constraints and invariants;
+- risks and unknowns;
+- validation commands or next-best checks;
+- a `meta-prompt` section for the next planner or GPT-5.5 subagent.
+
+After the builders return, synthesize their outputs into:
+- the most important context the next agent needs;
+- the recommended meta-prompt to use next;
+- open questions or assumptions;
+- the output artifact paths.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/prompts/parallel-handoff-plan.md

@@ -0,0 +1,59 @@
+---
+description: Parallel research/context builders into an implementation handoff plan
+---
+
+Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final GPT-5.5-ready meta-prompt.
+
+Primary request, target, or focus:
+
+$@
+
+Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
+
+Use the `subagent` tool in chain mode:
+
+1. First step: a parallel group.
+   - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.
+   - `context-builder` for local codebase context.
+   - Add a second `context-builder` only when the scope is large enough to benefit from a separate implementation-strategy pass.
+
+2. Second step: a synthesis `context-builder` that reads the parallel findings and writes the final handoff plan and meta-prompt.
+
+Use distinct output paths under the chain directory. Example outputs:
+- `handoff/external-reference.md`
+- `handoff/local-context.md`
+- `handoff/implementation-strategy.md`
+- `handoff/final-handoff-plan.md`
+
+Do not write these artifacts into the repository unless I explicitly ask for persistent files.
+
+Role guidance:
+
+External reference researcher:
+- Study linked projects, docs, issues, examples, source code, or prompt guidance.
+- Identify the behavior, API, implementation files, constraints, and transferable ideas.
+- Conduct web research if needed. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
+- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
+
+Local context-builder:
+- Read all files needed to fully understand the local issue, not just the first match.
+- Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the local problem, solution space, and validation path are clear.
+- Return relevant file paths and line ranges, current architecture, constraints, tests, risks, and open questions.
+
+Implementation-strategy context-builder, when used:
+- Compare the external evidence against the local architecture.
+- Propose the safest implementation shape, files likely to change, edge cases, validation commands, and decisions that need approval.
+- Stay review/planning-only unless I explicitly ask for implementation.
+
+Final synthesis context-builder:
+- Read the parallel outputs and produce one concise handoff plan.
+- Include what the feature/change should do, what the external reference teaches, what the local codebase implies, the recommended approach, likely files to change, constraints, non-goals, validation, risks, and unresolved questions.
+- End with a compact GPT-5.5-ready meta-prompt for the next worker/planner.
+
+After the chain returns, synthesize the result for me with:
+- the recommended approach;
+- artifact paths;
+- the final meta-prompt;
+- any questions or assumptions that remain.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/prompts/parallel-review.md

@@ -37,4 +37,8 @@ While reviewers run, do your own narrow inspection if useful. After they return,
 
 Do not blindly apply every reviewer suggestion. Ask before applying fixes unless I already told you to address review feedback.
 
+Additional review target or focus from the slash command invocation:
+
 $@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.

package/skills/pi-subagents/SKILL.md

@@ -40,12 +40,73 @@ Humans often use the slash-command layer instead:
 Prefer the tool when you are writing agent logic. Prefer the slash commands when
 you are guiding a human through an interactive flow.
 
-Packaged prompt shortcuts are also available for repeatable workflows:
+Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)` and other tools:
 - `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
 - `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/parallel-context-build` — parallel `context-builder` passes that produce planning handoff context and meta-prompts
+- `/parallel-handoff-plan` — external-reference research plus local `context-builder` passes, followed by a synthesis handoff plan and GPT-5.5-ready meta-prompt
 - `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
 - `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
 
+## Applying Prompt Techniques Without Slash Commands
+
+The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
+
+### Parallel review technique
+
+Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
+
+### Parallel research technique
+
+Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
+
+### Parallel context-build technique
+
+Use this before planning or implementation when a stronger handoff is needed. Run a chain with one parallel step of `context-builder` agents rather than top-level parallel tasks, so relative output files live under the temporary chain directory. Give every task a distinct output path such as `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, and `context-build/validation-and-risks.md`. Choose two or three builders: request/scope, codebase/patterns, and validation/risks. Each builder must read every relevant file needed to understand its slice, follow imports/callers/tests/docs/config, conduct tool-available web research when needed, and include a compact `meta-prompt` section. The parent synthesizes the outputs into important context, recommended next meta-prompt, open questions, assumptions, and artifact paths.
+
+Example shape:
+
+```typescript
+subagent({
+  chain: [{
+    parallel: [
+      { agent: "context-builder", task: "Build request/scope context for: ...", output: "context-build/request-and-scope.md" },
+      { agent: "context-builder", task: "Build codebase/pattern context for: ...", output: "context-build/codebase-and-patterns.md" },
+      { agent: "context-builder", task: "Build validation/risk context for: ...", output: "context-build/validation-and-risks.md" }
+    ]
+  }],
+  context: "fresh"
+})
+```
+
+### Parallel handoff-plan technique
+
+Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context, such as “study this library behavior, inspect our codebase, then produce a GPT-5.5 worker prompt.” Run a chain with a first parallel group and a second synthesis `context-builder` step. The first group usually includes `researcher` for external projects/docs/prompt guidance and `context-builder` for local code context; add a second `context-builder` for implementation strategy only when the scope is large enough to benefit. Use distinct output paths under `handoff/`, then have the synthesis `context-builder` read those outputs and write `handoff/final-handoff-plan.md` with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact GPT-5.5-ready meta-prompt.
+
+Example shape:
+
+```typescript
+subagent({
+  chain: [
+    { parallel: [
+      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
+      { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
+      { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
+    ] },
+    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and GPT-5.5-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
+  ],
+  context: "fresh"
+})
+```
+
+### Gather-context-and-clarify technique
+
+Use this at the start of non-trivial work. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
+
+### Parallel cleanup technique
+
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+
 ## Builtin Agents
 
 Builtin agents load at the lowest priority. Project agents override user agents,
@@ -200,6 +261,8 @@ without forcing each step to rediscover everything.
 
 ### Async/background
 
+Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`. Do not end your turn immediately after launching that async child if you promised to keep working; continue the local inspection or other independent work, then check the async run when its result is needed.
+
 ```typescript
 subagent({
   agent: "worker",
@@ -208,6 +271,18 @@ subagent({
 })
 ```
 
+For review fanout where the parent continues a local audit:
+
+```typescript
+const run = subagent({
+  agent: "reviewer",
+  task: "Review the current diff for correctness issues. Do not edit files.",
+  async: true,
+  context: "fresh"
+})
+// Continue local inspection, then later call status with the returned id.
+```
+
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
 Use diagnostics when setup or child startup looks wrong:
@@ -440,9 +515,12 @@ copying a full builtin file.
 ## Prompt Template Integration
 
 The package includes prompt shortcuts for common workflows: `/parallel-review`,
-`/parallel-research`, `/gather-context-and-clarify`, and `/parallel-cleanup`.
-Use them when the user wants repeatable review, research, clarification, or
-cleanup-review patterns.
+`/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`,
+`/gather-context-and-clarify`, and `/parallel-cleanup`. Use them when the user
+wants repeatable review, research, context handoff, implementation handoff,
+clarification, or cleanup-review patterns. Parent agents can also apply the same
+recipes directly with `subagent(...)` when the user describes the workflow in
+natural language instead of invoking a slash command.
 
 If `pi-prompt-template-model` is installed, additional user prompt templates can delegate into
 `pi-subagents`. This is useful when a slash command should always run through a
@@ -522,6 +600,8 @@ When the user approves launching a subagent to carry out a plan or workflow, tre
 - `/gather-context-and-clarify` maps to: launch `scout` and, when needed, `researcher`; synthesize findings; then use `interview` to ask every clarification question needed for shared understanding.
 - `/parallel-review` maps to: launch fresh-context `reviewer` agents with distinct review angles; synthesize the feedback before applying anything.
 - `/parallel-research` maps to: combine local `scout` context with external `researcher` evidence when current docs, ecosystem behavior, or API details matter.
+- `/parallel-context-build` maps to: run a chain-mode parallel group of `context-builder` agents with distinct temp output paths, then synthesize their context and meta-prompt sections.
+- `/parallel-handoff-plan` maps to: run external `researcher` plus local/strategy `context-builder` passes, then a synthesis `context-builder` that writes an implementation handoff plan and GPT-5.5-ready meta-prompt.
 - `/parallel-cleanup` maps to: use review-only cleanup passes after implementation, especially for simplicity, verbosity, and redundant tests.
 
 For feature work, use this sequence as scaffolding for parent-agent behavior:

package/{agent-management.ts → src/agents/agent-management.ts}

@@ -16,7 +16,7 @@ import {
 import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain } from "./chain-serializer.ts";
 import { discoverAvailableSkills } from "./skills.ts";
-import type { Details } from "./types.ts";
+import type { Details } from "../shared/types.ts";
 
 type ManagementAction = "list" | "get" | "create" | "update" | "delete";
 type ManagementScope = "user" | "project";

package/{agents.ts → src/agents/agents.ts}

@@ -696,7 +696,7 @@ function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; pref
 		preferredDir,
 	};
 }
-const BUILTIN_AGENTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "agents");
+const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
 	const userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");

package/src/extension/control-notices.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent, SubagentState } from "../shared/types.ts";
+
+export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
+
+export interface SubagentControlMessageDetails {
+	event: ControlEvent;
+	source?: "foreground" | "async";
+	asyncDir?: string;
+	childIntercomTarget?: string;
+	noticeText?: string;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+function noticeTimerKey(details: SubagentControlMessageDetails): string {
+	const childIntercomTarget = controlNoticeTarget(details);
+	return `${details.event.runId}:${controlNotificationKey(details.event, childIntercomTarget)}`;
+}
+
+export function clearPendingForegroundControlNotices(state: SubagentState, runId?: string): void {
+	const pending = state.pendingForegroundControlNotices;
+	if (!pending) return;
+	for (const [key, timer] of pending) {
+		if (runId !== undefined && !key.startsWith(`${runId}:`)) continue;
+		clearTimeout(timer);
+		pending.delete(key);
+	}
+}
+
+function deliverControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	const childIntercomTarget = controlNoticeTarget(input.details);
+	const key = controlNotificationKey(input.details.event, childIntercomTarget);
+	if (input.visibleControlNotices.has(key)) return;
+	input.visibleControlNotices.add(key);
+	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
+	input.pi.sendMessage(
+		{
+			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+			content: noticeText,
+			display: true,
+			details: { ...input.details, childIntercomTarget, noticeText },
+		},
+		{ triggerTurn: input.details.source !== "foreground" },
+	);
+}
+
+function isForegroundNoticeStillActionable(state: SubagentState, details: SubagentControlMessageDetails): boolean {
+	const control = state.foregroundControls.get(details.event.runId);
+	if (!control) return false;
+	if (control.currentAgent && control.currentAgent !== details.event.agent) return false;
+	if (details.event.index !== undefined && control.currentIndex !== details.event.index) return false;
+	return control.currentActivityState === "needs_attention";
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	state: SubagentState;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+	foregroundDelayMs?: number;
+}): void {
+	if (!input.details?.event || input.details.event.type === "active_long_running") return;
+	if (input.details.source !== "foreground") {
+		deliverControlNotice(input);
+		return;
+	}
+
+	const pending = input.state.pendingForegroundControlNotices ?? new Map<string, ReturnType<typeof setTimeout>>();
+	input.state.pendingForegroundControlNotices = pending;
+	const timerKey = noticeTimerKey(input.details);
+	const existing = pending.get(timerKey);
+	if (existing) clearTimeout(existing);
+	const timer = setTimeout(() => {
+		pending.delete(timerKey);
+		if (!isForegroundNoticeStillActionable(input.state, input.details)) return;
+		deliverControlNotice(input);
+	}, input.foregroundDelayMs ?? 1000);
+	timer.unref?.();
+	pending.set(timerKey, timer);
+}

package/{doctor.ts → src/extension/doctor.ts}

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { discoverAgentsAll, type AgentSource } from "./agents.ts";
-import { isAsyncAvailable } from "./async-execution.ts";
-import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "./intercom-bridge.ts";
-import { discoverAvailableSkills, type SkillSource } from "./skills.ts";
+import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
+import { isAsyncAvailable } from "../runs/background/async-execution.ts";
+import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
+import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
 	ASYNC_DIR,
 	CHAIN_RUNS_DIR,
@@ -11,7 +11,7 @@ import {
 	TEMP_ROOT_DIR,
 	type ExtensionConfig,
 	type SubagentState,
-} from "./types.ts";
+} from "../shared/types.ts";
 
 interface DoctorPaths {
 	tempRootDir: string;