pi-subagents 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-04-29
+
+### Changed
+- Document the recommended parent-agent workflow as `clarify → planner → worker → fresh reviewers → worker` in the docs and bundled skill.
+- Packaged `planner`, `worker`, and `oracle` now default to forked session context when the launch omits `context`; explicit `context: "fresh"` still overrides the agent default.
+- Expanded builtin subagent guidance so agents with a safe pi-intercom target can hand results back with blocking `intercom ask`, documented the self-orchestrated clarify → plan → implement → review workflow, and added GPT-5.5-oriented subagent prompt guidance to the bundled skill and `context-builder`.
+
+### Fixed
+- Prevent child subagents from receiving parent orchestration tooling/history, and inject boundary instructions that forbid sub-delegation and pseudo tool calls.
+- Added active-long-running and repeated mutating-tool failure notices so supervised/forked workers cannot burn turns silently while still appearing healthy.
+- Fixed task editor wrapping so wide characters cannot push text past the right border.
+- Mark implementation subagents as failed when they complete without any file mutation attempt.
+- Applied the same no-mutation completion guard to async/background runner paths.
+- Split terminal no-mutation guard notices from live idle notices so completed failures do not suggest status or interrupt commands.
+- Clarified worker/intercom bridge instructions so blocked decisions use `intercom ask` and stay alive for the reply instead of completing with a question.
+- Labeled the Agents widget as async/background work so running detached agents are easier to identify.
+- Reworked parallel progress wording so parallel runs show running/done agent counts (and chain parallel groups show `step X/Y · parallel group` with agent fractions) instead of serial `step X/Y` counters.
+- Expanded `/parallel-cleanup` guidance to flag redundant wrapper tests when one focused regression is enough.
+- Fixed flexible schema validation for `reads` and `skill` overrides so `reads: false`, `skill: "review"`, and `skill: false` no longer trigger `element.reads.every is not a function` (issue #124).
+- Hardened slash-result and async-widget animation timers so stale extension contexts after `/new` or reload stop their timers instead of crashing on `ctx.ui` access (issue #122).
+
+## [0.20.1] - 2026-04-27
+
+### Fixed
+- Made the packaged `/parallel-cleanup` prompt self-contained instead of referencing local-only cleanup skills.
+
 ## [0.20.0] - 2026-04-27
 
 ### Added

package/README.md

@@ -174,6 +174,20 @@ or ask:
 Check whether subagents and intercom are set up correctly.
 ```
 
+## Recommended orchestration pattern (scaffolding)
+
+Use orchestration as parent-agent guidance, not as a runtime workflow mode. For implementation work, the recommended loop is:
+
+```text
+clarify → planner → worker → fresh reviewers → worker
+```
+
+Use the optional prompt shortcuts below when you want the pattern to be repeatable.
+
+Packaged `planner`, `worker`, and `oracle` default to forked context when a launch omits `context`; pass `context: "fresh"` when you intentionally want a fresh child run.
+
+Child-safety boundaries are enforced at runtime. Spawned child sessions do not register the `subagent` tool, do not receive the bundled `pi-subagents` skill, and receive explicit boundary instructions that they are not the parent orchestrator and must not propose or run subagents. Forked child context filtering also removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
+
 ## Optional shortcuts
 
 The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
@@ -183,6 +197,7 @@ The package includes reusable prompt templates for common workflows. You do not
 | `/parallel-review` | Launch fresh-context reviewers with distinct angles, then synthesize what to fix. |
 | `/parallel-research` | Combine `researcher` and `scout` for external evidence, local code context, and practical tradeoffs. |
 | `/gather-context-and-clarify` | Scout/research first, then ask the user the clarification questions that matter. |
+| `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
 
 ## Optional pi-intercom companion
 
@@ -237,7 +252,7 @@ Skip this section until you want exact syntax.
 | `/subagents-status` | Open the active/recent run overlay |
 | `/subagents-doctor` | Show read-only setup diagnostics |
 
-Commands validate agent names locally, support tab completion, and still send results back into the conversation.
+Commands validate agent names locally, support tab completion, and send results back into the conversation.
 
 ### Per-step tasks
 
@@ -413,7 +428,7 @@ Example:
 }
 ```
 
-Supported override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `disabled`, `skills`, `tools`, and `systemPrompt`. Project overrides beat user overrides.
+Supported override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `disabled`, `skills`, `tools`, and `systemPrompt`. Use `defaultContext: false` in builtin overrides to clear an inherited context default. Project overrides beat user overrides.
 
 You can also manage builtin overrides from `/agents`. On a builtin detail screen, press `e`, choose user or project scope if needed, and save the fields you want to override.
 
@@ -430,6 +445,7 @@ Use these fields when an agent should see more:
 | `systemPromptMode: append` | Append the agent prompt to Pi’s normal base prompt. |
 | `inheritProjectContext: true` | Keep inherited project instructions from files like `AGENTS.md` and `CLAUDE.md`. |
 | `inheritSkills: true` | Let the child see Pi’s discovered skills catalog. |
+| `defaultContext: fork` | Use forked session context when a launch omits `context`; explicit `context: "fresh"` still wins. |
 
 Builtin agents opt into project instruction inheritance by default so they follow repo-specific rules out of the box. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
 
@@ -472,6 +488,7 @@ Important fields:
 | `systemPromptMode` | `replace` by default; `append` keeps Pi’s base prompt. |
 | `inheritProjectContext` | Keeps or strips inherited project instruction blocks. |
 | `inheritSkills` | Keeps or strips Pi’s discovered skills catalog. |
+| `defaultContext` | Optional `fresh` or `fork` launch context default for this agent. |
 | `skills` | Injects specific skills directly, regardless of `inheritSkills`. |
 | `output` | Default single-agent output file. |
 | `defaultReads` | Files to read before running in chain/parallel behavior. |
@@ -712,7 +729,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
 | `chain` | array | - | Sequential and parallel chain steps. |
-| `context` | `fresh \| fork` | `fresh` | `fork` creates real branched sessions from the parent leaf. |
+| `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
 | `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
 | `clarify` | boolean | true for chains | Show TUI preview/edit flow. |
 | `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
@@ -724,7 +741,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `share` | boolean | false | Upload session export to GitHub Gist. |
 | `sessionDir` | string | derived | Override session log directory. |
 
-`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`.
+`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`. In multi-agent runs, if any requested agent has `defaultContext: fork` and the launch omits `context`, the whole invocation uses forked context; pass `context: "fresh"` when you intentionally want a fresh run.
 
 Sequential and parallel chain tasks accept `agent`, `task`, `cwd`, `output`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`.
 

package/agent-management.ts

@@ -67,7 +67,7 @@ function normalizeListScope(scope: unknown): AgentScope | undefined {
 	return undefined;
 }
 
-export function sanitizeName(name: string): string {
+function sanitizeName(name: string): string {
 	return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
 }
 
@@ -81,7 +81,7 @@ function availableNames(cwd: string, kind: "agent" | "chain"): string[] {
 	return [...new Set(items.map((x) => x.name))].sort((a, b) => a.localeCompare(b));
 }
 
-export function findAgents(name: string, cwd: string, scope: AgentScope = "both"): AgentConfig[] {
+function findAgents(name: string, cwd: string, scope: AgentScope = "both"): AgentConfig[] {
 	const d = discoverAgentsAll(cwd);
 	const raw = name.trim();
 	const sanitized = sanitizeName(raw);
@@ -90,7 +90,7 @@ export function findAgents(name: string, cwd: string, scope: AgentScope = "both"
 		.sort((a, b) => a.source.localeCompare(b.source));
 }
 
-export function findChains(name: string, cwd: string, scope: AgentScope = "both"): ChainConfig[] {
+function findChains(name: string, cwd: string, scope: AgentScope = "both"): ChainConfig[] {
 	const raw = name.trim();
 	const sanitized = sanitizeName(raw);
 	return discoverAgentsAll(cwd).chains
@@ -259,6 +259,11 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
 		target.inheritSkills = cfg.inheritSkills;
 	}
+	if (hasKey(cfg, "defaultContext")) {
+		if (cfg.defaultContext === false || cfg.defaultContext === "") target.defaultContext = undefined;
+		else if (cfg.defaultContext === "fresh" || cfg.defaultContext === "fork") target.defaultContext = cfg.defaultContext;
+		else return "config.defaultContext must be 'fresh', 'fork', or false when provided.";
+	}
 	if (hasKey(cfg, "output")) {
 		if (cfg.output === false || cfg.output === "") target.output = undefined;
 		else if (typeof cfg.output === "string") target.output = cfg.output;
@@ -328,7 +333,7 @@ function renamePath(
 	return { filePath };
 }
 
-export function formatAgentDetail(agent: AgentConfig): string {
+function formatAgentDetail(agent: AgentConfig): string {
 	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
 	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
 	if (agent.model) lines.push(`Model: ${agent.model}`);
@@ -338,6 +343,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	lines.push(`System prompt mode: ${agent.systemPromptMode}`);
 	lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
+	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
@@ -349,7 +355,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	return lines.join("\n");
 }
 
-export function formatChainDetail(chain: ChainConfig): string {
+function formatChainDetail(chain: ChainConfig): string {
 	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`, "", "Steps:"];
 	for (let i = 0; i < chain.steps.length; i++) {
 		const s = chain.steps[i]!;
@@ -376,8 +382,12 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const lines = [
 		"Executable agents:",
-		...(agents.length ? agents.map((a) => `- ${a.name} (${a.source}): ${a.description}`) : ["- (none)"]),
-		...(disabledBuiltins.length ? ["", "Disabled builtins:", ...disabledBuiltins.map((a) => `- ${a.name} (${a.source}, disabled): ${a.description}`)] : []),
+		...(agents.length
+			? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}`)
+			: ["- (none)"]),
+		...(disabledBuiltins.length
+			? ["", "Disabled builtins:", ...disabledBuiltins.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}, disabled): ${a.description}`)]
+			: []),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
@@ -385,7 +395,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	return result(lines.join("\n"));
 }
 
-export function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for get.", true);
 	const hasBoth = Boolean(params.agent && params.chainName);
 	const blocks: string[] = [];
@@ -560,7 +570,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 	return result([headline, ...warnings].join("\n"));
 }
 
-export function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for delete.", true);
 	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
 	const scopeHint = asDisambiguationScope(params.agentScope);

package/agent-manager-chain-detail.ts

@@ -17,7 +17,7 @@ const CHAIN_DETAIL_VIEWPORT_HEIGHT = 12;
 
 type DetailChainStep = ChainStepConfig | ChainStep;
 
-export function buildDependencyMap(steps: DetailChainStep[]): Map<number, number[]> {
+function buildDependencyMap(steps: DetailChainStep[]): Map<number, number[]> {
 	const outputMap = new Map<string, number>();
 	const deps = new Map<number, number[]>();
 	for (let i = 0; i < steps.length; i++) {

package/agent-manager-detail.ts

@@ -58,12 +58,14 @@ function buildDetailLines(
 	const output = agent.output ?? "(none)";
 	const reads = agent.defaultReads && agent.defaultReads.length > 0 ? agent.defaultReads.join(", ") : "(none)";
 	const progress = agent.defaultProgress ? "on" : "off";
+	const defaultContext = agent.defaultContext ?? "auto";
 	const maxSubagentDepth = agent.maxSubagentDepth !== undefined ? String(agent.maxSubagentDepth) : "(default)";
 
 	lines.push(renderFieldLine("Model:", agent.model ?? "default", contentWidth, theme));
 	lines.push(renderFieldLine("Prompt mode:", agent.systemPromptMode, contentWidth, theme));
 	lines.push(renderFieldLine("Project ctx:", agent.inheritProjectContext ? "on" : "off", contentWidth, theme));
 	lines.push(renderFieldLine("Skills ctx:", agent.inheritSkills ? "on" : "off", contentWidth, theme));
+	lines.push(renderFieldLine("Run context:", defaultContext, contentWidth, theme));
 	if (agent.source === "builtin") {
 		lines.push(renderFieldLine("Disabled:", agent.disabled ? "on" : "off", contentWidth, theme));
 	}

package/agent-manager-edit.ts

@@ -1,6 +1,6 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import { defaultSystemPromptMode, type AgentConfig, type BuiltinAgentOverrideBase } from "./agents.ts";
+import { defaultSystemPromptMode, type AgentConfig, type AgentDefaultContext, type BuiltinAgentOverrideBase } from "./agents.ts";
 import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.ts";
 import type { TextEditorState } from "./text-editor.ts";
 import { pad, row, renderHeader, renderFooter, formatScrollInfo } from "./render-helpers.ts";
@@ -18,15 +18,15 @@ export interface EditState {
 	title?: string;
 	overrideBase?: BuiltinAgentOverrideBase;
 }
-export interface EditInputResult { action?: "save" | "discard" | "delete"; nextScreen?: EditScreen; }
-export interface CreateEditStateOptions {
+interface EditInputResult { action?: "save" | "discard" | "delete"; nextScreen?: EditScreen; }
+interface CreateEditStateOptions {
 	fields?: EditField[];
 	title?: string;
 	overrideBase?: BuiltinAgentOverrideBase;
 }
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
+const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
 type ThinkingLevel = typeof THINKING_LEVELS[number];
 const PROMPT_VIEWPORT_HEIGHT = 16;
 const MODEL_SELECTOR_HEIGHT = 10;
@@ -38,6 +38,12 @@ function parseTools(value: string): { tools?: string[]; mcp?: string[] } { const
 function parseCommaList(value: string): string[] | undefined { const items = value.split(",").map((item) => item.trim()).filter((item) => item.length > 0); return items.length > 0 ? items : undefined; }
 function arraysEqual(a: string[] | undefined, b: string[] | undefined): boolean { if (!a && !b) return true; if (!a || !b || a.length !== b.length) return false; for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false; return true; }
 
+function nextDefaultContext(value: AgentDefaultContext | undefined): AgentDefaultContext | undefined {
+	if (value === undefined) return "fork";
+	if (value === "fork") return "fresh";
+	return undefined;
+}
+
 function fieldValueMatchesBase(field: EditField, state: EditState): boolean {
 	const base = state.overrideBase;
 	if (!base) return false;
@@ -48,6 +54,7 @@ function fieldValueMatchesBase(field: EditField, state: EditState): boolean {
 		case "systemPromptMode": return state.draft.systemPromptMode === base.systemPromptMode;
 		case "inheritProjectContext": return state.draft.inheritProjectContext === base.inheritProjectContext;
 		case "inheritSkills": return state.draft.inheritSkills === base.inheritSkills;
+		case "defaultContext": return state.draft.defaultContext === base.defaultContext;
 		case "disabled": return state.draft.disabled === base.disabled;
 		case "tools": return arraysEqual(toolList(state.draft), toolList(base));
 		case "skills": return arraysEqual(state.draft.skills, base.skills);
@@ -66,6 +73,7 @@ function resetFieldToBase(field: EditField, state: EditState): void {
 		case "systemPromptMode": state.draft.systemPromptMode = base.systemPromptMode; break;
 		case "inheritProjectContext": state.draft.inheritProjectContext = base.inheritProjectContext; break;
 		case "inheritSkills": state.draft.inheritSkills = base.inheritSkills; break;
+		case "defaultContext": state.draft.defaultContext = base.defaultContext; break;
 		case "disabled": state.draft.disabled = base.disabled; break;
 		case "tools": state.draft.tools = base.tools ? [...base.tools] : undefined; state.draft.mcpDirectTools = base.mcpDirectTools ? [...base.mcpDirectTools] : undefined; break;
 		case "skills": state.draft.skills = base.skills ? [...base.skills] : undefined; break;
@@ -94,6 +102,7 @@ function renderFieldValue(field: EditField, state: EditState): string {
 		case "systemPromptMode": return draft.systemPromptMode ?? defaultSystemPromptMode(draft.name);
 		case "inheritProjectContext": return draft.inheritProjectContext ? "on" : "off";
 		case "inheritSkills": return draft.inheritSkills ? "on" : "off";
+		case "defaultContext": return draft.defaultContext ?? "auto";
 		case "disabled": return draft.disabled ? "on" : "off";
 		case "tools": return formatTools(draft);
 		case "extensions": return draft.extensions !== undefined ? (draft.extensions.length > 0 ? draft.extensions.join(", ") : "") : "(all)";
@@ -129,6 +138,15 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 		case "skills": draft.skills = parseCommaList(value); break;
 		case "output": { const trimmed = value.trim(); draft.output = trimmed.length > 0 ? trimmed : undefined; break; }
 		case "reads": draft.defaultReads = parseCommaList(value); break;
+		case "defaultContext": {
+			const trimmed = value.trim();
+			if (trimmed === "" || trimmed === "auto") {
+				draft.defaultContext = undefined;
+				break;
+			}
+			if (trimmed === "fresh" || trimmed === "fork") draft.defaultContext = trimmed;
+			break;
+		}
 		case "inheritProjectContext":
 		case "inheritSkills":
 		case "disabled":
@@ -260,9 +278,10 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 		if (data === "m") { openModelPicker(state, models); return { nextScreen: "edit-field" }; }
 		if (data === "t") { openThinkingPicker(state); return { nextScreen: "edit-field" }; }
 		if (data === "s") { openSkillPicker(state, skills); return { nextScreen: "edit-field" }; }
-		if (data === " " && (field === "inheritProjectContext" || field === "inheritSkills" || field === "disabled" || field === "progress" || field === "interactive")) {
+		if (data === " " && (field === "inheritProjectContext" || field === "inheritSkills" || field === "defaultContext" || field === "disabled" || field === "progress" || field === "interactive")) {
 			if (field === "inheritProjectContext") state.draft.inheritProjectContext = !state.draft.inheritProjectContext;
 			if (field === "inheritSkills") state.draft.inheritSkills = !state.draft.inheritSkills;
+			if (field === "defaultContext") state.draft.defaultContext = nextDefaultContext(state.draft.defaultContext);
 			if (field === "disabled") state.draft.disabled = !state.draft.disabled;
 			if (field === "progress") state.draft.defaultProgress = !state.draft.defaultProgress;
 			if (field === "interactive") state.draft.interactive = !state.draft.interactive;
@@ -273,6 +292,10 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 			if (field === "thinking") { openThinkingPicker(state); return { nextScreen: "edit-field" }; }
 			if (field === "skills") { openSkillPicker(state, skills); return { nextScreen: "edit-field" }; }
 			if (field === "prompt") { state.promptEditor = createEditorState(state.draft.systemPrompt ?? ""); return { nextScreen: "edit-prompt" }; }
+			if (field === "defaultContext") {
+				state.draft.defaultContext = nextDefaultContext(state.draft.defaultContext);
+				return;
+			}
 			if (field === "inheritProjectContext" || field === "inheritSkills" || field === "disabled" || field === "progress" || field === "interactive") return;
 			state.fieldMode = "text"; state.fieldEditor = createEditorState(renderFieldValue(field, state)); return { nextScreen: "edit-field" };
 		}
@@ -346,7 +369,9 @@ export function renderEdit(screen: EditScreen, state: EditState, width: number,
 				? "Project Ctx"
 				: field === "inheritSkills"
 					? "Skills Ctx"
-					: field === "disabled"
+					: field === "defaultContext"
+						? "Default Ctx"
+						: field === "disabled"
 						? "Disabled"
 					: `${field[0]!.toUpperCase()}${field.slice(1)}`;
 		const rawLabel = pad(`${fieldLabel}:`, labelWidth);

package/agent-manager-parallel.ts

@@ -4,7 +4,7 @@ import type { TextEditorState } from "./text-editor.ts";
 import { createEditorState, handleEditorInput, renderEditor, wrapText, getCursorDisplayPos, ensureCursorVisible } from "./text-editor.ts";
 import { pad, row, renderHeader, renderFooter, fuzzyFilter } from "./render-helpers.ts";
 
-export interface ParallelSlot {
+interface ParallelSlot {
 	agentName: string;
 	customTask: string;
 }
@@ -20,7 +20,7 @@ export interface ParallelState {
 	editEditor: TextEditorState | null;
 }
 
-export type ParallelAction =
+type ParallelAction =
 	| { type: "proceed" }
 	| { type: "back" };
 

package/agent-manager.ts

@@ -44,7 +44,7 @@ interface NameInputState { mode: "new-agent" | "clone-agent" | "clone-chain" | "
 interface StatusMessage { text: string; type: "error" | "info"; }
 interface OverrideScopeState { selectedScope: "user" | "project"; allowProject: boolean; }
 
-const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "disabled", "tools", "skills", "prompt"];
+const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "disabled", "tools", "skills", "prompt"];
 
 function cloneConfig(config: AgentConfig): AgentConfig {
 	return {
@@ -61,6 +61,7 @@ function cloneConfig(config: AgentConfig): AgentConfig {
 				base: {
 					...config.override.base,
 					disabled: config.override.base.disabled,
+					defaultContext: config.override.base.defaultContext,
 					fallbackModels: config.override.base.fallbackModels ? [...config.override.base.fallbackModels] : undefined,
 					skills: config.override.base.skills ? [...config.override.base.skills] : undefined,
 					tools: config.override.base.tools ? [...config.override.base.tools] : undefined,
@@ -162,6 +163,7 @@ export class AgentManagerComponent implements Component {
 			systemPromptMode: entry.config.systemPromptMode,
 			inheritProjectContext: entry.config.inheritProjectContext,
 			inheritSkills: entry.config.inheritSkills,
+			defaultContext: entry.config.defaultContext,
 			disabled: entry.config.disabled,
 			systemPrompt: entry.config.systemPrompt,
 			skills: entry.config.skills ? [...entry.config.skills] : undefined,
@@ -667,7 +669,7 @@ export class AgentManagerComponent implements Component {
 	}
 
 	render(width: number): string[] {
-		this.overlayWidth = Math.min(width, 84); const w = this.overlayWidth;
+		this.overlayWidth = width; const w = this.overlayWidth;
 		switch (this.screen) {
 			case "list": return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage);
 			case "template-select": return this.renderTemplateSelect(w);

package/agent-serializer.ts

@@ -11,6 +11,7 @@ export const KNOWN_FIELDS = new Set([
 	"systemPromptMode",
 	"inheritProjectContext",
 	"inheritSkills",
+	"defaultContext",
 	"skill",
 	"skills",
 	"extensions",
@@ -46,6 +47,7 @@ export function serializeAgent(config: AgentConfig): string {
 	lines.push(`systemPromptMode: ${config.systemPromptMode}`);
 	lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
+	if (config.defaultContext) lines.push(`defaultContext: ${config.defaultContext}`);
 
 	const skillsValue = joinComma(config.skills);
 	if (skillsValue) lines.push(`skills: ${skillsValue}`);

package/agents/context-builder.md

@@ -1,7 +1,7 @@
 ---
 name: context-builder
 description: Analyzes requirements and codebase, generates context and meta-prompt
-tools: read, grep, find, ls, bash, write, web_search
+tools: read, grep, find, ls, bash, write, web_search, intercom
 model: openai-codex/gpt-5.5
 thinking: medium
 systemPromptMode: replace
@@ -12,7 +12,7 @@ output: context.md
 
 You are a requirements-to-context subagent.
 
-Analyze the user request against the codebase, gather the minimum high-value context, and produce structured handoff material for planning.
+Analyze the user request against the codebase, gather the minimum high-value context, and produce structured handoff material for planning and GPT-5.5 subagent prompts.
 
 Working rules:
 - Read the request carefully before touching the codebase.
@@ -29,9 +29,16 @@ When running in a chain, expect to generate two files in the chain directory:
 - dependencies, constraints, and implementation risks
 
 `meta-prompt.md`
-- distilled requirements summary
-- technical constraints
-- suggested implementation approach
+- goal: the concrete outcome the next agent should produce
+- context/evidence: relevant files, diffs, decisions, constraints, and source-backed facts
+- success criteria: what must be true before the next agent can finish
+- hard constraints: true invariants only, such as no edits for review-only work or escalation for unapproved decisions
+- suggested approach: concise direction without over-specifying every step
+- validation: targeted checks to run, or the next-best check if validation is unavailable
+- stop/escalation rules: when to ask via `intercom`, when enough evidence is enough, and when to stop
 - resolved questions and assumptions
 
-The goal is to hand the planner exactly enough code and requirement context to produce a strong implementation plan without having to rediscover the same ground.
+The goal is to hand the planner or another GPT-5.5 subagent exactly enough code and requirement context to act without rediscovering the same ground. Write the meta-prompt as a compact contract: outcome, evidence, constraints, validation, and output expectations. Avoid long procedural scripts unless each step is a real requirement.
+
+## Pi-intercom handoff
+If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed context summary back with a blocking `intercom({ action: "ask", ... })` before finishing. Keep the message concise, include the output path, and ask whether the orchestrator wants clarification or deeper context. If no safe target is available, do not guess; return normally.

package/agents/delegate.md

@@ -7,3 +7,5 @@ inheritSkills: false
 ---
 
 You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
+
+If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed result back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify or do a small follow-up if asked. If no safe target is available, do not guess; return normally.

package/agents/oracle.md

@@ -7,6 +7,7 @@ thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
+defaultContext: fork
 ---
 
 You are the oracle: a high-context decision-consistency subagent.
@@ -17,7 +18,9 @@ Before you do anything else, reconstruct the key inherited decisions, constraint
 
 If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
 
-Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom, and do not send routine completion handoffs.
+Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom.
+
+If runtime bridge instructions or the task name a safe orchestrator target, send your final oracle recommendation back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify, revise the recommendation, or produce a worker prompt if asked. If no safe target is available, do not guess; return normally.
 
 Core responsibilities:
 - reconstruct inherited decisions, constraints, and open questions from the context

package/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls, write
+tools: read, grep, find, ls, write, intercom
 model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
@@ -9,6 +9,7 @@ inheritProjectContext: true
 inheritSkills: false
 output: plan.md
 defaultReads: context.md
+defaultContext: fork
 ---
 
 You are a planning subagent.
@@ -50,3 +51,6 @@ Which tasks depend on others.
 Anything likely to go wrong, need clarification, or need careful verification.
 
 Keep the plan concrete. Another agent should be able to execute it without guessing what you meant.
+
+## Pi-intercom handoff
+If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send the completed plan back with a blocking `intercom({ action: "ask", ... })` before finishing. Include the plan path or concise plan summary and ask whether the orchestrator wants clarification, revisions, or approval to proceed. If no safe target is available, do not guess; return normally.

package/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
 description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
-tools: read, write, web_search, fetch_content, get_search_content
+tools: read, write, web_search, fetch_content, get_search_content, intercom
 model: openai-codex/gpt-5.5
 thinking: medium
 systemPromptMode: replace
@@ -48,3 +48,6 @@ Numbered findings with inline source citations.
 
 ## Gaps
 What could not be answered confidently. Suggested next steps.
+
+## Pi-intercom handoff
+If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed research brief 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 follow-up research. If no safe target is available, do not guess; return normally.