pi-subagents 0.20.0 → 0.21.0

package/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
-description: Code review specialist that validates implementation and fixes issues
-tools: read, grep, find, ls, bash, edit, write
+description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
+tools: read, grep, find, ls, bash, edit, write, intercom
 model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
@@ -11,28 +11,86 @@ defaultReads: plan.md, progress.md
 defaultProgress: true
 ---
 
-You are a review-and-fix subagent.
+You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
 
-Review the implementation against the plan, inspect the actual code, and fix any real problems you find.
+## Review types you handle
 
-Working rules:
-- Read the plan and current progress first when they are provided.
-- Use `bash` only for read-only inspection commands like `git diff`, `git log`, `git show`, or test commands.
-- Do not invent issues. Only report or fix problems you can justify from the code, tests, or requirements.
+### 1. Code diffs (changed files)
+Inspect the actual diff or changed files. Verify:
+- Implementation matches intent and requirements.
+- Code is correct, coherent, and handles edge cases.
+- Tests cover the change and still pass.
+- No unintended side effects or regressions.
+- The change is minimal and readable.
+
+### 2. Plans
+Validate a proposed plan for:
+- Feasibility and completeness.
+- Missing steps or hidden risks.
+- Alignment with existing architecture and constraints.
+- Whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach for:
+- Correctness and tradeoffs.
+- Fit with existing codebase patterns.
+- Whether simpler alternatives exist.
+- Edge cases the proposal may miss.
+
+### 4. Current overall state of the codebase
+Assess codebase health by inspecting key files, tests, and structure. Look for:
+- Architecture drift or tech debt.
+- Inconsistent patterns or naming.
+- Areas lacking tests or documentation.
+- Obvious bugs or fragile code.
+- Opportunities to simplify or consolidate.
+
+### 5. Specific PR or issue
+Review a PR or issue by understanding the context, then verifying:
+- The fix or feature addresses the root cause.
+- Changes are minimal and focused.
+- No regressions are introduced.
+- Tests and docs are updated as needed.
+
+## Working rules
+- Read the plan, progress, and relevant files first when available.
+- Use `bash` only for read-only inspection (e.g., `git diff`, `git log`, `git show`, test runs).
+- Do not invent issues. Only report problems you can justify from evidence.
 - Prefer small corrective edits over broad rewrites.
-- If everything looks good, say so plainly and leave the code unchanged.
-- If you are asked to maintain progress, record what you checked and what you fixed.
+- If everything looks good, say so plainly.
+- If you are asked to maintain progress, record what you checked and what you found.
 
-Review checklist:
-1. Implementation matches the plan and task requirements.
-2. Code is correct and coherent.
-3. Important edge cases are handled.
-4. Tests and validation still make sense.
-5. The final code is readable and minimal.
+## Pi-intercom handoff
+If the `intercom` tool is available and pi-intercom is active, send your completed review back to the orchestrator through pi-intercom before finishing.
 
-When updating `progress.md`, add a review section like this:
+Use a blocking `ask`, not a fire-and-forget `send`, so you stay alive long enough for the orchestrator to reply with follow-up questions or approval:
 
+```ts
+intercom({
+  action: "ask",
+  to: "<orchestrator-or-parent-session>",
+  message: "Review complete.\n\n<your review feedback>\n\nReply if you want me to inspect a follow-up or clarify anything."
+})
+```
+
+How to pick the target:
+- Prefer an explicit target named in the task or inherited intercom bridge instructions.
+- Otherwise use `intercom({ action: "list" })` and choose the obvious planner/orchestrator/parent session in the same repo.
+- If no safe target is discoverable, do not guess. Return the review normally and note that pi-intercom was unavailable or no target was clear.
+
+After the `ask` returns:
+- If the orchestrator requests clarification or a follow-up review, answer or inspect further, then use `intercom ask` again if another reply is useful.
+- If the orchestrator confirms or does not need more, finish with the same concise review summary.
+
+## Review output format
+Structure your findings clearly:
+
+```
 ## Review
-- Correct: what is already good
-- Fixed: issue and resolution
-- Note: observations or follow-up items
+- Correct: what is already good (with evidence)
+- Fixed: issue, location, and resolution (if you applied a fix)
+- Blocker: critical issue that must be resolved before proceeding
+- Note: observation, risk, or follow-up item
+```
+
+When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.

package/agents/scout.md

@@ -1,9 +1,9 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff
-tools: read, grep, find, ls, bash, write
+tools: read, grep, find, ls, bash, write, intercom
 model: openai-codex/gpt-5.5
-thinking: medium
+thinking: low
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
@@ -46,3 +46,6 @@ Explain how the pieces connect.
 
 ## Start Here
 Name the first file another agent should open and why.
+
+## Pi-intercom handoff
+If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed scout findings back with a blocking `intercom({ action: "ask", ... })` before finishing. Keep the message concise, include the output path or top findings, and ask whether the orchestrator wants more context. If no safe target is available, do not guess; return normally.

package/agents/worker.md

@@ -1,11 +1,12 @@
 ---
 name: worker
 description: Implementation agent for normal tasks and approved oracle handoffs
-model: openai-codex/gpt-5.3-codex
+model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
+defaultContext: fork
 defaultReads: context.md, plan.md
 defaultProgress: true
 ---
@@ -18,7 +19,7 @@ Use the provided tools directly. First understand the inherited context, supplie
 
 If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
 
-If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate. If runtime bridge instructions are present, use them as the source of truth for which parent session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed. Use `intercom({ action: "send", ... })` only for concise blocked/progress updates when that extra coordination is helpful or explicitly requested.
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which parent session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed, and stay alive to receive the reply before continuing. Use `intercom({ action: "send", ... })` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Do not finish your final response with a question that requires the orchestrator to choose before you can continue.
 
 Default responsibilities:
 - validate the task or approved direction against the actual code
@@ -34,9 +35,11 @@ Working rules:
 - Do not leave placeholder code, TODOs, or silent scope changes.
 - Use `bash` for inspection, validation, and relevant tests.
 - If there is supplied context or a plan, read it first.
-- If implementation reveals a gap in the approved direction, pause and escalate instead of silently patching around it with an implicit decision.
-- If implementation reveals an unapproved product or architecture choice, pause and ask instead of deciding it yourself.
+- If implementation reveals a gap in the approved direction, pause and escalate with `intercom({ action: "ask", ... })` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `intercom({ action: "ask", ... })` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, ask the orchestrator if blocked, or explicitly report that no edits were made.
 - If you send a blocked/progress update through intercom, keep it short and still return the full structured task result normally.
+- If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed implementation summary back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify or handle a small follow-up if requested. If no safe target is available, do not guess; return normally.
 
 When running in a chain, expect instructions about:
 - which files to read first

package/agents.ts

@@ -14,7 +14,8 @@ import { parseFrontmatter } from "./frontmatter.ts";
 export type AgentScope = "user" | "project" | "both";
 
 export type AgentSource = "builtin" | "user" | "project";
-export type SystemPromptMode = "append" | "replace";
+type SystemPromptMode = "append" | "replace";
+export type AgentDefaultContext = "fresh" | "fork";
 
 export function defaultSystemPromptMode(name: string): SystemPromptMode {
 	return name === "delegate" ? "append" : "replace";
@@ -35,6 +36,7 @@ export interface BuiltinAgentOverrideBase {
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
+	defaultContext?: AgentDefaultContext;
 	disabled?: boolean;
 	systemPrompt: string;
 	skills?: string[];
@@ -42,20 +44,21 @@ export interface BuiltinAgentOverrideBase {
 	mcpDirectTools?: string[];
 }
 
-export interface BuiltinAgentOverrideConfig {
+interface BuiltinAgentOverrideConfig {
 	model?: string | false;
 	fallbackModels?: string[] | false;
 	thinking?: string | false;
 	systemPromptMode?: SystemPromptMode;
 	inheritProjectContext?: boolean;
 	inheritSkills?: boolean;
+	defaultContext?: AgentDefaultContext | false;
 	disabled?: boolean;
 	systemPrompt?: string;
 	skills?: string[] | false;
 	tools?: string[] | false;
 }
 
-export interface BuiltinAgentOverrideInfo {
+interface BuiltinAgentOverrideInfo {
 	scope: "user" | "project";
 	path: string;
 	base: BuiltinAgentOverrideBase;
@@ -72,6 +75,7 @@ export interface AgentConfig {
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
+	defaultContext?: AgentDefaultContext;
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
@@ -113,7 +117,7 @@ export interface ChainConfig {
 	extraFields?: Record<string, string>;
 }
 
-export interface AgentDiscoveryResult {
+interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
 }
@@ -160,6 +164,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,
+		defaultContext: agent.defaultContext,
 		disabled: agent.disabled,
 		systemPrompt: agent.systemPrompt,
 		skills: agent.skills ? [...agent.skills] : undefined,
@@ -178,6 +183,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.systemPromptMode !== undefined ? { systemPromptMode: override.systemPromptMode } : {}),
 		...(override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {}),
 		...(override.inheritSkills !== undefined ? { inheritSkills: override.inheritSkills } : {}),
+		...(override.defaultContext !== undefined ? { defaultContext: override.defaultContext } : {}),
 		...(override.disabled !== undefined ? { disabled: override.disabled } : {}),
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
@@ -198,11 +204,11 @@ function findNearestProjectRoot(cwd: string): string | null {
 	}
 }
 
-export function getUserAgentSettingsPath(): string {
+function getUserAgentSettingsPath(): string {
 	return path.join(os.homedir(), ".pi", "agent", "settings.json");
 }
 
-export function getProjectAgentSettingsPath(cwd: string): string | null {
+function getProjectAgentSettingsPath(cwd: string): string | null {
 	const projectRoot = findNearestProjectRoot(cwd);
 	return projectRoot ? path.join(projectRoot, ".pi", "settings.json") : null;
 }
@@ -302,6 +308,14 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("defaultContext" in input) {
+		if (input.defaultContext === "fresh" || input.defaultContext === "fork" || input.defaultContext === false) {
+			override.defaultContext = input.defaultContext;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultContext'; expected 'fresh', 'fork', or false.`);
+		}
+	}
+
 	if ("disabled" in input) {
 		if (typeof input.disabled === "boolean") {
 			override.disabled = input.disabled;
@@ -373,6 +387,7 @@ function applyBuiltinOverride(
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
+	if (override.defaultContext !== undefined) next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
 	if (override.disabled !== undefined) next.disabled = override.disabled;
 	if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
 	if (override.skills !== undefined) next.skills = override.skills === false ? undefined : [...override.skills];
@@ -420,7 +435,7 @@ function applyBuiltinOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -430,6 +445,7 @@ export function buildBuiltinOverrideConfig(
 	if (draft.systemPromptMode !== base.systemPromptMode) override.systemPromptMode = draft.systemPromptMode;
 	if (draft.inheritProjectContext !== base.inheritProjectContext) override.inheritProjectContext = draft.inheritProjectContext;
 	if (draft.inheritSkills !== base.inheritSkills) override.inheritSkills = draft.inheritSkills;
+	if (draft.defaultContext !== base.defaultContext) override.defaultContext = draft.defaultContext ?? false;
 	if (draft.disabled !== base.disabled) override.disabled = draft.disabled ?? false;
 	if (draft.systemPrompt !== base.systemPrompt) override.systemPrompt = draft.systemPrompt;
 	if (!arraysEqual(draft.skills, base.skills)) override.skills = draft.skills ? [...draft.skills] : false;
@@ -568,6 +584,11 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			: frontmatter.inheritSkills === "false"
 				? false
 				: defaultInheritSkills();
+		const defaultContext = frontmatter.defaultContext === "fork"
+			? "fork" as const
+			: frontmatter.defaultContext === "fresh"
+				? "fresh" as const
+				: undefined;
 
 		let extensions: string[] | undefined;
 		if (frontmatter.extensions !== undefined) {
@@ -595,6 +616,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			systemPromptMode,
 			inheritProjectContext,
 			inheritSkills,
+			defaultContext,
 			systemPrompt: body,
 			source,
 			filePath,

package/async-execution.ts

@@ -55,14 +55,14 @@ const jitiCliPath: string | undefined = (() => {
 	return undefined;
 })();
 
-export interface AsyncExecutionContext {
+interface AsyncExecutionContext {
 	pi: ExtensionAPI;
 	cwd: string;
 	currentSessionId: string;
 	currentModelProvider?: string;
 }
 
-export interface AsyncChainParams {
+interface AsyncChainParams {
 	chain: ChainStep[];
 	resultMode?: "parallel" | "chain";
 	agents: AgentConfig[];
@@ -84,7 +84,7 @@ export interface AsyncChainParams {
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 }
 
-export interface AsyncSingleParams {
+interface AsyncSingleParams {
 	agent: string;
 	task?: string;
 	agentConfig: AgentConfig;
@@ -108,7 +108,7 @@ export interface AsyncSingleParams {
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 }
 
-export interface AsyncExecutionResult {
+interface AsyncExecutionResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: Details;
 	isError?: boolean;
@@ -167,6 +167,10 @@ function formatAsyncStartError(mode: "single" | "chain", message: string): Async
 	};
 }
 
+const UNAVAILABLE_SUBAGENT_SKILL_ERROR = "Skills not found: pi-subagents";
+
+class UnavailableSubagentSkillError extends Error {}
+
 /**
  * Execute a chain asynchronously
  */
@@ -240,7 +244,8 @@ export function executeAsyncChain(
 		const instructionCwd = behaviorCwd ?? stepCwd;
 		const behavior = resolvedBehavior ?? resolveStepBehavior(a, buildStepOverrides(s), chainSkills);
 		const skillNames = behavior.skills === false ? [] : behavior.skills;
-		const { resolved: resolvedSkills } = resolveSkillsWithFallback(skillNames, stepCwd, ctx.cwd);
+		const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(skillNames, stepCwd, ctx.cwd);
+		if (missingSkills.includes("pi-subagents")) throw new UnavailableSubagentSkillError(UNAVAILABLE_SUBAGENT_SKILL_ERROR);
 
 		let systemPrompt = a.systemPrompt?.trim() ?? "";
 		if (resolvedSkills.length > 0) {
@@ -285,36 +290,42 @@ export function executeAsyncChain(
 		return sessionFile;
 	};
 
-	const steps: RunnerStep[] = chain.map((s, stepIndex) => {
-		if (isParallelStep(s)) {
-			const parallelBehaviors = s.parallel.map((task) => {
-				const agent = agents.find((candidate) => candidate.name === task.agent)!;
-				return resolveStepBehavior(agent, buildStepOverrides(task), chainSkills);
-			});
-			const progressPrecreated = parallelBehaviors.some((behavior) => behavior.progress);
-			if (progressPrecreated) {
-				if (!s.worktree) writeInitialProgressFile(runnerCwd);
-				progressInstructionCreated = true;
-			}
-			return {
-				parallel: s.parallel.map((t, taskIndex) => {
-					let behaviorCwd: string | undefined;
-					if (s.worktree) {
-						try {
-							behaviorCwd = resolveExpectedWorktreeAgentCwd(runnerCwd, `${id}-s${stepIndex}`, taskIndex);
-						} catch {
-							behaviorCwd = undefined;
+	let steps: RunnerStep[];
+	try {
+		steps = chain.map((s, stepIndex) => {
+			if (isParallelStep(s)) {
+				const parallelBehaviors = s.parallel.map((task) => {
+					const agent = agents.find((candidate) => candidate.name === task.agent)!;
+					return resolveStepBehavior(agent, buildStepOverrides(task), chainSkills);
+				});
+				const progressPrecreated = parallelBehaviors.some((behavior) => behavior.progress);
+				if (progressPrecreated) {
+					if (!s.worktree) writeInitialProgressFile(runnerCwd);
+					progressInstructionCreated = true;
+				}
+				return {
+					parallel: s.parallel.map((t, taskIndex) => {
+						let behaviorCwd: string | undefined;
+						if (s.worktree) {
+							try {
+								behaviorCwd = resolveExpectedWorktreeAgentCwd(runnerCwd, `${id}-s${stepIndex}`, taskIndex);
+							} catch {
+								behaviorCwd = undefined;
+							}
 						}
-					}
-					return buildSeqStep(t, nextSessionFile(), behaviorCwd, progressPrecreated, parallelBehaviors[taskIndex]);
-				}),
-				concurrency: s.concurrency,
-				failFast: s.failFast,
-				worktree: s.worktree,
-			};
-		}
-		return buildSeqStep(s as SequentialStep, nextSessionFile());
-	});
+						return buildSeqStep(t, nextSessionFile(), behaviorCwd, progressPrecreated, parallelBehaviors[taskIndex]);
+					}),
+					concurrency: s.concurrency,
+					failFast: s.failFast,
+					worktree: s.worktree,
+				};
+			}
+			return buildSeqStep(s as SequentialStep, nextSessionFile());
+		});
+	} catch (error) {
+		if (error instanceof UnavailableSubagentSkillError) return formatAsyncStartError("chain", error.message);
+		throw error;
+	}
 	let childTargetIndex = 0;
 	const childIntercomTargets = childIntercomTarget ? steps.flatMap((step) => {
 		if ("parallel" in step) {
@@ -365,16 +376,33 @@ export function executeAsyncChain(
 		const firstAgents = isParallelStep(firstStep)
 			? firstStep.parallel.map((t) => t.agent)
 			: [(firstStep as SequentialStep).agent];
+		const parallelGroups: Array<{ start: number; count: number; stepIndex: number }> = [];
+		const flatAgents: string[] = [];
+		let flatStepStart = 0;
+		for (let stepIndex = 0; stepIndex < chain.length; stepIndex++) {
+			const step = chain[stepIndex]!;
+			if (isParallelStep(step)) {
+				parallelGroups.push({ start: flatStepStart, count: step.parallel.length, stepIndex });
+				flatAgents.push(...step.parallel.map((task) => task.agent));
+				flatStepStart += step.parallel.length;
+			} else {
+				flatAgents.push((step as SequentialStep).agent);
+				flatStepStart++;
+			}
+		}
 		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
 			id,
 			pid: spawnResult.pid,
 			agent: firstAgents[0],
+			agents: flatAgents,
 			task: isParallelStep(firstStep)
 				? firstStep.parallel[0]?.task?.slice(0, 50)
 				: (firstStep as SequentialStep).task?.slice(0, 50),
 			chain: chain.map((s) =>
 				isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
 			),
+			chainStepCount: chain.length,
+			parallelGroups,
 			cwd: runnerCwd,
 			asyncDir,
 		});
@@ -421,7 +449,8 @@ export function executeAsyncSingle(
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
 	const skillNames = params.skills ?? agentConfig.skills ?? [];
 	const availableModels = params.availableModels;
-	const { resolved: resolvedSkills } = resolveSkillsWithFallback(skillNames, runnerCwd, ctx.cwd);
+	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(skillNames, runnerCwd, ctx.cwd);
+	if (missingSkills.includes("pi-subagents")) return formatAsyncStartError("single", UNAVAILABLE_SUBAGENT_SKILL_ERROR);
 	let systemPrompt = agentConfig.systemPrompt?.trim() ?? "";
 	if (resolvedSkills.length > 0) {
 		const injection = buildSkillInjection(resolvedSkills);

package/async-job-tracker.ts

@@ -5,6 +5,8 @@ import { renderWidget } from "./render.ts";
 import { formatControlNoticeMessage } from "./subagent-control.ts";
 import {
 	type AsyncJobState,
+	type AsyncParallelGroupStatus,
+	type AsyncStartedEvent,
 	type ControlEvent,
 	type SubagentState,
 	POLL_INTERVAL_MS,
@@ -13,6 +15,23 @@ import {
 } from "./types.ts";
 import { readStatus } from "./utils.ts";
 
+
+function isValidParallelGroup(group: AsyncParallelGroupStatus, stepCount: number, chainStepCount: number): boolean {
+	return Number.isInteger(group.start)
+		&& Number.isInteger(group.count)
+		&& Number.isInteger(group.stepIndex)
+		&& group.start >= 0
+		&& group.count > 0
+		&& group.stepIndex >= 0
+		&& group.stepIndex < chainStepCount
+		&& group.start + group.count <= stepCount;
+}
+
+function normalizeParallelGroups(groups: AsyncParallelGroupStatus[] | undefined, stepCount: number, chainStepCount: number): AsyncParallelGroupStatus[] {
+	if (!groups?.length) return [];
+	return groups.filter((group) => isValidParallelGroup(group, stepCount, chainStepCount));
+}
+
 interface AsyncJobTrackerOptions {
 	completionRetentionMs?: number;
 	pollIntervalMs?: number;
@@ -66,8 +85,8 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				let parsed: unknown;
 				try {
 					parsed = JSON.parse(line);
-				} catch {
-					// Ignore malformed completed records but keep the poller alive for later events.
+				} catch (error) {
+					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
 					continue;
 				}
 				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") continue;
@@ -83,7 +102,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				if (record.channels.includes("event")) {
 					pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
 				}
-				if (record.channels.includes("intercom") && record.intercom?.to && record.intercom.message) {
+				if (record.event.type !== "active_long_running" && record.channels.includes("intercom") && record.intercom?.to && record.intercom.message) {
 					pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
 						...payload,
 						to: record.intercom.to,
@@ -119,15 +138,30 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.status = status.state;
 						job.activityState = status.activityState;
 						job.lastActivityAt = status.lastActivityAt ?? job.lastActivityAt;
-						job.currentTool = status.currentTool ?? job.currentTool;
-						job.currentToolStartedAt = status.currentToolStartedAt ?? job.currentToolStartedAt;
+						job.currentTool = status.currentTool;
+						job.currentToolStartedAt = status.currentToolStartedAt;
+						job.currentPath = status.currentPath;
+						job.turnCount = status.turnCount ?? job.turnCount;
+						job.toolCount = status.toolCount ?? job.toolCount;
 						job.mode = status.mode;
 						job.currentStep = status.currentStep ?? job.currentStep;
-						job.stepsTotal = status.steps?.length ?? job.stepsTotal;
 						job.startedAt = status.startedAt ?? job.startedAt;
 						job.updatedAt = status.lastUpdate ?? Date.now();
 						if (status.steps?.length) {
-							job.agents = status.steps.map((step) => step.agent);
+							const groups = normalizeParallelGroups(status.parallelGroups, status.steps.length, status.chainStepCount ?? status.steps.length);
+							job.hasParallelGroups = groups.length > 0 || job.hasParallelGroups;
+							const activeGroup = status.currentStep !== undefined
+								? groups.find((group) => status.currentStep! >= group.start && status.currentStep! < group.start + group.count)
+								: undefined;
+							const visibleSteps = activeGroup
+								? status.steps.slice(activeGroup.start, activeGroup.start + activeGroup.count)
+								: status.steps;
+							job.activeParallelGroup = Boolean(activeGroup);
+							job.agents = visibleSteps.map((step) => step.agent);
+							job.stepsTotal = visibleSteps.length;
+							job.runningSteps = visibleSteps.filter((step) => step.status === "running").length;
+							job.completedSteps = visibleSteps.filter((step) => step.status === "complete" || step.status === "completed").length;
+							if (status.state === "complete") job.completedSteps = visibleSteps.length;
 						}
 						job.sessionDir = status.sessionDir ?? job.sessionDir;
 						job.outputFile = status.outputFile ?? job.outputFile;
@@ -153,23 +187,26 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	};
 
 	const handleStarted = (data: unknown) => {
-		const info = data as {
-			id?: string;
-			asyncDir?: string;
-			agent?: string;
-			chain?: string[];
-		};
+		const info = data as AsyncStartedEvent;
 		if (!info.id) return;
 		const now = Date.now();
 		const asyncDir = info.asyncDir ?? path.join(asyncDirRoot, info.id);
-		const agents = info.chain && info.chain.length > 0 ? info.chain : info.agent ? [info.agent] : undefined;
+		const rawAgents = info.agents?.length ? info.agents : info.chain && info.chain.length > 0 ? info.chain : info.agent ? [info.agent] : undefined;
+		const validParallelGroups = normalizeParallelGroups(info.parallelGroups, Number.MAX_SAFE_INTEGER, info.chainStepCount ?? Number.MAX_SAFE_INTEGER);
+		const firstGroup = validParallelGroups.find((group) => group.start === 0);
+		const firstGroupCount = firstGroup?.count;
+		const agents = firstGroupCount && firstGroupCount > 0
+			? rawAgents?.slice(0, firstGroupCount)
+			: rawAgents;
 		state.asyncJobs.set(info.id, {
 			asyncId: info.id,
 			asyncDir,
 			status: "queued",
 			mode: info.chain ? "chain" : "single",
 			agents,
-			stepsTotal: agents?.length,
+			stepsTotal: firstGroupCount ?? agents?.length,
+			hasParallelGroups: validParallelGroups.length > 0,
+			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
 			startedAt: now,
 			updatedAt: now,
 		});