pi-subagents 0.13.4 → 0.14.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-04-14
+
+### Fixed
+- Completed foreground subagent results now return compact payloads instead of inlining full raw message histories and per-result progress objects, preventing long tool-heavy sync runs from overwhelming the parent agent return path.
+- Prompt-template delegation now rebuilds minimal assistant messages from compact foreground results when raw message arrays are intentionally omitted.
+- UI/status wording now uses plain text labels instead of glyph-heavy markers across foreground rendering, parallel summaries, save-result receipts, installer output, agent manager views, clarify screens, and the corresponding README/CHANGELOG examples.
+- Added a realistic foreground integration repro for issue `#80` and cleaned up the touched tests to remove the remaining blunt `as any` fixture casts.
+
+## [0.14.0] - 2026-04-14
+
+### Added
+- Builtin agents can now be customized through settings-backed field overrides in `~/.pi/agent/settings.json` and `.pi/settings.json` under `subagents.agentOverrides`, with `/agents` exposing a create/edit override flow instead of forcing full-file copies for model/thinking/tool/prompt tweaks.
+
+### Fixed
+- Shared temp paths are now scoped under a user-specific temp root across async result storage, async run state, chain directories, artifact fallback storage, and detached async config files, avoiding cross-user collisions on shared machines while still handling arbitrary-UID/container environments where `os.userInfo()` can throw.
+- Async/background runs now launch child `pi` processes in JSON mode, stream child events into `events.jsonl` with step metadata while the run is active, keep `output-<n>.log` live with human-readable child output, and document that `subagent-log-<id>.md` is a completion artifact.
+- Bare model IDs now prefer the active parent-session provider when that provider actually exposes the model, across sync, chain, parallel, async, and clarify flows. Ambiguous bare IDs still fall back to conservative resolution.
+- Skill resolution now includes local package roots declared in project/user `settings.json -> packages`, checks the effective task `cwd` before the runtime cwd, and still falls back to the runtime cwd when a nested task inherits package-provided skills from the repo root.
+
 ## [0.13.4] - 2026-04-13
 
 ### Fixed
@@ -485,7 +504,7 @@
   - Pre-selects current thinking level if already set
 - **Model selector in chain TUI** - Press `[m]` to select a different model for any step
   - Fuzzy search through all available models
-  - Shows current model with ✓ indicator
+  - Shows the current model with a `current` badge
   - Provider/model format (e.g., `anthropic/claude-haiku-4-5`)
   - Override indicator (✎) when model differs from agent default
 - **Model visibility in chain execution** - Shows which model each step is using
@@ -523,8 +542,8 @@
 
 ### Improved
 - **Per-step progress indicators** - When progress is enabled, each step shows its role:
-  - Step 1: `● creates & updates progress.md`
-  - Step 2+: `↔ reads & updates progress.md`
+  - Step 1: `writes progress.md`
+  - Step 2+: `reads progress.md`
   - Clear visualization of progress.md data flow through the chain
 - **Comprehensive tool descriptions** - Better documentation of chain variables:
   - Tool description now explains `{task}`, `{previous}`, `{chain_dir}` in detail
@@ -580,7 +599,7 @@
 ### Improved
 - **Tool description now explicitly shows the three modes** (SINGLE, CHAIN, PARALLEL) with syntax - helps agents pick the right mode when user says "scout → planner"
 - **Chain execution observability** - Now shows:
-  - Chain visualization with status icons: `✓scout → ●planner` (✓=done, ●=running, ○=pending, ✗=failed) - sequential chains only
+  - Chain visualization with status labels: `done scout → running planner` (`done`, `running`, `pending`, `failed`) - sequential chains only
   - Accurate step counter: "step 1/2" instead of misleading "1/1"
   - Current tool and recent output for running step
 

package/README.md

@@ -44,7 +44,14 @@ Agents are markdown files with YAML frontmatter that define specialized subagent
 
 Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
-**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, and `delegate`. They load at lowest priority so any user or project agent with the same name overrides them. Builtin agents appear with a `[builtin]` badge in listings and cannot be modified through management actions (create a same-named user agent to override instead).
+**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, and `delegate`. They load at lowest priority so any user or project agent with the same name overrides them.
+
+You can also override selected builtin fields without copying the whole agent. Builtin overrides are stored in settings under `subagents.agentOverrides`:
+
+- 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]`.
 
 > **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`.
 
@@ -74,7 +81,7 @@ 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.
 
-Fallback resolution follows the same conservative model lookup as normal execution. Explicit `provider/model` values are used as-is. Bare model IDs are only upgraded to a full `provider/model` when they map cleanly to a single registry entry. If a bare ID is ambiguous, it stays bare.
+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.
 
@@ -221,7 +228,7 @@ Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay —
 | Screen | Description |
 |--------|-------------|
 | List | Browse all agents and chains with search/filter, scope badges, chain badges |
-| Detail | View resolved prompt, frontmatter fields, recent run history |
+| 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) |
 | 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 |
@@ -233,13 +240,15 @@ Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay —
 - `Enter` — view detail
 - Type any character — search/filter
 - `Tab` — toggle selection (agents only)
-- `Ctrl+N` — new agent from template
+- `Alt+N` — new agent from template
 - `Ctrl+K` — clone current item
 - `Ctrl+D` or `Del` — delete current item
 - `Ctrl+R` — run selected (1 agent: launch, 2+: sequential chain)
 - `Ctrl+P` — open parallel builder (from selection or cursor agent)
 - `Esc` — clear query, then selection, then close overlay
 
+On a builtin detail screen, `e` opens the builtin override flow instead of cloning the whole agent. If no override exists yet, the manager asks whether to store it in user or project settings first.
+
 **Parallel builder keybindings:**
 - `↑↓` — navigate slots
 - `Ctrl+A` — add agent (opens search picker)
@@ -253,6 +262,12 @@ Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay —
 - `Tab` — toggle skip-clarify (defaults to on for all manager launches)
 - `Esc` — back
 
+**Builtin override edit keybindings:**
+- `Ctrl+S` — save override
+- `r` — reset the focused field back to the builtin value
+- `D` — remove the entire override
+- `Esc` — back
+
 **Multi-select workflow:** Select agents with `Tab`, then press `Ctrl+R` for a sequential chain or `Ctrl+P` to open the parallel builder. The parallel builder lets you add the same agent multiple times, set per-slot task overrides, and launch N agents in parallel. Slots without a custom task use the shared task entered on the next screen.
 
 ## Chain Files
@@ -306,7 +321,7 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 - **Worktree Isolation**: `worktree: true` gives each parallel agent its own git worktree, preventing filesystem conflicts during concurrent execution
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
 - **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`) plus optional recursion limits via `maxSubagentDepth`
-- **Chain Artifacts**: Shared directory at `<tmpdir>/pi-chain-runs/{runId}/` for inter-step files
+- **Chain Artifacts**: Shared directory at a user-scoped temp path like `<tmpdir>/pi-subagents-<scope>/chain-runs/{runId}/` for inter-step files
 - **Solo Agent Output**: Agents with `output` write to temp dir and return path to caller
 - **Live Progress Display**: Real-time visibility during sync execution showing current tool, recent output, tokens, and duration
 - **Output Truncation**: Configurable byte/line limits via `maxOutput`
@@ -397,9 +412,12 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 **Skill locations (project-first precedence):**
 - Project: `.pi/skills/{name}/SKILL.md`
 - Project packages: `.pi/npm/node_modules/*` via `package.json -> pi.skills`
+- Project settings packages: local package roots from `.pi/settings.json -> packages`, then `package.json -> pi.skills`
+- Current task cwd package: `<cwd>/package.json -> pi.skills`
 - Project settings: `.pi/settings.json -> skills`
 - User: `~/.pi/agent/skills/{name}/SKILL.md`
 - User packages: `~/.pi/agent/npm/node_modules/*` via `package.json -> pi.skills`
+- User settings packages: local package roots from `~/.pi/agent/settings.json -> packages`, then `package.json -> pi.skills`
 - User settings: `~/.pi/agent/settings.json -> skills`
 
 **Usage:**
@@ -529,7 +547,7 @@ These are the parameters the **LLM agent** passes when it calls the `subagent` t
 ```typescript
 { action: "list" }                    // active async runs only
 { id: "a53ebe46" }                    // inspect one run
-{ dir: "<tmpdir>/pi-async-subagent-runs/a53ebe46-..." }
+{ dir: "<tmpdir>/pi-subagents-<scope>/async-subagent-runs/a53ebe46-..." }
 ```
 
 **/subagents-status slash command:**
@@ -615,7 +633,7 @@ Notes:
 | `worktree` | boolean | false | Create isolated git worktrees for each parallel task. Requires clean git state. Per-worktree diffs included in output. |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
 | `context` | `"fresh" \| "fork"` | `fresh` | Execution context mode. `fork` uses a real branched session from the parent's current leaf for each child run |
-| `chainDir` | string | `<tmpdir>/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
+| `chainDir` | string | user-scoped temp dir like `<tmpdir>/pi-subagents-<scope>/chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
 | `agentScope` | `"user" \| "project" \| "both"` | `both` | Agent discovery scope (project wins on name collisions) |
 | `async` | boolean | false | Background execution (requires `clarify: false` for chains) |
@@ -850,7 +868,7 @@ Optional timeout (milliseconds) for each worktree hook invocation.
 Default: `30000` ms.
 
 ## Chain Directory
-Each chain run creates `<tmpdir>/pi-chain-runs/{runId}/` containing:
+Each chain run creates a user-scoped temp directory like `<tmpdir>/pi-subagents-<scope>/chain-runs/{runId}/` containing:
 - `context.md` - Scout/context-builder output
 - `plan.md` - Planner output
 - `progress.md` - Worker/reviewer shared progress
@@ -863,7 +881,7 @@ Directories older than 24 hours are cleaned up on extension startup.
 
 ## Artifacts
 
-Location: `{sessionDir}/subagent-artifacts/` or `<tmpdir>/pi-subagent-artifacts/`
+Location: `{sessionDir}/subagent-artifacts/` or a user-scoped temp directory like `<tmpdir>/pi-subagents-<scope>/artifacts/`
 
 Files per task:
 - `{runId}_{agent}_input.md` - Task prompt
@@ -903,8 +921,8 @@ Requirements:
 During sync execution, the collapsed view shows real-time progress for single, chain, and parallel modes.
 
 **Chains:**
-- Header: `... chain 1/2 | 8 tools, 1.4k tok, 38s`
-- Chain visualization with status: `✓scout → ●planner` (✓=done, ●=running, ○=pending, ✗=failed)
+- Header: `running chain 1/2 | 8 tools, 1.4k tok, 38s`
+- Chain visualization with status: `done scout → running planner` (`done`, `running`, `pending`, `failed`)
 - Current tool: `> read: packages/tui/src/...`
 - Recent output lines (last 2-3 lines)
 
@@ -915,7 +933,7 @@ During sync execution, the collapsed view shows real-time progress for single, c
 
 Press **Ctrl+O** to expand the full streaming view with complete output per step.
 
-> **Note:** Chain visualization (the `✓scout → ●planner` line) is only shown for sequential chains. Chains with parallel steps show per-step cards instead.
+> **Note:** Chain visualization (the `done scout → running planner` line) is only shown for sequential chains. Chains with parallel steps show per-step cards instead.
 
 ## Nested subagent recursion guard
 
@@ -946,14 +964,17 @@ export PI_SUBAGENT_MAX_DEPTH=0   # disable the subagent tool entirely
 Async runs write a dedicated observability folder:
 
 ```
-<tmpdir>/pi-async-subagent-runs/<id>/
+<tmpdir>/pi-subagents-<scope>/async-subagent-runs/<id>/
   status.json
   events.jsonl
+  output-<n>.log
   subagent-log-<id>.md
 ```
 
 `status.json` is the source of truth for async progress and powers both the TUI widget and `/subagents-status`. Async status and result files are written atomically, so readers do not observe partial JSON during background updates.
 
+`events.jsonl` is the live event stream. It includes high-level wrapper events plus child `pi` JSON events annotated with subagent metadata for the run and step they belong to. `output-<n>.log` is a live human-readable tail for the current step. `subagent-log-<id>.md` is written when the run completes.
+
 When fallback is used in async/background mode, `status.json` and the final result JSON include the final selected model, ordered attempted models, and per-attempt outcomes so background runs are as debuggable as sync runs.
 
 For programmatic access:
@@ -961,7 +982,7 @@ For programmatic access:
 ```typescript
 subagent_status({ action: "list" })
 subagent_status({ id: "<id>" })
-subagent_status({ dir: "<tmpdir>/pi-async-subagent-runs/<id>" })
+subagent_status({ dir: "<tmpdir>/pi-subagents-<scope>/async-subagent-runs/<id>" })
 ```
 
 For an interactive overview, run the `/subagents-status` slash command to open the overlay listing active runs and recent completed/failed runs. The overlay auto-refreshes every 2 seconds while it is open.

package/agent-management.ts

@@ -35,13 +35,18 @@ function parseCsv(value: string): string[] {
 	return [...new Set(value.split(",").map((v) => v.trim()).filter(Boolean))];
 }
 
-function configObject(config: unknown): Record<string, unknown> | undefined {
+function configObject(config: unknown): { value?: Record<string, unknown>; error?: string } {
 	let val = config;
 	if (typeof val === "string") {
-		try { val = JSON.parse(val); } catch { return undefined; }
+		try {
+			val = JSON.parse(val);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { error: `config must be valid JSON: ${message}` };
+		}
 	}
-	if (!val || typeof val !== "object" || Array.isArray(val)) return undefined;
-	return val as Record<string, unknown>;
+	if (!val || typeof val !== "object" || Array.isArray(val)) return {};
+	return { value: val as Record<string, unknown> };
 }
 
 function hasKey(obj: Record<string, unknown>, key: string): boolean {
@@ -383,7 +388,9 @@ export function handleGet(params: ManagementParams, ctx: ManagementContext): Age
 }
 
 export function handleCreate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
-	const cfg = configObject(params.config);
+	const parsedConfig = configObject(params.config);
+	if (parsedConfig.error) return result(parsedConfig.error, true);
+	const cfg = parsedConfig.value;
 	if (!cfg) return result("config required for create.", true);
 	if (typeof cfg.name !== "string" || !cfg.name.trim()) return result("config.name is required and must be a non-empty string.", true);
 	if (typeof cfg.description !== "string" || !cfg.description.trim()) return result("config.description is required and must be a non-empty string.", true);
@@ -427,7 +434,9 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 export function handleUpdate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for update.", true);
 	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
-	const cfg = configObject(params.config);
+	const parsedConfig = configObject(params.config);
+	if (parsedConfig.error) return result(parsedConfig.error, true);
+	const cfg = parsedConfig.value;
 	if (!cfg) return result("config required for update.", true);
 	const warnings: string[] = [];
 	if (params.agent) {

package/agent-manager-detail.ts

@@ -61,6 +61,10 @@ function buildDetailLines(
 	const maxSubagentDepth = agent.maxSubagentDepth !== undefined ? String(agent.maxSubagentDepth) : "(default)";
 
 	lines.push(renderFieldLine("Model:", agent.model ?? "default", contentWidth, theme));
+	if (agent.override) {
+		const overrideLabel = `${agent.override.scope} · ${formatPath(agent.override.path)}`;
+		lines.push(renderFieldLine("Override:", overrideLabel, contentWidth, theme));
+	}
 	lines.push(renderFieldLine("Thinking:", agent.thinking ?? "off", contentWidth, theme));
 	lines.push(renderFieldLine("Tools:", tools, contentWidth, theme));
 	lines.push(renderFieldLine("MCP:", mcp, contentWidth, theme));
@@ -102,7 +106,7 @@ function buildDetailLines(
 
 	for (const run of recentRuns) {
 		const when = pad(formatRelativeTime(run.ts), 8);
-		const status = run.status === "ok" ? "✓" : "✗";
+		const status = run.status;
 		const task = truncateToWidth(`"${run.task}"`, 34);
 		const tail = run.status === "ok" ? formatDuration(run.duration) : `exit ${run.exit ?? 1}`;
 		lines.push(truncateToWidth(`  ${when} ${status} ${task} ${tail}`, contentWidth));
@@ -131,7 +135,11 @@ export function renderDetail(
 	theme: Theme,
 ): string[] {
 	const lines: string[] = [];
-	const scopeBadge = agent.source === "builtin" ? "[builtin]" : agent.source === "project" ? "[proj]" : "[user]";
+	const scopeBadge = agent.source === "builtin"
+		? (agent.override ? `[builtin+${agent.override.scope}]` : "[builtin]")
+		: agent.source === "project"
+			? "[proj]"
+			: "[user]";
 	const headerText = ` ${agent.name} ${scopeBadge} ${formatPath(agent.filePath)} `;
 	lines.push(renderHeader(headerText, width, theme));
 	lines.push(row("", width, theme));
@@ -152,7 +160,9 @@ export function renderDetail(
 	lines.push(row(scrollInfo ? ` ${theme.fg("dim", scrollInfo)}` : "", width, theme));
 
 	const footer = agent.source === "builtin"
-		? " [l]aunch  [v] raw/resolved  [↑↓] scroll  [esc] back "
+		? agent.override
+			? " [l]aunch  [e]dit override  [v] raw/resolved  [↑↓] scroll  [esc] back "
+			: " [l]aunch  [e]create override  [v] raw/resolved  [↑↓] scroll  [esc] back "
 		: " [l]aunch  [e]dit  [v] raw/resolved  [↑↓] scroll  [esc] back ";
 	lines.push(renderFooter(footer, width, theme));
 	return lines;

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 } from "./agents.ts";
+import type { AgentConfig, 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";
@@ -8,30 +8,70 @@ import { pad, row, renderHeader, renderFooter, formatScrollInfo } from "./render
 export interface ModelInfo { provider: string; id: string; fullId: string; }
 export interface SkillInfo { name: string; source: string; description?: string; }
 export type EditScreen = "edit" | "edit-field" | "edit-prompt";
+export type EditField = typeof FIELD_ORDER[number];
+
 export interface EditState {
 	draft: AgentConfig; isNew: boolean; fieldIndex: number; fieldMode: "text" | "model" | "thinking" | "skills" | null;
 	fieldEditor: TextEditorState; promptEditor: TextEditorState; modelSearchQuery: string; modelCursor: number; filteredModels: ModelInfo[];
 	thinkingCursor: number; skillSearchQuery: string; skillCursor: number; filteredSkills: SkillInfo[]; skillSelected: Set<string>; error?: string;
+	fields: EditField[];
+	title?: string;
+	overrideBase?: BuiltinAgentOverrideBase;
+}
+export interface EditInputResult { action?: "save" | "discard" | "delete"; nextScreen?: EditScreen; }
+export interface CreateEditStateOptions {
+	fields?: EditField[];
+	title?: string;
+	overrideBase?: BuiltinAgentOverrideBase;
 }
-export interface EditInputResult { action?: "save" | "discard"; nextScreen?: EditScreen; }
 
 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;
-type EditField = typeof FIELD_ORDER[number];
 type ThinkingLevel = typeof THINKING_LEVELS[number];
 const PROMPT_VIEWPORT_HEIGHT = 16;
 const MODEL_SELECTOR_HEIGHT = 10;
 const SKILL_SELECTOR_HEIGHT = 10;
 
-function formatTools(draft: AgentConfig): string { const tools = [...(draft.tools ?? []), ...(draft.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`)]; return tools.length > 0 ? tools.join(", ") : ""; }
+function formatTools(draft: Pick<AgentConfig, "tools" | "mcpDirectTools">): string { const tools = [...(draft.tools ?? []), ...(draft.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`)]; return tools.length > 0 ? tools.join(", ") : ""; }
+function toolList(draft: Pick<AgentConfig, "tools" | "mcpDirectTools">): string[] | undefined { const tools = [...(draft.tools ?? []), ...(draft.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`)]; return tools.length > 0 ? tools : undefined; }
 function parseTools(value: string): { tools?: string[]; mcp?: string[] } { const items = value.split(",").map((item) => item.trim()).filter((item) => item.length > 0); const tools: string[] = []; const mcp: string[] = []; for (const item of items) { if (item.startsWith("mcp:")) { const name = item.slice(4).trim(); if (name) mcp.push(name); } else { tools.push(item); } } return { tools: tools.length > 0 ? tools : undefined, mcp: mcp.length > 0 ? mcp : undefined }; }
 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 fieldValueMatchesBase(field: EditField, state: EditState): boolean {
+	const base = state.overrideBase;
+	if (!base) return false;
+	switch (field) {
+		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 "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;
+		default: return false;
+	}
+}
 
-export function createEditState(draft: AgentConfig, isNew: boolean, models: ModelInfo[], skills: SkillInfo[]): EditState {
+function resetFieldToBase(field: EditField, state: EditState): void {
+	const base = state.overrideBase;
+	if (!base) return;
+	switch (field) {
+		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 "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;
+		default: break;
+	}
+}
+
+export function createEditState(draft: AgentConfig, isNew: boolean, models: ModelInfo[], skills: SkillInfo[], options: CreateEditStateOptions = {}): EditState {
 	return {
 		draft: { ...draft, tools: draft.tools ? [...draft.tools] : undefined, mcpDirectTools: draft.mcpDirectTools ? [...draft.mcpDirectTools] : undefined, skills: draft.skills ? [...draft.skills] : undefined, fallbackModels: draft.fallbackModels ? [...draft.fallbackModels] : undefined, extensions: draft.extensions ? [...draft.extensions] : draft.extensions, defaultReads: draft.defaultReads ? [...draft.defaultReads] : undefined, extraFields: draft.extraFields ? { ...draft.extraFields } : undefined },
 		isNew, fieldIndex: 0, fieldMode: null, fieldEditor: createEditorState(), promptEditor: createEditorState(draft.systemPrompt ?? ""),
 		modelSearchQuery: "", modelCursor: 0, filteredModels: [...models], thinkingCursor: 0, skillSearchQuery: "", skillCursor: 0, filteredSkills: [...skills], skillSelected: new Set(draft.skills ?? []),
+		fields: options.fields ?? [...FIELD_ORDER], title: options.title, overrideBase: options.overrideBase,
 	};
 }
 
@@ -71,15 +111,15 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 }
 
 function openModelPicker(state: EditState, models: ModelInfo[]): void {
-	state.fieldIndex = FIELD_ORDER.indexOf("model"); state.fieldMode = "model"; state.modelSearchQuery = ""; state.filteredModels = [...models];
+	state.fieldIndex = state.fields.indexOf("model"); state.fieldMode = "model"; state.modelSearchQuery = ""; state.filteredModels = [...models];
 	const idx = state.filteredModels.findIndex((m) => m.fullId === state.draft.model || m.id === state.draft.model); state.modelCursor = idx >= 0 ? idx : 0;
 }
 function openThinkingPicker(state: EditState): void {
-	state.fieldIndex = FIELD_ORDER.indexOf("thinking"); state.fieldMode = "thinking";
+	state.fieldIndex = state.fields.indexOf("thinking"); state.fieldMode = "thinking";
 	const idx = THINKING_LEVELS.indexOf((state.draft.thinking ?? "off") as ThinkingLevel); state.thinkingCursor = idx >= 0 ? idx : 0;
 }
 function openSkillPicker(state: EditState, skills: SkillInfo[]): void {
-	state.fieldIndex = FIELD_ORDER.indexOf("skills"); state.fieldMode = "skills"; state.skillSearchQuery = ""; state.filteredSkills = [...skills]; state.skillSelected = new Set(state.draft.skills ?? []); state.skillCursor = 0;
+	state.fieldIndex = state.fields.indexOf("skills"); state.fieldMode = "skills"; state.skillSearchQuery = ""; state.filteredSkills = [...skills]; state.skillSelected = new Set(state.draft.skills ?? []); state.skillCursor = 0;
 }
 
 function renderModelPicker(state: EditState, width: number, theme: Theme): string[] {
@@ -183,9 +223,11 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 	if (screen === "edit") {
 		if (matchesKey(data, "ctrl+s")) return { action: "save" };
 		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) return { action: "discard" };
+		if (data === "D" && state.overrideBase) return { action: "delete" };
 		if (matchesKey(data, "up")) { state.fieldIndex = Math.max(0, state.fieldIndex - 1); return; }
-		if (matchesKey(data, "down")) { state.fieldIndex = Math.min(FIELD_ORDER.length - 1, state.fieldIndex + 1); return; }
-		const field = FIELD_ORDER[state.fieldIndex]!;
+		if (matchesKey(data, "down")) { state.fieldIndex = Math.min(state.fields.length - 1, state.fieldIndex + 1); return; }
+		const field = state.fields[state.fieldIndex]!;
+		if (data === "r" && state.overrideBase) { resetFieldToBase(field, state); return; }
 		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" }; }
@@ -234,7 +276,7 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 			return;
 		}
 		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) { state.fieldMode = null; return { nextScreen: "edit" }; }
-		if (matchesKey(data, "return")) { const field = FIELD_ORDER[state.fieldIndex]!; applyFieldValue(field, state, state.fieldEditor.buffer); state.fieldMode = null; return { nextScreen: "edit" }; }
+		if (matchesKey(data, "return")) { const field = state.fields[state.fieldIndex]!; applyFieldValue(field, state, state.fieldEditor.buffer); state.fieldMode = null; return { nextScreen: "edit" }; }
 		if (matchesKey(data, "tab")) return;
 		const innerW = width - 2; const labelWidth = 12; const textWidth = Math.max(10, innerW - labelWidth - 6);
 		const nextState = handleEditorInput(state.fieldEditor, data, textWidth); if (nextState) state.fieldEditor = nextState; return;
@@ -256,13 +298,14 @@ export function renderEdit(screen: EditScreen, state: EditState, width: number,
 	if (screen === "edit-prompt") return renderPromptEditor(state, width, theme);
 	const lines: string[] = [];
 	const scopeBadge = state.draft.source === "user" ? "[user]" : "[proj]"; const label = state.isNew ? " [new]" : "";
-	lines.push(renderHeader(` Editing: ${state.draft.name} ${scopeBadge}${label} `, width, theme));
+	lines.push(renderHeader(` ${state.title ?? `Editing: ${state.draft.name} ${scopeBadge}${label}`} `, width, theme));
 	lines.push(row("", width, theme));
 	const innerW = width - 2; const labelWidth = 12; const valueWidth = Math.max(10, innerW - labelWidth - 6);
-	for (let i = 0; i < FIELD_ORDER.length; i++) {
-		const field = FIELD_ORDER[i]!; if (field === "prompt") break;
+	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 labelText = pad(`${field[0]!.toUpperCase()}${field.slice(1)}:`, labelWidth); let valueText = renderFieldValue(field, state);
+		const rawLabel = pad(`${field[0]!.toUpperCase()}${field.slice(1)}:`, labelWidth);
+		const labelText = state.overrideBase && !fieldValueMatchesBase(field, state) ? theme.fg("accent", rawLabel) : rawLabel; let valueText = renderFieldValue(field, state);
 		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);
@@ -275,14 +318,23 @@ export function renderEdit(screen: EditScreen, state: EditState, width: number,
 		}
 		lines.push(row(` ${prefix}${labelText} [${displayValue}]`, width, theme));
 	}
-	lines.push(row("", width, theme));
-	const promptFocused = state.fieldIndex === FIELD_ORDER.indexOf("prompt");
-	const promptPrefix = promptFocused ? theme.fg("accent", "▸ ") : "  ";
-	lines.push(row(` ${promptPrefix}${theme.fg("dim", "── System Prompt ──")}`, width, theme));
-	const previewWidth = innerW - 2; const wrapped = wrapText(state.draft.systemPrompt ?? "", previewWidth); const previewLines = wrapped.lines.slice(0, 4);
-	for (const line of previewLines) lines.push(row(` ${line}`, width, theme));
-	for (let i = previewLines.length; i < 4; i++) lines.push(row("", width, theme));
+	if (state.fields.includes("prompt")) {
+		lines.push(row("", width, theme));
+		const promptIndex = state.fields.indexOf("prompt");
+		const promptFocused = state.fieldIndex === promptIndex;
+		const promptPrefix = promptFocused ? theme.fg("accent", "▸ ") : "  ";
+		const promptTitle = state.overrideBase && !fieldValueMatchesBase("prompt", state)
+			? theme.fg("accent", "── System Prompt ──")
+			: theme.fg("dim", "── System Prompt ──");
+		lines.push(row(` ${promptPrefix}${promptTitle}`, width, theme));
+		const previewWidth = innerW - 2; const wrapped = wrapText(state.draft.systemPrompt ?? "", previewWidth); const previewLines = wrapped.lines.slice(0, 4);
+		for (const line of previewLines) lines.push(row(` ${line}`, width, theme));
+		for (let i = previewLines.length; i < 4; i++) lines.push(row("", width, theme));
+	}
 	if (state.error) lines.push(row(` ${theme.fg("error", state.error)}`, width, theme)); else lines.push(row("", width, theme));
-	lines.push(renderFooter(" [ctrl+s] save  [esc] back ", width, theme));
+	const footer = state.overrideBase
+		? " [ctrl+s] save  [r] reset field  [D] remove override  [esc] back "
+		: " [ctrl+s] save  [esc] back ";
+	lines.push(renderFooter(footer, width, theme));
 	return lines;
 }

package/agent-manager-list.ts

@@ -9,6 +9,7 @@ export interface ListAgent {
 	description: string;
 	model?: string;
 	source: AgentSource;
+	overrideScope?: "user" | "project";
 	kind: "agent" | "chain";
 	stepCount?: number;
 }
@@ -190,7 +191,7 @@ export function renderList(
 		const innerW = width - 2;
 		const nameWidth = 16;
 		const modelWidth = 12;
-		const scopeWidth = 9;
+		const scopeWidth = 17;
 
 		for (let i = 0; i < visible.length; i++) {
 			const agent = visible[i]!;
@@ -199,16 +200,22 @@ export function renderList(
 			const count = selectionCount(state.selected, agent.id);
 			const isShadowed = agent.kind === "agent" && agent.source === "project" && userNames.has(agent.name);
 
-			const cursorChar = isCursor ? theme.fg("accent", "▸") : " ";
-			const selectBadge = count > 1 ? theme.fg("accent", `×${count}`.padStart(2)) : count === 1 ? theme.fg("accent", " ✓") : "  ";
-			const shadowMarker = isShadowed ? theme.fg("warning", "●") : " ";
+			const cursorChar = isCursor ? theme.fg("accent", ">") : " ";
+			const selectBadge = count > 0 ? theme.fg("accent", String(count).padStart(2)) : "  ";
+			const shadowMarker = isShadowed ? theme.fg("warning", "!") : " ";
 			const prefix = `${cursorChar}${selectBadge}${shadowMarker} `;
 
 			const modelRaw = agent.kind === "chain" ? `${agent.stepCount ?? 0} steps` : (agent.model ?? "default");
 			const modelDisplay = modelRaw.includes("/") ? modelRaw.split("/").pop() ?? modelRaw : modelRaw;
 			const nameText = isCursor ? theme.fg("accent", agent.name) : agent.name;
 			const modelText = theme.fg("dim", modelDisplay);
-			const scopeLabel = agent.kind === "chain" ? "[chain]" : agent.source === "builtin" ? "[builtin]" : agent.source === "project" ? "[proj]" : "[user]";
+			const scopeLabel = agent.kind === "chain"
+				? "[chain]"
+				: agent.source === "builtin"
+					? (agent.overrideScope ? `[builtin+${agent.overrideScope}]` : "[builtin]")
+					: agent.source === "project"
+						? "[proj]"
+						: "[user]";
 			const scopeBadge = theme.fg("dim", scopeLabel);
 			const descText = theme.fg("dim", agent.description);