# Pi Subagents > Delegate work to builtin or custom subagents with single-agent, chain, parallel, async, forked-context, and intercom-coordinated workflows. Use for advisory review, implementation handoffs, and multi-step tasks where a single agent should stay in control while other agents contribute context, planning, or execution. - Skill: `joelhooks/pi-subagents` (Agent Skill) - Install (CLI): `npx skillmds@latest add joelhooks/pi-subagents` - Raw SKILL.md: https://api.skillmd.com/api/skills/joelhooks/pi-subagents/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: joelhooks (https://skillmd.com/u/joelhooks) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/joelhooks/pi-subagents --- # Pi Subagents This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches; child subagents should receive concrete role-specific tasks. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned. Use this skill when the parent orchestrator needs to launch a specialized subagent, compose multiple agents into a workflow, or create/edit agents and chains on demand. ## When to Use - **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter - **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction - **Recon and planning**: use `scout` or `context-builder`, then `planner` - **Parallel exploration**: run multiple non-conflicting tasks concurrently - **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task - **Long-running work**: launch async/background runs and inspect them later - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked - **Agent authoring**: create, update, or override agents and chains for a project ## Tool vs Slash Commands Agents can use the `subagent(...)` tool directly for execution, management, status, and control. Humans often use the slash-command layer instead: - `/run` — launch a single agent - `/chain` — launch a chain of steps - `/parallel` — launch top-level parallel tasks - `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow - `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state 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. 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 - `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped - `/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 implementation-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. ### Proactive skill-specialist technique Use this when `{ action: "list" }` reports proactive skill subagent suggestions and the user's task would benefit from perspectives the parent regularly uses. These suggestions are conservative: a skill is recommended only when it is available and referenced repeatedly by configured agents or saved chains. Treat the list as an opt-in hint for the current task, not a command to always fan out. Default guardrails: - Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap. - Prefer `context: "fresh"` and include only the files, diff, plan, URL, or request details each child needs. Use forked context only when private/session history is essential and appropriate to share. - Use read-only agents for analysis/review unless implementation was explicitly requested; do not create several writers in the same worktree. - Skip proactive skill subagents for tiny questions, direct commands, highly private requests, or when the user asks not to delegate. - Make cost and concurrency visible by using an ordinary `subagent(...)` call rather than hidden/background automation. Example shape: ```typescript subagent({ tasks: [ { agent: "reviewer", task: "Apply the available 'deslop' skill to review the current diff for concrete cleanup findings only. Do not modify files.", skill: "deslop" }, { agent: "reviewer", task: "Apply the available 'accessibility' skill to review the UI changes for concrete issues only. Do not modify files.", skill: "accessibility" } ], context: "fresh", concurrency: 2 }) ``` ### Review-loop technique Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless the user explicitly wants the foreground clarify UI. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome. ### 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 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 implementation-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 implementation-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` and `progress: 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. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized. ### Staged fix orchestration technique Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep the active worktree safe with a three-stage chain: 1. A parallel read-only planning fanout, one planner/reviewer per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit. 2. One writer worker. It receives the planner summaries through `{previous}`, the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree. 3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification. Prefer `async: true`, `context: "fresh"` for planners/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred. When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`. Example shape: ```typescript subagent({ async: true, context: "fresh", chain: [ { parallel: [ { agent: "reviewer", phase: "Planning", label: "Deploy docs", as: "deployPlan", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" }, { agent: "reviewer", phase: "Planning", label: "Scheduler contract", as: "schedulerPlan", task: "Plan fixes for scheduler contract. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/scheduler.md", outputMode: "file-only" }, { agent: "reviewer", phase: "Planning", label: "Sandbox/security", as: "sandboxPlan", task: "Plan fixes for sandbox/security. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/sandbox.md", outputMode: "file-only" } ], concurrency: 3 }, { agent: "worker", phase: "Implementation", label: "Apply accepted fixes", as: "workerResult", task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\n\nDeploy plan:\n{outputs.deployPlan}\n\nScheduler plan:\n{outputs.schedulerPlan}\n\nSandbox plan:\n{outputs.sandboxPlan}", output: "worker/fixes.md", outputMode: "file-only", progress: true }, { parallel: [ { agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" }, { agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" } ], concurrency: 2 } ] }) ``` ## Builtin Agents Builtin agents load at the lowest priority. Project agents override user agents, and user/project agents override builtins with the same name. | Agent | Purpose | Model | Typical output / role | |-------|---------|-------|------------------------| | `scout` | Fast codebase recon | inherits default | Writes `context.md` handoff material | | `planner` | Creates implementation plans | inherits default | Writes `plan.md` | | `worker` | Implementation and approved oracle handoffs | inherits default | Single-writer implementation with decision escalation | | `reviewer` | Review-and-fix specialist | inherits default | Can edit/fix reviewed code | | `context-builder` | Requirements/codebase handoff builder | inherits default | Writes structured context files | | `researcher` | Web research brief generator | inherits default | Writes `research.md` | | `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work | | `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination | Builtin agents inherit the current Pi default model unless a run, user setting, or project setting overrides `model`. Override builtin defaults before copying full agent files when a small tweak is enough. For one run, use inline config: ```text /run reviewer[model=anthropic/claude-sonnet-4] "Review this diff" ``` For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. ## Prompting role subagents Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path. A strong subagent prompt usually includes: - **Goal**: the concrete outcome the child should produce. - **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved. - **Success criteria**: what must be true before the child can finish. - **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is an explicitly assigned `tools: subagent` fanout child, or escalation for unapproved decisions. - **Validation**: targeted checks to run, or the next-best check when validation is impossible. - **Output**: the expected summary shape, artifact path, or finding format. - **Stop rules**: when to ask via `intercom`, when to stop after enough evidence, and when not to keep searching. Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop. For implementation handoffs, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation. Settings locations: - User scope: `~/.pi/agent/settings.json` - Project scope: `.pi/settings.json` Direct settings example: ```json { "subagents": { "agentOverrides": { "reviewer": { "model": "anthropic/claude-sonnet-4", "thinking": "high", "fallbackModels": ["openai/gpt-5-mini"] } } } } ``` Useful override fields: `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `disabled`, `skills`, `tools`, and `systemPrompt`. Create a user or project agent with the same name only when you want a substantially different agent. If a provider rejects model IDs with thinking suffixes, use `subagents.disableThinking: true` in user or project settings to clear bundled builtin thinking defaults globally. A higher-precedence per-agent `thinking` override can opt one builtin back in. ## Discovery and Scope Rules Agent files can live in: - `~/.pi/agent/agents/**/*.md` — user scope - `.pi/agents/**/*.md` — canonical project scope - legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts Chains live in: - `~/.pi/agent/chains/**/*.chain.md` and `~/.pi/agent/chains/**/*.chain.json` — user scope - `.pi/chains/**/*.chain.md` and `.pi/chains/**/*.chain.json` — project scope Discovery is recursive. `.chain.md` files do not define agents. Use `.chain.md` for simple saved chains and `.chain.json` for dynamic fanout or inline schema objects. Agents and chains can set optional frontmatter/package metadata; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate. Precedence is by parsed runtime name: 1. project scope 2. user scope 3. builtin agents ## Running Subagents ### Single agent ```typescript subagent({ agent: "oracle", task: "Review my current direction and challenge assumptions." }) ``` ### Forked context ```typescript subagent({ agent: "oracle", task: "Review my current direction and challenge assumptions." }) ``` `context: "fork"` creates a branched child session from the current persisted parent session. It does **not** create a fresh minimal review context or filter history down to only the relevant parts. Use it when you want a separate review or execution thread that can still reference the parent session history. ### Parallel execution ```typescript subagent({ tasks: [ { agent: "scout", task: "Explore the auth module" }, { agent: "reviewer", task: "Review the API client" } ] }) ``` Top-level parallel tasks can override per-task behavior: ```typescript subagent({ tasks: [ { agent: "scout", task: "Map auth", output: "auth-context.md", progress: true }, { agent: "researcher", task: "Research OAuth best practices", output: "oauth-research.md" }, { agent: "reviewer", task: "Review auth tests", model: "anthropic/claude-sonnet-4" } ], concurrency: 3 }) ``` Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file. For large saved outputs, set `outputMode: "file-only"` together with an `output` path. The parent result then contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` instead of the full saved content. Do not use `output: false` for this; `output: false` means no file output. When a task is review-only, say “do not modify project/source files” rather than “do not write files” if you also configured `output`; otherwise the child may treat the output artifact as forbidden. Failed runs and save errors still return inline details for debugging. ### Chain execution ```typescript subagent({ chain: [ { agent: "scout", task: "Map the auth flow and summarize key files" }, { agent: "planner", task: "Create an implementation plan from {previous}" }, { agent: "worker", task: "Implement the approved plan based on {previous}" } ] }) ``` Chain steps can use templated variables such as `{task}`, `{previous}`, `{chain_dir}`, and `{outputs.name}`. Use `as: "name"` on a successful step or parallel task to make that output available to later steps. Prefer named outputs when a later step needs one specific result; keep `{previous}` for simple linear handoffs or full fan-in summaries. Use `phase` and `label` for status readability. Use `outputSchema` when later steps need reliable structured data; the child must call `structured_output` with schema-valid JSON, or the step fails. ### Async/background Prefer async mode for every subagent launch. Set `async: true` no matter the task unless there is a specific reason to opt into a foreground/blocking run. This applies to scouts, researchers, workers, reviewers, validators, oracle checks, one-off delegates, chains, and parallel groups. Keep the write path single-threaded even when the run is async. Async does not mean parallel writes. Do not edit the same active worktree while an async worker is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree. Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed. If there is no independent work left and you would only be running `sleep` or status polling commands to wait, end your turn instead. Pi will deliver the async completion when it arrives. ```typescript subagent({ agent: "worker", task: "Run the full test suite", async: true }) ``` File-only output mode also works for async single runs, top-level parallel task items, sequential chain steps, and chain parallel task items. In chains, `{previous}` receives the compact saved-file reference when the prior step used file-only mode. 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: "..." })` or `subagent({ action: "status" })` for active runs. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id. Use `resume` for follow-up work after a delegated run: ```typescript subagent({ action: "resume", id: "run-id", message: "Follow up on this point." }) subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." }) subagent({ action: "resume", id: "nested-run-id", message: "Continue this nested reviewer." }) ``` Resume behavior: - If an async child is still running and reachable, `resume` sends the follow-up to that live child over intercom. - If an async child has completed, `resume` revives it by starting a new async child from the persisted child session file. - Multi-child async runs require `index` unless only one running child is selectable. - Completed foreground single, parallel, and chain runs can also be revived by `index` while their run metadata remains in extension state. - Nested runs can be resumed by nested id when a live route or persisted nested session metadata is available. - Revive starts a new child process from the old session context; it does not restart the same OS process. - If the chosen child has no persisted `.jsonl` session file, resume fails and reports that directly. Use diagnostics when setup or child startup looks wrong: ```typescript subagent({ action: "doctor" }) ``` Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state. ### Subagent control Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state. Use soft interrupt when a child is clearly blocked or drifting and the parent needs to regain control: ```typescript subagent({ action: "interrupt" }) ``` Pass `id` when targeting a specific controllable run, including a nested run shown in the parent status tree: ```typescript subagent({ action: "interrupt", id: "abc123" }) subagent({ action: "interrupt", id: "nested-run-id" }) ``` A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the delegated task succeeded or failed. Bare `interrupt` does not target hidden nested descendants; use the explicit nested id. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow. Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual: ```typescript subagent({ agent: "worker", task: "Run the slow migration test suite", control: { needsAttentionAfterMs: 300000, notifyOn: ["needs_attention"] } }) ``` If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists. ## Clarify TUI Single and parallel runs support a clarification TUI when you want to preview or edit parameters before launch: ```typescript subagent({ agent: "worker", task: "Implement feature X", clarify: true }) ``` Chains default to clarify mode; set `clarify: false` to skip it. Clarify edits affect only the next run; use management actions, settings, or markdown files for persistent changes. For programmatic background launches, use `async: true`. Set `clarify: false` when you want to bypass chain clarification explicitly; `clarify: true` keeps the run foreground for the clarify UI. ## Worktree Isolation When multiple agents might write concurrently, use worktrees instead of letting them share one filesystem view. ```typescript subagent({ tasks: [ { agent: "worker", task: "Implement feature A" }, { agent: "worker", task: "Implement feature B" } ], worktree: true }) ``` `worktree: true` gives each parallel task its own git worktree branched from HEAD. This requires a clean git state and is mainly for intentionally parallel write workflows. If you want one writer thread and several advisory agents, prefer a single-writer pattern instead. ## The Oracle Workflow The intended oracle loop is: 1. the main agent forks to `oracle` 2. `oracle` reviews direction, drift, assumptions, and risks 3. `oracle` can coordinate back through `contact_supervisor` when the bridge injects it 4. the main agent decides what direction to approve 5. only then should `worker` implement ```typescript // Advisory review in a branched thread. Oracle defaults to forked context. subagent({ agent: "oracle", task: "Review my current direction, challenge assumptions, and propose the best next move." }) // Implementation only after explicit approval. Worker defaults to forked context. subagent({ agent: "worker", task: "Implement the approved approach: ..." }) ``` `oracle` is not a fresh-context reviewer in the Cognition article sense. It is a forked advisory thread that inherits the parent session history and uses that history as a baseline contract. Use `oracle` as a smart-friend escalation when the parent needs help with trajectory rather than diff inspection: architectural boundaries, model capability routing, merge conflicts, reviewer disagreement, context drift after long work, a worker about to invent a pattern, or fixes that require product/scope tradeoffs. Ask broad questions when the right concern is unclear, and let `oracle` point out missing context or files the parent should inspect before asking again. Keep `oracle` advisory unless it has been explicitly assigned the single writer role. ## Subagent + Intercom Coordination `pi-subagents` works without `pi-intercom`. When `pi-intercom` is installed and enabled, the intercom bridge can automatically give child agents a private coordination channel back to the parent session. Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target. Prefer the tool from the injected bridge instructions. Use `contact_supervisor` with `reason: "need_decision"` when: - a subagent is blocked on a decision - a child needs clarification instead of guessing - an approval, product, API, or scope choice is required before continuing safely Do not use `contact_supervisor` just to resolve review-only/no-project-edit versus progress-writing or output-artifact instructions. The child must not modify project/source files, but returning findings through its normal response or configured output artifact is allowed unless the parent explicitly set `output: false`. Use `contact_supervisor` with `reason: "progress_update"` when: - a child is explicitly asked for progress - a meaningful discovery changes the plan - a long-running child needs to report a blocked/progress checkpoint without waiting for normal tool return flow Message conventions: - `reason: "need_decision"` waits for the parent reply and returns it to the child. - `reason: "progress_update"` is non-blocking and should stay concise. - Child-side routine completion handoffs are not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets, full child summaries, and compact nested summaries under the parent child that launched them. If bridge instructions provide the child-facing tool, a child can ask: ```typescript contact_supervisor({ reason: "need_decision", message: "Should I optimize for readability or performance here?" }) ``` The parent replies with: ```typescript intercom({ action: "reply", message: "Optimize for readability." }) ``` Or inspects unresolved asks first: ```typescript intercom({ action: "pending" }) ``` If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`. ## Management Mode The `subagent(...)` tool also supports management actions. ### List available agents and chains ```typescript subagent({ action: "list" }) ``` ### Create an agent ```typescript subagent({ action: "create", config: { name: "my-agent", package: "code-analysis", description: "Project-specific implementation helper", systemPrompt: "Your system prompt here.", systemPromptMode: "replace", model: "openai-codex/gpt-5.4", tools: "read,grep,find,ls,bash" } }) ``` ### Update an agent ```typescript subagent({ action: "update", agent: "code-analysis.my-agent", config: { thinking: "high" } }) ``` ### Delete an agent ```typescript subagent({ action: "delete", agent: "code-analysis.my-agent" }) ``` Use management actions when the system needs to create or edit subagents on demand without dropping into raw file editing. Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and chain steps. For small builtin changes such as a model swap, prefer `subagents.agentOverrides` in settings. ## Creating and Editing Agents by File A minimal agent file looks like this: ```markdown --- name: my-agent package: code-analysis description: What this agent does model: openai-codex/gpt-5.4 thinking: high tools: read, grep, find, ls, bash systemPromptMode: replace inheritProjectContext: true inheritSkills: false --- Your system prompt here. ``` That is only a starting point. Omit `package` for the traditional unqualified runtime name. Common optional fields include: - `defaultProgress` - `defaultReads` - `output` - `fallbackModels` - `maxSubagentDepth` For many customizations, builtin overrides in settings are lower-friction than copying a full builtin file. ## Prompt Template Integration The package includes prompt shortcuts for common workflows: `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`, `/gather-context-and-clarify`, and `/parallel-cleanup`. Use them when the user wants repeatable review, review/fix loops, research, context handoff, implementation handoff, clarification, or cleanup-review patterns. `/parallel-review autofix` and `/parallel-cleanup autofix` synthesize reviewer feedback and then apply only the fixes worth doing now. 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 particular agent or with forked context. ## Important Constraints - **Forking requires a persisted parent session.** If the current session does not have a persisted session file, forked runs fail. Packaged `planner`, `worker`, and `oracle` default to forked context, so use `context: "fresh"` explicitly when that is not available or not wanted. - **Forked runs inherit parent history.** They are branched threads, not fresh filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context. - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked unless configured otherwise. - **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`. - **Intercom asks are blocking.** A session can only maintain one pending outbound ask wait state at a time. - **Keep conversational authority clear.** Advisory subagents should not silently become second decision-makers. ## Best Practices ### Prefer async orchestration Launch ever …(truncated)