pi-subagents 0.20.1 → 0.21.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.21.1] - 2026-04-30
+
+### Changed
+- Changed the `/agents` new-agent shortcut from `Alt+N` to `Shift+Ctrl+N`, and added `agentManager.newShortcut` config for overriding it.
+
+### Fixed
+- Fall back to polling async result files when native result watching is unavailable due to `EMFILE` or `ENOSPC`.
+- Treat forced final-drain termination after a valid final assistant output as cleanup success instead of failing the subagent run.
+- Hide disabled builtin agents from `subagent({ action: "list" })` output so agent-facing choices match executable runtime discovery.
+- Resolve intercom bridge default paths at runtime so tests and isolated environments that change `HOME` use the correct `pi-intercom` location.
+- Made the tool-description source check tolerant of Windows line endings.
+
+## [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

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
 
@@ -359,7 +374,7 @@ Useful keys:
 
 - type to search the list
 - `Enter` opens detail screens
-- `Alt+N` creates an agent or chain from a template
+- `Shift+Ctrl+N` creates an agent or chain from a template
 - `Ctrl+R` launches selected agents as a run or chain
 - `Ctrl+P` opens the parallel builder
 - `Tab` selects agents in the list or toggles skip-clarify in task input
@@ -413,11 +428,11 @@ 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.
 
-Set `disabled: true` to hide a builtin from runtime discovery while keeping it visible in `/agents`. For bulk control, set `subagents.disableBuiltins: true` in settings. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`; disabled builtins show `off` badges in the manager.
+Set `disabled: true` to hide a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output while keeping it visible in `/agents`. For bulk control, set `subagents.disableBuiltins: true` in settings. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`; disabled builtins show `off` badges in the manager.
 
 ### Prompt assembly
 
@@ -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`.
 
@@ -816,6 +833,18 @@ Session directory precedence is: `params.sessionDir`, then `config.defaultSessio
 
 Controls nested delegation when no inherited `PI_SUBAGENT_MAX_DEPTH` is already in effect. Per-agent `maxSubagentDepth` can tighten the limit for that agent’s child runs, but cannot relax an inherited stricter limit.
 
+### `agentManager.newShortcut`
+
+```json
+{
+  "agentManager": {
+    "newShortcut": "shift+ctrl+n"
+  }
+}
+```
+
+Sets the `/agents` list shortcut for opening the new agent/chain template picker. The default is `shift+ctrl+n`; use Pi key names such as `ctrl+n` if your terminal cannot distinguish Shift for control chords.
+
 ### `intercomBridge`
 
 ```json

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]!;
@@ -372,12 +378,12 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const d = discoverAgentsAll(ctx.cwd);
 	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
-	const disabledBuiltins = scopedAgents.filter((a) => a.source === "builtin" && a.disabled);
 	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)"]),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
@@ -385,7 +391,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 +566,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-list.ts

@@ -22,6 +22,12 @@ export interface ListState {
 	selected: string[];
 }
 
+export interface ListShortcuts {
+	newShortcut: string;
+}
+
+export const DEFAULT_AGENT_MANAGER_NEW_SHORTCUT = "shift+ctrl+n";
+
 export type ListAction =
 	| { type: "open-detail"; id: string }
 	| { type: "clone"; id: string }
@@ -57,7 +63,7 @@ function clampCursor(state: ListState, filtered: ListAgent[]): void {
 	}
 }
 
-export function handleListInput(state: ListState, agents: ListAgent[], data: string): ListAction | undefined {
+export function handleListInput(state: ListState, agents: ListAgent[], data: string, shortcuts: ListShortcuts = { newShortcut: DEFAULT_AGENT_MANAGER_NEW_SHORTCUT }): ListAction | undefined {
 	const filtered = fuzzyFilter(agents, state.filterQuery);
 
 	if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
@@ -98,7 +104,7 @@ export function handleListInput(state: ListState, agents: ListAgent[], data: str
 		return;
 	}
 
-	if (matchesKey(data, "alt+n")) {
+	if (matchesKey(data, shortcuts.newShortcut)) {
 		return { type: "new" };
 	}
 
@@ -160,6 +166,7 @@ export function renderList(
 	width: number,
 	theme: Theme,
 	statusMessage?: { text: string; type: "error" | "info" },
+	shortcuts: ListShortcuts = { newShortcut: DEFAULT_AGENT_MANAGER_NEW_SHORTCUT },
 ): string[] {
 	const lines: string[] = [];
 	const filtered = fuzzyFilter(agents, state.filterQuery);
@@ -269,7 +276,7 @@ export function renderList(
 		? ` [ctrl+r] chain  [ctrl+p] parallel  [tab] add  [shift+tab] remove  [esc] clear (${selCount}) `
 		: selCount === 1
 			? " [ctrl+r] run  [ctrl+p] parallel  [tab] add more  [shift+tab] remove  [esc] clear "
-			: " [enter] view  [ctrl+r] run  [tab] select  [alt+n] new  [esc] close ";
+			: ` [enter] view  [ctrl+r] run  [tab] select  [${shortcuts.newShortcut}] new  [esc] close `;
 	lines.push(renderFooter(footerText, width, theme));
 
 	return lines;

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

@@ -18,7 +18,7 @@ import {
 import { serializeAgent } from "./agent-serializer.ts";
 import { TEMPLATE_ITEMS, type AgentTemplate, type TemplateItem } from "./agent-templates.ts";
 import { parseChain, serializeChain } from "./chain-serializer.ts";
-import { renderList, handleListInput, type ListAgent, type ListState, type ListAction } from "./agent-manager-list.ts";
+import { DEFAULT_AGENT_MANAGER_NEW_SHORTCUT, renderList, handleListInput, type ListAgent, type ListShortcuts, type ListState, type ListAction } from "./agent-manager-list.ts";
 import { createParallelState, handleParallelInput, renderParallel, formatParallelTitle, type ParallelState, type AgentOption } from "./agent-manager-parallel.ts";
 import { renderDetail, handleDetailInput, renderTaskInput, type DetailState, type DetailAction, type LaunchToggleState } from "./agent-manager-detail.ts";
 import { renderChainDetail, handleChainDetailInput, type ChainDetailAction, type ChainDetailState } from "./agent-manager-chain-detail.ts";
@@ -43,8 +43,9 @@ interface ChainEntry { id: string; kind: "chain"; config: ChainConfig; }
 interface NameInputState { mode: "new-agent" | "clone-agent" | "clone-chain" | "new-chain"; editor: TextEditorState; scope: "user" | "project"; allowProject: boolean; sourceId?: string; template?: AgentTemplate; error?: string; }
 interface StatusMessage { text: string; type: "error" | "info"; }
 interface OverrideScopeState { selectedScope: "user" | "project"; allowProject: boolean; }
+export interface AgentManagerOptions { newShortcut?: string; }
 
-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 +62,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,
@@ -130,14 +132,16 @@ export class AgentManagerComponent implements Component {
 	private models: ModelInfo[];
 	private skills: SkillInfo[];
 	private done: (result: ManagerResult) => void;
+	private shortcuts: ListShortcuts;
 
-	constructor(tui: TUI, theme: Theme, agentData: AgentData, models: ModelInfo[], skills: SkillInfo[], done: (result: ManagerResult) => void) {
+	constructor(tui: TUI, theme: Theme, agentData: AgentData, models: ModelInfo[], skills: SkillInfo[], done: (result: ManagerResult) => void, options: AgentManagerOptions = {}) {
 		this.tui = tui;
 		this.theme = theme;
 		this.agentData = agentData;
 		this.models = models;
 		this.skills = skills;
 		this.done = done;
+		this.shortcuts = { newShortcut: options.newShortcut?.trim() || DEFAULT_AGENT_MANAGER_NEW_SHORTCUT };
 		this.loadEntries();
 	}
 
@@ -162,6 +166,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,
@@ -516,7 +521,7 @@ export class AgentManagerComponent implements Component {
 		if (this.screen === "list" && this.statusMessage) this.clearStatus();
 		if (this.screen.startsWith("edit") && this.editState?.error) this.editState.error = undefined;
 		switch (this.screen) {
-			case "list": { const action = handleListInput(this.listState, this.listAgents(), data); if (action) this.handleListAction(action); this.tui.requestRender(); return; }
+			case "list": { const action = handleListInput(this.listState, this.listAgents(), data, this.shortcuts); if (action) this.handleListAction(action); this.tui.requestRender(); return; }
 			case "template-select": this.handleTemplateSelectInput(data); return;
 			case "override-scope": this.handleOverrideScopeInput(data); return;
 			case "detail": {
@@ -667,16 +672,16 @@ 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 "list": return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts);
 			case "template-select": return this.renderTemplateSelect(w);
 			case "override-scope": return this.renderOverrideScope(w);
-			case "detail": { const entry = this.getAgentEntry(this.currentAgentId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage); return renderDetail(this.detailState, entry.config, this.agentData.cwd, w, this.theme); }
-			case "chain-detail": { const entry = this.getChainEntry(this.currentChainId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage); return renderChainDetail(this.chainDetailState, entry.config, w, this.theme); }
+			case "detail": { const entry = this.getAgentEntry(this.currentAgentId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts); return renderDetail(this.detailState, entry.config, this.agentData.cwd, w, this.theme); }
+			case "chain-detail": { const entry = this.getChainEntry(this.currentChainId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts); return renderChainDetail(this.chainDetailState, entry.config, w, this.theme); }
 			case "edit": case "edit-field": case "edit-prompt": return this.editState ? renderEdit(this.screen as EditScreen, this.editState, w, this.theme) : [];
 			case "parallel-builder": {
-				if (!this.parallelState) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage);
+				if (!this.parallelState) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts);
 				const agentOptions: AgentOption[] = this.agents.map((e) => ({ name: e.config.name, description: e.config.description, model: e.config.model }));
 				return renderParallel(this.parallelState, agentOptions, w, this.theme);
 			}

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