pi-subagents 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-04-16
+
+### Added
+- Added `systemPromptMode` so subagents can replace Pi's base prompt with `--system-prompt` instead of always appending with `--append-system-prompt`, shipping the core of issue `#85` from @isvlasov.
+- Added `inheritProjectContext` and `inheritSkills` so child runs can keep or strip inherited project instruction files (`AGENTS.md`, `CLAUDE.md`, etc.) and Pi's discovered skills block.
+
+### Changed
+- Builtin subagents now default to `systemPromptMode: replace`, with builtin `delegate` staying on `append`.
+- Builtin agents now inherit project-level instruction files by default unless the user overrides them.
+- Builtin agent prompts were rewritten for the new prompt-assembly model, and builtin `reviewer` / `context-builder` tool lists now match their documented behaviors. This rounds out the prompt-assembly work merged in PR `#92`, which closed issue `#85`. Thanks @isvlasov.
+
+### Fixed
+- Cross-platform tests now avoid machine-specific Pi install paths, align homedir-sensitive settings discovery on Windows CI, and use deterministic async config-write failure fixtures.
+- Request-level `cwd` handling is now consistent across management and execution paths. `subagent` requests that target a worktree or nested checkout now resolve project agents, project settings, and builtin agent overrides from the requested `cwd` instead of accidentally inheriting the parent session's repo. This fixes issue `#83`. Thanks @hakin19 for the report.
+- Relative child `cwd` values now resolve from the already-selected request/shared `cwd` across sync runs, async/background runs, chain steps, and top-level parallel tasks. This fixes cases where values like `packages/app` were interpreted from the wrong base directory, which could break skill lookup, output paths, and child process spawning.
+- Worktree parallel-mode validation now compares task-level `cwd` overrides after relative-path resolution, so equivalent paths like `.` no longer trigger false conflict errors against the shared worktree base.
+- Internal TypeScript source imports in the touched runtime paths now consistently use `.ts` local specifiers, matching the repo's direct TypeScript runtime loading conventions and reducing drift between adjacent modules.
+
 ## [0.14.1] - 2026-04-14
 
 ### Fixed

package/README.md

@@ -51,10 +51,44 @@ You can also override selected builtin fields without copying the whole agent. B
 - User scope: `~/.pi/agent/settings.json`
 - Project scope: `.pi/settings.json`
 
-Supported builtin override fields are `model`, `fallbackModels`, `thinking`, `skills`, `tools`, and `systemPrompt`. Project overrides beat user overrides. In `/agents`, press `e` on a builtin to create or edit its override. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`.
+Supported builtin override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `skills`, `tools`, and `systemPrompt`. Project overrides beat user overrides.
+
+**Overriding builtin defaults:**
+
+All builtin agents inherit project instruction files (`AGENTS.md`, `CLAUDE.md`, etc.) by default. To make a builtin agent run without those project instructions:
+
+**Via settings file** — add to `~/.pi/agent/settings.json` (user scope) or `.pi/settings.json` (project scope):
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "inheritProjectContext": false
+      }
+    }
+  }
+}
+```
+
+**Via `/agents` UI** — press `e` on any builtin agent (like `reviewer`), then toggle `inheritProjectContext` to `false` and save. This creates an override that you can edit or remove later without modifying the builtin definition itself.
+
+Overridden builtins show badges like `[builtin+user]` or `[builtin+project]` to indicate they have customizations applied.
 
 > **Note:** The `researcher` agent uses `web_search`, `fetch_content`, and `get_search_content` tools which require the [pi-web-access](https://github.com/nicobailon/pi-web-access) extension. Install it with `pi install npm:pi-web-access`.
 
+### Prompt Assembly Philosophy
+
+Subagents are designed to be **narrow and intentional**. Custom subagents default to seeing only what you explicitly give them — not Pi's entire base prompt, not your repo's `AGENTS.md`, and not the parent's discovered skills.
+
+This prevents subtle bugs where a "simple" code review agent starts making decisions based on project architecture rules it shouldn't know about, or a focused research agent gets distracted by tool descriptions meant for the orchestrator.
+
+Use inheritance flags to selectively add back context when you actually want it:
+- **`inheritProjectContext: true`** — Keep Pi's inherited project-instructions block from project-level files like `AGENTS.md` and `CLAUDE.md`
+- **`inheritSkills: true`** — Let the child use Pi's discovered skills catalog
+- **`systemPromptMode: append`** — Add the agent's prompt to Pi's base instead of replacing it
+
+Builtin agents ship a little differently: they all inherit project instruction files by default so they follow repo-specific rules out of the box. `delegate` is still the exception for `systemPromptMode` — it stays on `append` because its job is orchestration within the parent workflow, not isolated task execution.
+
 **Agent frontmatter:**
 
 ```yaml
@@ -66,6 +100,9 @@ extensions:                 # absent=all, empty=none, csv=allowlist
 model: claude-haiku-4-5
 fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4  # optional ordered fallbacks
 thinking: high               # off, minimal, low, medium, high, xhigh
+systemPromptMode: replace    # replace by default, except builtin delegate
+inheritProjectContext: false # custom agents default false; builtins opt into true
+inheritSkills: false         # strip Pi's discovered skills section
 skill: safe-bash, chrome-devtools  # comma-separated skills to inject
 output: context.md           # writes to {chain_dir}/context.md
 defaultReads: context.md     # comma-separated files to read
@@ -81,10 +118,51 @@ The `thinking` field sets a default extended thinking level for the agent. At ru
 
 `fallbackModels` is an optional ordered list of backup models to try when the primary model fails with a provider/model-style error such as quota, auth, timeout, or provider/model unavailable. In markdown frontmatter, declare it as a comma-separated string. In management `config` objects, you can pass either a comma-separated string or a string array.
 
+`systemPromptMode` — How the agent markdown body is passed to Pi:
+- **`replace`** (default) — The agent's markdown body becomes the system prompt. Clean slate, no Pi base prompt baggage.
+- **`append`** — The agent's prompt is appended to Pi's normal base prompt. Use this when you want Pi's full capabilities plus your extra instructions.
+
+`inheritProjectContext` — Whether the child keeps Pi's inherited project-instructions block, built from project-level instruction files like `AGENTS.md` and `CLAUDE.md`:
+- **`false`** (default) — Strip those inherited project-level instructions from the child's final system prompt. This does not remove repo access, cwd, tools, or the task itself; it only removes those inherited instructions.
+- **`true`** — Keep those inherited project-level instructions. Use for specialists that should follow project-specific constraints and conventions.
+
+`inheritSkills` — Whether the child keeps Pi's discovered skills section:
+- **`false`** (default) — Skills catalog is stripped. Good for focused agents that shouldn't browse unrelated skills.
+- **`true`** — Child sees the full skills list. Use for general-purpose assistants that might need varied tools.
+
+The `skills` field still works independently — it injects specific skills directly into the agent prompt regardless of `inheritSkills`.
+
+**Common Recipes**
+
+| Goal | `systemPromptMode` | `inheritProjectContext` | `inheritSkills` |
+|------|-------------------|------------------------|-----------------|
+| Fully isolated specialist (custom-agent default) | `replace` | `false` | `false` |
+| Specialist that should follow project instruction files | `replace` | `true` | `false` |
+| Pi-plus-extensions | `append` | `true` | `true` |
+
+- **Security auditor**: Fully isolated so it objectively checks for vulnerabilities without being biased by project conventions.
+- **Architecture planner**: Repo-aware so it respects `AGENTS.md` constraints when making design decisions.
+- **Generic helper**: Append mode with full inheritance so it behaves like a slightly-customized Pi.
+
 Fallback resolution follows the same conservative model lookup as normal execution. Explicit `provider/model` values are used as-is. Bare model IDs first prefer the current session provider when that provider actually exposes the model, then fall back to a unique registry match. If a bare ID is still ambiguous, it stays bare.
 
 Fallback is only used for provider/model availability failures. Ordinary task failures such as bad `bash` commands, missing files, or other tool/runtime errors do not trigger a model hop.
 
+**Tool selection semantics**
+
+The `tools` field controls builtin-tool allowlisting and a couple of related extension behaviors:
+
+- `tools` **omitted** → `pi-subagents` does not pass `--tools`, so the child gets Pi's normal default builtin tools.
+- `tools` **present** → listed builtin tool names become an explicit allowlist passed via `--tools`.
+- `mcp:...` entries are split out of `tools` and forwarded as direct MCP tool selections.
+- Path-like entries in `tools` (extension paths or file paths ending in `.ts` / `.js`) are treated as tool-extension paths, not builtin tool names.
+
+This means:
+
+- `tools` omitted + `extensions` omitted → child gets Pi's normal builtin tools and normal extension set.
+- `tools: mcp:chrome-devtools` → child still gets Pi's default builtin tools, plus direct MCP tools from `chrome-devtools`.
+- `tools: read, bash, mcp:chrome-devtools` → child is restricted to `read` and `bash` for builtin tools, plus direct MCP tools from `chrome-devtools`.
+
 **Extension sandboxing**
 
 Use `extensions` in frontmatter to control which extensions a subagent can access:
@@ -229,7 +307,7 @@ Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay —
 |--------|-------------|
 | List | Browse all agents and chains with search/filter, scope badges, chain badges |
 | Detail | View resolved prompt, frontmatter fields, recent run history, and active builtin override path |
-| Edit | Edit fields with specialized pickers (model, thinking, skills, prompt editor) |
+| Edit | Edit fields with specialized pickers and toggles (model, thinking, prompt mode, inherited context, inherited skills, prompt editor) |
 | Chain Detail | View chain steps with flow visualization and dependency map |
 | Parallel Builder | Build parallel execution slots, add same agent multiple times, per-slot task overrides |
 | Task Input | Enter task and launch with optional skip-clarify toggle |
@@ -573,6 +651,9 @@ Agent definitions are not loaded into LLM context by default. Management actions
   description: "Scans codebases for patterns and issues",
   scope: "user",
   systemPrompt: "You are a code scout...",
+  systemPromptMode: "replace",
+  inheritProjectContext: false,
+  inheritSkills: false,
   model: "anthropic/claude-sonnet-4",
   fallbackModels: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"],
   tools: "read, bash, mcp:github/search_repositories",
@@ -613,7 +694,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
 Notes:
 - `create` uses `config.scope` (`"user"` or `"project"`), not `agentScope`.
 - `update`/`delete` use `agentScope` only for scope disambiguation when the same name exists in both scopes.
-- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, `maxSubagentDepth` maps directly to agent frontmatter, `fallbackModels` maps directly to agent frontmatter, and `tools` supports `mcp:` entries that map to direct MCP tools.
+- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, `maxSubagentDepth`, `fallbackModels`, `systemPromptMode`, `inheritProjectContext`, and `inheritSkills` map directly to agent frontmatter, and `tools` supports `mcp:` entries that map to direct MCP tools.
 - To clear any optional field, set it to `false` or `""` (e.g., `{ model: false }` or `{ skills: "" }`). Both work for all string-typed fields.
 
 ## Parameters
@@ -624,7 +705,7 @@ Notes:
 | `task` | string | - | Task string (single mode) |
 | `action` | string | - | Management action: `list`, `get`, `create`, `update`, `delete` |
 | `chainName` | string | - | Chain name for management get/update/delete |
-| `config` | object | - | Agent or chain config for management create/update. Agent configs also accept `fallbackModels` (comma-separated string or string array). |
+| `config` | object | - | Agent or chain config for management create/update. Agent configs also accept `fallbackModels` (comma-separated string or string array), `systemPromptMode` (`append` or `replace`), `inheritProjectContext` (boolean), and `inheritSkills` (boolean). |
 | `output` | `string \| false` | agent default | Override output file for single agent (absolute path as-is, relative path resolved against cwd) |
 | `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
 | `model` | string | agent default | Override model for single agent |

package/agent-management.ts

@@ -8,6 +8,9 @@ import {
 	type AgentSource,
 	type ChainConfig,
 	type ChainStepConfig,
+	defaultInheritProjectContext,
+	defaultInheritSkills,
+	defaultSystemPromptMode,
 	discoverAgentsAll,
 } from "./agents.ts";
 import { serializeAgent } from "./agent-serializer.ts";
@@ -244,6 +247,18 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.thinking === "string") target.thinking = cfg.thinking.trim() || undefined;
 		else return "config.thinking must be a string or false when provided.";
 	}
+	if (hasKey(cfg, "systemPromptMode")) {
+		if (cfg.systemPromptMode === "append" || cfg.systemPromptMode === "replace") target.systemPromptMode = cfg.systemPromptMode;
+		else return "config.systemPromptMode must be 'append' or 'replace' when provided.";
+	}
+	if (hasKey(cfg, "inheritProjectContext")) {
+		if (typeof cfg.inheritProjectContext !== "boolean") return "config.inheritProjectContext must be a boolean when provided.";
+		target.inheritProjectContext = cfg.inheritProjectContext;
+	}
+	if (hasKey(cfg, "inheritSkills")) {
+		if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
+		target.inheritSkills = cfg.inheritSkills;
+	}
 	if (hasKey(cfg, "output")) {
 		if (cfg.output === false || cfg.output === "") target.output = undefined;
 		else if (typeof cfg.output === "string") target.output = cfg.output;
@@ -320,6 +335,9 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
 	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
 	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
+	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.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
@@ -418,7 +436,16 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 		warnings.push(...chainStepWarnings(ctx, chain.steps));
 		return result([`Created chain '${name}' at ${targetPath}.`, ...warnings].join("\n"));
 	}
-	const agent: AgentConfig = { name, description: cfg.description.trim(), source: scope, filePath: targetPath, systemPrompt: "" };
+	const agent: AgentConfig = {
+		name,
+		description: cfg.description.trim(),
+		source: scope,
+		filePath: targetPath,
+		systemPrompt: "",
+		systemPromptMode: defaultSystemPromptMode(name),
+		inheritProjectContext: defaultInheritProjectContext(name),
+		inheritSkills: defaultInheritSkills(),
+	};
 	const applyError = applyAgentConfig(agent, cfg);
 	if (applyError) return result(applyError, true);
 	const mw = modelWarning(ctx, agent.model);
@@ -446,7 +473,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		const target = targetOrError;
 		const updated: AgentConfig = { ...target };
 		const oldName = target.name;
-		// Validate all fields before any filesystem mutation
 		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
 		let newName: string | undefined;
@@ -456,7 +482,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		}
 		const applyError = applyAgentConfig(updated, cfg);
 		if (applyError) return result(applyError, true);
-		// Apply name/description (validated above)
 		if (newName !== undefined) updated.name = newName;
 		if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 		if (hasKey(cfg, "model")) {
@@ -471,7 +496,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 			const sw = skillsWarning(ctx.cwd, updated.skills);
 			if (sw) warnings.push(sw);
 		}
-		// Filesystem mutations last
 		if (updated.name !== oldName) {
 			const renamed = renamePath("agent", target.filePath, updated.name, target.source, ctx.cwd);
 			if (renamed.error) return result(renamed.error, true);
@@ -493,7 +517,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 	const target = targetOrError;
 	const updated: ChainConfig = { ...target, steps: [...target.steps] };
 	const oldName = target.name;
-	// Validate all fields before any filesystem mutation
 	if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 	if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
 	let newName: string | undefined;
@@ -507,7 +530,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (parsed.error) return result(parsed.error, true);
 		parsedSteps = parsed.steps!;
 	}
-	// Apply validated changes to in-memory object
 	if (newName !== undefined) updated.name = newName;
 	if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 	if (parsedSteps) {
@@ -516,7 +538,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (missing.length) warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
 		warnings.push(...chainStepWarnings(ctx, updated.steps));
 	}
-	// Filesystem mutations last
 	if (updated.name !== oldName) {
 		const renamed = renamePath("chain", target.filePath, updated.name, target.source, ctx.cwd);
 		if (renamed.error) return result(renamed.error, true);

package/agent-manager-detail.ts

@@ -27,7 +27,7 @@ function renderFieldLine(
 	width: number,
 	theme: Theme,
 ): string {
-	const labelWidth = 10;
+	const labelWidth = 12;
 	const labelText = theme.fg("dim", pad(label, labelWidth));
 	const available = Math.max(0, width - labelWidth);
 	return `${labelText}${truncateToWidth(value, available)}`;
@@ -61,6 +61,9 @@ function buildDetailLines(
 	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));
 	if (agent.override) {
 		const overrideLabel = `${agent.override.scope} · ${formatPath(agent.override.path)}`;
 		lines.push(renderFieldLine("Override:", overrideLabel, 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 type { AgentConfig, BuiltinAgentOverrideBase } from "./agents.ts";
+import { defaultSystemPromptMode, type AgentConfig, 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";
@@ -26,7 +26,7 @@ export interface CreateEditStateOptions {
 }
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
+const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "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;
@@ -45,6 +45,9 @@ function fieldValueMatchesBase(field: EditField, state: EditState): boolean {
 		case "model": return state.draft.model === base.model;
 		case "fallbackModels": return arraysEqual(state.draft.fallbackModels, base.fallbackModels);
 		case "thinking": return state.draft.thinking === base.thinking;
+		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 "tools": return arraysEqual(toolList(state.draft), toolList(base));
 		case "skills": return arraysEqual(state.draft.skills, base.skills);
 		case "prompt": return state.draft.systemPrompt === base.systemPrompt;
@@ -59,6 +62,9 @@ function resetFieldToBase(field: EditField, state: EditState): void {
 		case "model": state.draft.model = base.model; break;
 		case "fallbackModels": state.draft.fallbackModels = base.fallbackModels ? [...base.fallbackModels] : undefined; break;
 		case "thinking": state.draft.thinking = base.thinking; break;
+		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 "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;
 		case "prompt": state.draft.systemPrompt = base.systemPrompt; state.promptEditor = createEditorState(base.systemPrompt); break;
@@ -83,6 +89,9 @@ function renderFieldValue(field: EditField, state: EditState): string {
 		case "model": return draft.model ?? "default";
 		case "fallbackModels": return draft.fallbackModels && draft.fallbackModels.length > 0 ? draft.fallbackModels.join(", ") : "";
 		case "thinking": return draft.thinking ?? "off";
+		case "systemPromptMode": return draft.systemPromptMode ?? defaultSystemPromptMode(draft.name);
+		case "inheritProjectContext": return draft.inheritProjectContext ? "on" : "off";
+		case "inheritSkills": return draft.inheritSkills ? "on" : "off";
 		case "tools": return formatTools(draft);
 		case "extensions": return draft.extensions !== undefined ? (draft.extensions.length > 0 ? draft.extensions.join(", ") : "") : "(all)";
 		case "skills": return draft.skills && draft.skills.length > 0 ? draft.skills.join(", ") : "";
@@ -101,12 +110,28 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 		case "description": draft.description = value.trim(); break;
 		case "model": draft.model = value.trim() || undefined; break;
 		case "fallbackModels": draft.fallbackModels = parseCommaList(value); break;
+		case "systemPromptMode": {
+			const trimmed = value.trim();
+			if (trimmed === "") {
+				draft.systemPromptMode = defaultSystemPromptMode(draft.name);
+				break;
+			}
+			if (trimmed === "append" || trimmed === "replace") {
+				draft.systemPromptMode = trimmed;
+			}
+			break;
+		}
 		case "tools": { const parsed = parseTools(value); draft.tools = parsed.tools; draft.mcpDirectTools = parsed.mcp; break; }
 		case "extensions": { const trimmed = value.trim(); draft.extensions = trimmed === "(all)" ? undefined : parseCommaList(trimmed) ?? []; break; }
 		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 "progress": case "interactive": case "prompt": break;
+		case "inheritProjectContext":
+		case "inheritSkills":
+		case "progress":
+		case "interactive":
+		case "prompt":
+			break;
 	}
 }
 
@@ -231,13 +256,19 @@ 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 === "progress" || field === "interactive")) { if (field === "progress") state.draft.defaultProgress = !state.draft.defaultProgress; if (field === "interactive") state.draft.interactive = !state.draft.interactive; return; }
+		if (data === " " && (field === "inheritProjectContext" || field === "inheritSkills" || field === "progress" || field === "interactive")) {
+			if (field === "inheritProjectContext") state.draft.inheritProjectContext = !state.draft.inheritProjectContext;
+			if (field === "inheritSkills") state.draft.inheritSkills = !state.draft.inheritSkills;
+			if (field === "progress") state.draft.defaultProgress = !state.draft.defaultProgress;
+			if (field === "interactive") state.draft.interactive = !state.draft.interactive;
+			return;
+		}
 		if (matchesKey(data, "return")) {
 			if (field === "model") { openModelPicker(state, models); return { nextScreen: "edit-field" }; }
 			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 === "progress" || field === "interactive") return;
+			if (field === "inheritProjectContext" || field === "inheritSkills" || field === "progress" || field === "interactive") return;
 			state.fieldMode = "text"; state.fieldEditor = createEditorState(renderFieldValue(field, state)); return { nextScreen: "edit-field" };
 		}
 		return;
@@ -304,8 +335,17 @@ export function renderEdit(screen: EditScreen, state: EditState, width: number,
 	for (let i = 0; i < state.fields.length; i++) {
 		const field = state.fields[i]!; if (field === "prompt") break;
 		const isFocused = i === state.fieldIndex; const prefix = isFocused ? theme.fg("accent", "▸ ") : "  ";
-		const rawLabel = pad(`${field[0]!.toUpperCase()}${field.slice(1)}:`, labelWidth);
+		const fieldLabel = field === "systemPromptMode"
+			? "Prompt Mode"
+			: field === "inheritProjectContext"
+				? "Project Ctx"
+				: field === "inheritSkills"
+					? "Skills Ctx"
+					: `${field[0]!.toUpperCase()}${field.slice(1)}`;
+		const rawLabel = pad(`${fieldLabel}:`, labelWidth);
 		const labelText = state.overrideBase && !fieldValueMatchesBase(field, state) ? theme.fg("accent", rawLabel) : rawLabel; let valueText = renderFieldValue(field, state);
+		if (field === "inheritProjectContext") { const toggle = state.draft.inheritProjectContext ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.inheritProjectContext ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
+		if (field === "inheritSkills") { const toggle = state.draft.inheritSkills ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.inheritSkills ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		if (field === "progress") { const toggle = state.draft.defaultProgress ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.defaultProgress ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		if (field === "interactive") { const toggle = state.draft.interactive ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.interactive ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		let displayValue = truncateToWidth(valueText, valueWidth);

package/agent-manager.ts

@@ -5,6 +5,9 @@ import type { Component, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import {
 	buildBuiltinOverrideConfig,
+	defaultInheritProjectContext,
+	defaultInheritSkills,
+	defaultSystemPromptMode,
 	discoverAgentsAll,
 	removeBuiltinAgentOverride,
 	saveBuiltinAgentOverride,
@@ -40,7 +43,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", "tools", "skills", "prompt"];
+const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "tools", "skills", "prompt"];
 
 function cloneConfig(config: AgentConfig): AgentConfig {
 	return {
@@ -130,6 +133,9 @@ export class AgentManagerComponent implements Component {
 			model: entry.config.model,
 			fallbackModels: entry.config.fallbackModels ? [...entry.config.fallbackModels] : undefined,
 			thinking: entry.config.thinking,
+			systemPromptMode: entry.config.systemPromptMode,
+			inheritProjectContext: entry.config.inheritProjectContext,
+			inheritSkills: entry.config.inheritSkills,
 			systemPrompt: entry.config.systemPrompt,
 			skills: entry.config.skills ? [...entry.config.skills] : undefined,
 			tools: entry.config.tools ? [...entry.config.tools] : undefined,
@@ -233,6 +239,16 @@ export class AgentManagerComponent implements Component {
 			filePath = path.join(dir, `${edit.draft.name}.md`);
 			if (fs.existsSync(filePath)) { edit.error = "An agent with that name already exists."; return false; }
 			fs.mkdirSync(dir, { recursive: true });
+		} else if (edit.draft.name !== entry.config.name) {
+			const nextPath = path.join(path.dirname(filePath), `${edit.draft.name}.md`);
+			if (nextPath !== filePath && fs.existsSync(nextPath)) {
+				edit.error = "An agent with that name already exists.";
+				return false;
+			}
+			if (nextPath !== filePath) {
+				fs.renameSync(filePath, nextPath);
+				filePath = nextPath;
+			}
 		}
 		try { const toSave: AgentConfig = { ...edit.draft, filePath }; fs.writeFileSync(filePath, serializeAgent(toSave), "utf-8"); entry.config = cloneConfig(toSave); entry.isNew = false; edit.error = undefined; return true; }
 		catch (err) { edit.error = err instanceof Error ? err.message : "Failed to save agent."; return false; }
@@ -349,7 +365,17 @@ export class AgentManagerComponent implements Component {
 			baseConfig = cloneConfig(sourceEntry.config);
 		} else {
 			const templateConfig = state.template?.config ?? {};
-			baseConfig = { name, description: "Describe this agent", systemPrompt: "", source: state.scope, filePath: "", ...templateConfig };
+			baseConfig = {
+				name,
+				description: "Describe this agent",
+				systemPrompt: "",
+				systemPromptMode: defaultSystemPromptMode(name),
+				inheritProjectContext: defaultInheritProjectContext(name),
+				inheritSkills: defaultInheritSkills(),
+				source: state.scope,
+				filePath: "",
+				...templateConfig,
+			};
 		}
 		const dir = state.scope === "project" ? this.agentData.projectDir : this.agentData.userDir;
 		if (!dir) { state.error = "Project agents directory not found."; this.tui.requestRender(); return; }

package/agent-serializer.ts

@@ -8,6 +8,9 @@ export const KNOWN_FIELDS = new Set([
 	"model",
 	"fallbackModels",
 	"thinking",
+	"systemPromptMode",
+	"inheritProjectContext",
+	"inheritSkills",
 	"skill",
 	"skills",
 	"extensions",
@@ -40,6 +43,9 @@ export function serializeAgent(config: AgentConfig): string {
 	const fallbackModelsValue = joinComma(config.fallbackModels);
 	if (fallbackModelsValue) lines.push(`fallbackModels: ${fallbackModelsValue}`);
 	if (config.thinking && config.thinking !== "off") lines.push(`thinking: ${config.thinking}`);
+	lines.push(`systemPromptMode: ${config.systemPromptMode}`);
+	lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
+	lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
 
 	const skillsValue = joinComma(config.skills);
 	if (skillsValue) lines.push(`skills: ${skillsValue}`);

package/agents/context-builder.md

@@ -1,38 +1,36 @@
 ---
 name: context-builder
 description: Analyzes requirements and codebase, generates context and meta-prompt
-tools: read, grep, find, ls, bash, web_search
+tools: read, grep, find, ls, bash, write, web_search
 model: claude-sonnet-4-6
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
 output: context.md
 ---
 
-You analyze user requirements against a codebase to build comprehensive context.
+You are a requirements-to-context subagent.
 
-Given a user request (prose, user stories, requirements), you will:
+Analyze the user request against the codebase, gather the minimum high-value context, and produce structured handoff material for planning.
 
-1. **Analyze the request** - Understand what the user wants to build
-2. **Search the codebase** - Find all relevant files, patterns, dependencies
-3. **Research if needed** - Look up APIs, libraries, best practices online
-4. **Generate output files** - You'll receive instructions about where to write
+Working rules:
+- Read the request carefully before touching the codebase.
+- Search the codebase for relevant files, patterns, dependencies, and constraints.
+- Use `web_search` only when the task depends on external APIs, libraries, or current best practices.
+- Write the requested output files clearly and concretely.
+- Prefer distilled, high-signal context over exhaustive dumps.
 
-When running in a chain, generate two files in the specified chain directory:
+When running in a chain, expect to generate two files in the chain directory:
 
-**context.md** - Code context:
-# Code Context
-## Relevant Files
-[files with line numbers and snippets]
-## Patterns Found
-[existing patterns to follow]
-## Dependencies
-[libraries, APIs involved]
+`context.md`
+- relevant files with line numbers and key snippets
+- important patterns already used in the codebase
+- dependencies, constraints, and implementation risks
 
-**meta-prompt.md** - Optimized instructions for planner:
-# Meta-Prompt for Planning
-## Requirements Summary
-[distilled requirements]
-## Technical Constraints
-[must-haves, limitations]
-## Suggested Approach
-[recommended implementation strategy]
-## Questions Resolved
-[decisions made during analysis]
+`meta-prompt.md`
+- distilled requirements summary
+- technical constraints
+- suggested implementation approach
+- 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.

package/agents/delegate.md

@@ -1,6 +1,9 @@
 ---
 name: delegate
 description: Lightweight subagent that inherits the parent model with no default reads
+systemPromptMode: append
+inheritProjectContext: true
+inheritSkills: false
 ---
 
-You are a delegated agent. Execute the assigned task using your tools. Be direct and efficient.
+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.

package/agents/planner.md

@@ -4,43 +4,49 @@ description: Creates implementation plans from context and requirements
 tools: read, grep, find, ls, write
 model: claude-opus-4-6
 thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
 output: plan.md
 defaultReads: context.md
 ---
 
-You are a planning specialist. You receive context and requirements, then produce a clear implementation plan.
+You are a planning subagent.
 
-You must NOT make any changes. Only read, analyze, and plan.
+Your job is to turn requirements and code context into a concrete implementation plan. Do not make code changes. Read, analyze, and write the plan only.
 
-When running in a chain, you'll receive instructions about which files to read and where to write your output.
+Working rules:
+- Read the provided context before planning.
+- Read any additional code you need in order to make the plan concrete.
+- Name exact files whenever you can.
+- Prefer small, ordered, actionable tasks over vague phases.
+- Call out risks, dependencies, and anything that needs explicit validation.
+- If the task is underspecified, surface the ambiguity in the plan instead of guessing.
 
-Output format (plan.md):
+Output format (`plan.md`):
 
 # Implementation Plan
 
 ## Goal
-One sentence summary of what needs to be done.
+One sentence summary of the outcome.
 
 ## Tasks
-Numbered steps, each small and actionable:
+Numbered steps, each small and actionable.
 1. **Task 1**: Description
    - File: `path/to/file.ts`
-   - Changes: What to modify
-   - Acceptance: How to verify
-
-2. **Task 2**: Description
-   ...
+   - Changes: what to modify
+   - Acceptance: how to verify
 
 ## Files to Modify
-- `path/to/file.ts` - what changes
+- `path/to/file.ts` - what changes there
 
-## New Files (if any)
+## New Files
 - `path/to/new.ts` - purpose
 
 ## Dependencies
 Which tasks depend on others.
 
 ## Risks
-Anything to watch out for.
+Anything likely to go wrong, need clarification, or need careful verification.
 
-Keep the plan concrete. The worker agent will execute it.
+Keep the plan concrete. Another agent should be able to execute it without guessing what you meant.