pi-subagents 0.19.0 → 0.19.2

package/skills/pi-subagents/SKILL.md

@@ -15,8 +15,8 @@ agents into a workflow, or create/edit agents and chains on demand.
 
 ## When to Use
 
-- **Advisory review**: fork to `oracle` or `reviewer` for a branched review thread
-- **Implementation handoff**: have `oracle` advise, then `oracle-executor` or `worker` implement
+- **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 `oracle-executor` or `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
 - **Long-running work**: launch async/background runs and inspect them later
@@ -32,11 +32,19 @@ Humans often use the slash-command layer instead:
 - `/chain` — launch a chain of steps
 - `/parallel` — launch top-level parallel tasks
 - `/agents` — open the agents manager TUI
+- `/run-chain` — launch a saved `.chain.md` workflow
 - `/subagents-status` — inspect active/recent async runs
+- `/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:
+- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
+- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
+- `/oracle-executor` — send an explicitly approved implementation task to `oracle-executor`
+
 ## Builtin Agents
 
 Builtin agents load at the lowest priority. Project agents override user agents,
@@ -54,16 +62,40 @@ and user/project agents override builtins with the same name.
 | `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.5` | Advisory review, intercom coordination |
 | `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.5` | Single-writer implementation after approval |
 
-Override builtin defaults via settings before copying full agent files when a
-small tweak is enough.
+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, prefer `/agents`: choose the builtin, press `e`, change the model or other fields, then save a user or project override. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
 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`, `disabled`,
-`skills`, `tools`, and `systemPrompt`.
+`skills`, `tools`, and `systemPrompt`. Create a user or project agent with the
+same name only when you want a substantially different agent.
 
 ## Discovery and Scope Rules
 
@@ -119,6 +151,21 @@ subagent({
 })
 ```
 
+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.
+
 ### Chain execution
 
 ```typescript
@@ -147,6 +194,14 @@ subagent({
 
 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:
+
+```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.
@@ -198,6 +253,8 @@ subagent({
 Chains default to clarify mode unless you explicitly set `clarify: false`.
 For programmatic background launches, use `clarify: false, async: true`.
 
+The `/agents` manager also has launch toggles for forked context, background execution, and worktree-isolated parallel runs. Use it when guiding a human who wants to inspect or edit the launch before starting.
+
 ## Worktree Isolation
 
 When multiple agents might write concurrently, use worktrees instead of letting
@@ -249,35 +306,44 @@ history as a baseline contract.
 
 ## Subagent + Intercom Coordination
 
-When `pi-intercom` is installed and enabled, delegated runs can coordinate with
-the orchestrator through the intercom bridge.
+`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.
 
-### Subagent asks the orchestrator
+Most agents should not call `intercom` directly unless bridge instructions provide a target. Do not invent a target. Use the target from the injected bridge instructions or from a visible needs-attention notice.
+
+Use `intercom` when:
+- a subagent is blocked on a decision
+- a child needs clarification instead of guessing
+- a detached or async child needs to coordinate without waiting for normal tool return flow
+- an advisory agent was explicitly asked to send a concise progress update
+
+Message conventions:
+- `ask` means the child needs a decision or clarification from the parent session.
+- `send` means a short blocked/progress update, only when blocked or explicitly asked.
+- Routine completion does not go through intercom. The normal subagent result still returns through `pi-subagents`.
+
+If a bridge target is available, a child can ask:
 
 ```typescript
 intercom({
   action: "ask",
-  to: "orchestrator",
+  to: "<bridge-provided-target>",
   message: "Should I optimize for readability or performance here?"
 })
 ```
 
-### Orchestrator replies
+The parent replies with:
 
 ```typescript
 intercom({ action: "reply", message: "Optimize for readability." })
 ```
 
-Or inspect unresolved asks first:
+Or inspects unresolved asks first:
 
 ```typescript
 intercom({ action: "pending" })
 ```
 
-Use `intercom` when:
-- a subagent is blocked on a decision
-- an advisory agent wants to send a concise handoff mid-flight
-- a detached or async child needs to coordinate without waiting for normal tool return flow
+If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
 
 ## Management Mode
 
@@ -326,6 +392,8 @@ subagent({ action: "delete", agent: "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. For small builtin changes such as a model swap, prefer `/agents` builtin overrides or `subagents.agentOverrides` in settings.
+
 ## Creating and Editing Agents by File
 
 A minimal agent file looks like this:
@@ -357,7 +425,12 @@ copying a full builtin file.
 
 ## Prompt Template Integration
 
-If `pi-prompt-template-model` is installed, prompt templates can delegate into
+The package includes prompt shortcuts for common workflows: `/parallel-review`,
+`/parallel-research`, `/gather-context-and-clarify`, and `/oracle-executor`.
+Use them when the user wants repeatable review, research, clarification, or
+approved execution patterns.
+
+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.
 
@@ -366,7 +439,7 @@ particular agent or with forked context.
 - **Forking requires a persisted parent session.** If the current session does not
   have a persisted session file, forked runs fail.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
-  filtered contexts.
+  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`.
@@ -386,7 +459,10 @@ for the actual write path.
 ### Use fork for branched advisory or execution threads
 
 Forked runs are useful when the child should reason in a separate thread while
-still inheriting the parent’s accumulated context.
+still inheriting the parent’s accumulated context. They are especially useful for
+`oracle`, which audits inherited decisions and drift. For adversarial code review,
+prefer fresh-context reviewers that inspect the repo and diff directly unless the
+user explicitly requests forked context.
 
 ### Prefer narrow tasks
 
@@ -426,8 +502,7 @@ subagent({
 subagent({ agent: "worker", task: "Add retry logic to the API client." })
 subagent({
   agent: "reviewer",
-  task: "Review the retry logic implementation. Look for edge cases and race conditions.",
-  context: "fork"
+  task: "Review the retry logic implementation. Inspect the repo and current diff directly. Look for edge cases and race conditions."
 })
 ```
 
@@ -442,6 +517,14 @@ subagent({
 })
 ```
 
+### Saved chain
+
+```text
+/run-chain review-chain -- review this branch
+```
+
+Use saved `.chain.md` workflows when the user wants a repeatable multi-agent flow without rewriting the chain each time.
+
 ## Error Handling
 
 **"Unknown agent"**
@@ -450,6 +533,12 @@ subagent({ action: "list" })
 // Check available agents and chains, then confirm scope/precedence.
 ```
 
+**Setup, discovery, or intercom confusion**
+```typescript
+subagent({ action: "doctor" })
+// Check runtime paths, async support, discovery counts, current session, and intercom bridge state.
+```
+
 **"Max subagent depth exceeded"**
 ```typescript
 // Flatten the workflow or raise maxSubagentDepth in config.
@@ -464,3 +553,18 @@ subagent({ action: "list" })
 ```typescript
 // Resolve the current outbound ask before starting another one.
 ```
+
+**Parallel output-path conflict**
+```typescript
+// Give each parallel task a distinct output path, or disable output for tasks that do not need it.
+```
+
+**Worktree launch fails**
+```typescript
+// Ensure the git working tree is clean and task cwd overrides match the shared cwd.
+```
+
+**Child fails before starting**
+```typescript
+// Inspect /subagents-status detail, artifact metadata/output logs, and run doctor. Extension loader errors usually appear in child output logs.
+```

package/slash-commands.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey } from "@mariozechner/pi-tui";
-import { discoverAgents, discoverAgentsAll } from "./agents.ts";
+import { discoverAgents, discoverAgentsAll, type ChainConfig } from "./agents.ts";
 import { AgentManagerComponent, type ManagerResult } from "./agent-manager.ts";
 import { SubagentsStatusComponent } from "./subagents-status.ts";
 import { discoverAvailableSkills } from "./skills.ts";
@@ -108,6 +108,36 @@ const makeAgentCompletions = (state: SubagentState, multiAgent: boolean) => (pre
 	return agents.filter((a) => a.name.startsWith(lastWord)).map((a) => ({ value: `${beforeLastWord}${a.name}`, label: a.name }));
 };
 
+const discoverSavedChains = (cwd: string): ChainConfig[] => {
+	const chainsByName = new Map<string, ChainConfig>();
+	for (const chain of discoverAgentsAll(cwd).chains) {
+		chainsByName.set(chain.name, chain);
+	}
+	return Array.from(chainsByName.values());
+};
+
+const makeChainCompletions = (state: SubagentState) => (prefix: string) => {
+	if (prefix.includes(" ")) return null;
+	return discoverSavedChains(state.baseCwd)
+		.filter((chain) => chain.name.startsWith(prefix))
+		.map((chain) => ({ value: chain.name, label: chain.name }));
+};
+
+const mapSavedChainSteps = (chain: ChainConfig, worktree = false): ChainStep[] => {
+	return (chain.steps as Array<ChainStep & { skills?: string[] | false }>).map((step) => {
+		if (isParallelStep(step)) return worktree ? { ...step, worktree: true } : { ...step };
+		return {
+			agent: step.agent,
+			task: step.task || undefined,
+			output: step.output,
+			reads: step.reads,
+			progress: step.progress,
+			skill: step.skill ?? step.skills,
+			model: step.model,
+		};
+	});
+};
+
 async function requestSlashRun(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -328,19 +358,7 @@ async function openAgentManager(
 	if (result.action === "launch") {
 		await runSlashSubagent(pi, ctx, { agent: result.agent, task: result.task, ...launchOptions });
 	} else if (result.action === "launch-chain") {
-		const chainParam = (result.chain.steps as unknown as ChainStep[]).map((step) => {
-			if (isParallelStep(step)) return result.worktree ? { ...step, worktree: true } : { ...step };
-			return {
-				agent: step.agent,
-				task: step.task || undefined,
-				output: step.output,
-				reads: step.reads,
-				progress: step.progress,
-				skill: step.skill ?? (step as typeof step & { skills?: string[] | false }).skills,
-				model: step.model,
-			};
-		});
-		await runSlashSubagent(pi, ctx, { chain: chainParam, task: result.task, ...launchOptions });
+		await runSlashSubagent(pi, ctx, { chain: mapSavedChainSteps(result.chain, result.worktree), task: result.task, ...launchOptions });
 	} else if (result.action === "parallel") {
 		await runSlashSubagent(pi, ctx, {
 			tasks: result.tasks,
@@ -489,24 +507,53 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("run-chain", {
+		description: "Run a saved chain: /run-chain chainName -- task [--bg] [--fork]",
+		getArgumentCompletions: makeChainCompletions(state),
+		handler: async (args, ctx) => {
+			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
+			const delimiterIndex = cleanedArgs.indexOf(" -- ");
+			const usage = "Usage: /run-chain <chainName> -- <task> [--bg] [--fork]";
+			if (delimiterIndex === -1) {
+				ctx.ui.notify(usage, "error");
+				return;
+			}
+			const chainName = cleanedArgs.slice(0, delimiterIndex).trim();
+			const task = cleanedArgs.slice(delimiterIndex + 4).trim();
+			if (!chainName || !task) {
+				ctx.ui.notify(usage, "error");
+				return;
+			}
+			const chain = discoverSavedChains(state.baseCwd).find((candidate) => candidate.name === chainName);
+			if (!chain) {
+				ctx.ui.notify(`Unknown chain: ${chainName}`, "error");
+				return;
+			}
+			const params: SubagentParamsLike = { chain: mapSavedChainSteps(chain), task, clarify: false, agentScope: "both" };
+			if (bg) params.async = true;
+			if (fork) params.context = "fork";
+			await runSlashSubagent(pi, ctx, params);
+		},
+	});
+
 	pi.registerCommand("parallel", {
 		description: "Run agents in parallel: /parallel scout \"task1\" -> reviewer \"task2\" [--bg] [--fork]",
 		getArgumentCompletions: makeAgentCompletions(state, true),
-			handler: async (args, ctx) => {
-				const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
-				const parsed = parseAgentArgs(state, cleanedArgs, "parallel", ctx);
-				if (!parsed) return;
-				const tasks = parsed.steps.map(({ name, config, task: stepTask }) => ({
-					agent: name,
-					task: stepTask ?? parsed.task,
-					...(config.output !== undefined ? { output: config.output } : {}),
-					...(config.reads !== undefined ? { reads: config.reads } : {}),
-					...(config.model ? { model: config.model } : {}),
-					...(config.skill !== undefined ? { skill: config.skill } : {}),
-					...(config.progress !== undefined ? { progress: config.progress } : {}),
-				}));
-				const params: SubagentParamsLike = { tasks, clarify: false, agentScope: "both" };
-				if (bg) params.async = true;
+		handler: async (args, ctx) => {
+			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
+			const parsed = parseAgentArgs(state, cleanedArgs, "parallel", ctx);
+			if (!parsed) return;
+			const tasks = parsed.steps.map(({ name, config, task: stepTask }) => ({
+				agent: name,
+				task: stepTask ?? parsed.task,
+				...(config.output !== undefined ? { output: config.output } : {}),
+				...(config.reads !== undefined ? { reads: config.reads } : {}),
+				...(config.model ? { model: config.model } : {}),
+				...(config.skill !== undefined ? { skill: config.skill } : {}),
+				...(config.progress !== undefined ? { progress: config.progress } : {}),
+			}));
+			const params: SubagentParamsLike = { tasks, clarify: false, agentScope: "both" };
+			if (bg) params.async = true;
 			if (fork) params.context = "fork";
 			await runSlashSubagent(pi, ctx, params);
 		},
@@ -522,6 +569,13 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("subagents-doctor", {
+		description: "Show subagent diagnostics",
+		handler: async (_args, ctx) => {
+			await runSlashSubagent(pi, ctx, { action: "doctor" });
+		},
+	});
+
 	pi.registerShortcut("ctrl+shift+a", {
 		handler: async (ctx) => {
 			await openAgentManager(pi, ctx);

package/slash-live-state.ts

@@ -1,8 +1,8 @@
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { Message } from "@mariozechner/pi-ai";
-import type { SubagentParamsLike } from "./subagent-executor.js";
-import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.js";
-import { type Details, type SingleResult, type Usage, SLASH_RESULT_TYPE } from "./types.js";
+import type { SubagentParamsLike } from "./subagent-executor.ts";
+import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
+import { type Details, type SingleResult, type Usage, SLASH_RESULT_TYPE } from "./types.ts";
 
 export interface SlashMessageDetails {
 	requestId: string;

package/subagent-executor.ts

@@ -9,6 +9,7 @@ import { ChainClarifyComponent, type ChainClarifyResult, type ModelInfo } from "
 import { executeChain } from "./chain-execution.ts";
 import { resolveExecutionAgentScope } from "./agent-scope.ts";
 import { handleManagementAction } from "./agent-management.ts";
+import { buildDoctorReport } from "./doctor.ts";
 import { runSync } from "./execution.ts";
 import { resolveModelCandidate } from "./model-fallback.ts";
 import { aggregateParallelOutputs } from "./parallel-utils.ts";
@@ -1544,6 +1545,39 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const requestCwd = resolveRequestedCwd(ctx.cwd, params.cwd);
 		const paramsWithResolvedCwd = params.cwd === undefined ? params : { ...params, cwd: requestCwd };
 		if (params.action) {
+			if (params.action === "doctor") {
+				let currentSessionFile: string | null = null;
+				let currentSessionId = deps.state.currentSessionId;
+				let sessionError: string | undefined;
+				try {
+					currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+					currentSessionId = ctx.sessionManager.getSessionId();
+				} catch (error) {
+					sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+				}
+				let orchestratorTarget: string | undefined;
+				try {
+					orchestratorTarget = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
+				} catch {}
+				return {
+					content: [{
+						type: "text",
+						text: buildDoctorReport({
+							cwd: requestCwd,
+							config: deps.config,
+							state: deps.state,
+							context: paramsWithResolvedCwd.context,
+							requestedSessionDir: paramsWithResolvedCwd.sessionDir,
+							currentSessionFile,
+							currentSessionId,
+							orchestratorTarget,
+							sessionError,
+							expandTilde: deps.expandTilde,
+						}),
+					}],
+					details: { mode: "management", results: [] },
+				};
+			}
 			if (params.action === "status") {
 				const foreground = getForegroundControl(deps.state, paramsWithResolvedCwd.id ?? paramsWithResolvedCwd.runId);
 				if (foreground) return foregroundStatusResult(foreground);
@@ -1576,7 +1610,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 					details: { mode: "management", results: [] },
 				};
 			}
-			const validActions = ["list", "get", "create", "update", "delete", "status", "interrupt"];
+			const validActions = ["list", "get", "create", "update", "delete", "status", "interrupt", "doctor"];
 			if (!validActions.includes(params.action)) {
 				return {
 					content: [{ type: "text", text: `Unknown action: ${params.action}. Valid: ${validActions.join(", ")}` }],

package/subagents-status.ts

@@ -3,10 +3,10 @@ import * as path from "node:path";
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { Component, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import { type AsyncRunOverlayData, type AsyncRunSummary, listAsyncRunsForOverlay } from "./async-status.js";
-import { ASYNC_DIR } from "./types.js";
-import { formatDuration, formatTokens, shortenPath } from "./formatters.js";
-import { formatScrollInfo, renderFooter, renderHeader, row } from "./render-helpers.js";
+import { type AsyncRunOverlayData, type AsyncRunSummary, listAsyncRunsForOverlay } from "./async-status.ts";
+import { ASYNC_DIR } from "./types.ts";
+import { formatDuration, formatTokens, shortenPath } from "./formatters.ts";
+import { formatScrollInfo, renderFooter, renderHeader, row } from "./render-helpers.ts";
 
 const AUTO_REFRESH_MS = 2000;
 const DETAIL_EVENT_LIMIT = 8;
@@ -178,13 +178,19 @@ export class SubagentsStatusComponent implements Component {
 	private recent: AsyncRunSummary[] = [];
 	private rows: StatusRow[] = [];
 	private errorMessage?: string;
+	private tui: TUI;
+	private theme: Theme;
+	private done: () => void;
 
 	constructor(
-		private tui: TUI,
-		private theme: Theme,
-		private done: () => void,
+		tui: TUI,
+		theme: Theme,
+		done: () => void,
 		deps: StatusOverlayDeps = {},
 	) {
+		this.tui = tui;
+		this.theme = theme;
+		this.done = done;
 		this.listRunsForOverlay = deps.listRunsForOverlay ?? listAsyncRunsForOverlay;
 		const refreshMs = deps.refreshMs ?? AUTO_REFRESH_MS;
 		this.reload();