pi-subagents-lite 1.4.1 → 1.4.3

package/README.md

@@ -35,7 +35,7 @@ Names like `Agent`, `StopAgent`, `AgentStatus`, `run_in_background`, `worktree_p
 - **Live widget** — persistent status bar with running/completed agents, full and compact modes
 - **Result viewer** — fullscreen markdown with stats
 - **Worktrees** — run agents in a git worktree via `worktree_path`
-- **Output logs** — `tail -f` friendly, ISO-timestamped
+- **Output logs** — `tail -f` friendly, ISO-timestamped with configurable thinking buffer (OFF, 80, 200, 500, 1000 chars). Flush rounds to sentence boundaries.
 
 ## Install
 
@@ -112,7 +112,7 @@ Stop a running agent by ID.
 |---|---|---|
 | `agent_id` | ✅ | The agent ID returned by `Agent` at spawn |
 
-IDs come from the `Agent` result, the `StopAgent` error (lists all running IDs), or `/agents` → **Running agents**.
+IDs come from the `Agent` result, the `StopAgent` error (lists all running IDs), or `/agents` → **Running agents**. Display format is `id (type)` (e.g. `a1b2c3 (Explore)`).
 
 ### `AgentStatus`
 
@@ -244,13 +244,13 @@ When `includeContextFiles` is `true` (default), AGENTS.md files from the project
 Management menu with four sections:
 
 - **Running agents** — status and description; per-agent actions (view snapshot, result, error; steer; stop) and bulk stop
-- **Spawn agent** — manually spawn without the LLM. Pick a type, enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
+- **Spawn agent** — manually spawn without the LLM. Pick a type (with search), enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
 - **Settings**
   - **Model settings** — global default, per-type overrides, session overrides, clear all
   - **Spawn options** — force background, grace turns, default max turns, default thinking, disable default agents
   - **System prompt** — mode, custom prompt file, include AGENTS.md, load skills/extensions implicitly
-  - **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
-  - **Widget settings** — force compact, max lines, description length, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)
+  - **Concurrency** — default limit, per-provider and per-model slots (with search), reset to defaults
+  - **Widget settings** — force compact, max lines, description length, thinking buffer size, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)
 
 ## Interface
 
@@ -333,6 +333,7 @@ With **Cost display** ON, stats show dollar cost (`✓ Builder·2🛠 ·5⟳ ·
 | `widgetDescLengthCompact` | `30` | Max description length in compact mode. |
 | `widgetCompact` | `false` | Force compact mode regardless of ctrl+o state. |
 | `widgetShortcut` | `false` | When ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact is manual via `widgetCompact`. |
+| `outputThinkingBufferSize` | `200` | Thinking buffer ring size in chars. `0` = OFF. Flushes to output log at sentence boundaries. |
 
 ### Stats visibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",
@@ -28,11 +28,12 @@
     "url": "https://github.com/AlexParamonov/pi-subagents-lite/issues"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": ">=0.74.0"
+    "@earendil-works/pi-ai": "^0.80.1",
+    "@earendil-works/pi-coding-agent": "^0.80.1",
+    "@earendil-works/pi-tui": "^0.80.1"
   },
   "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.1",
     "@sinclair/typebox": "^0.34.49"
   },
   "files": [

package/src/agents/agent-discovery.ts

@@ -257,7 +257,6 @@ function compactDefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
  */
 export function parseAgentFile(
   content: string,
-  _filename: string,
   source: "user" | "project",
 ): AgentConfigFromMd {
   const { frontmatter, body } = parseFrontmatter(content);
@@ -310,7 +309,7 @@ export async function scanAgentFilesInDir(
     const filePath = path.join(dirPath, entry.name);
     try {
       const content = await fs.promises.readFile(filePath, "utf-8");
-      const info = parseAgentFile(content, entry.name, source);
+      const info = parseAgentFile(content, source);
       if (info.name) {
         agents.push(info);
       }

package/src/agents/agent-manager.ts

@@ -98,6 +98,7 @@ export class AgentManager {
     onComplete?: OnAgentComplete,
     concurrency?: ConcurrencyConfig,
     onStart?: OnAgentStart,
+    private bufferSize: number = 0,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
@@ -258,7 +259,7 @@ export class AgentManager {
     record.lifecycle.startedAt = Date.now();
 
     // Create output log for this agent (creates file + writes [USER] entry)
-    record.execution.outputLog = new AgentOutputLog(id, prompt);
+    record.execution.outputLog = new AgentOutputLog(id, prompt, undefined, this.bufferSize);
     record.display.outputFile = record.execution.outputLog.path;
 
     this.onStart?.(record);

package/src/agents/agent-runner.ts

@@ -21,21 +21,14 @@ import {
 import { getAgentConfig, getConfig, getToolNamesForType, resolveVisibleTools } from "./agent-types.js";
 import { extractText } from "../prompt/context.js";
 import type { LifetimeUsage } from "./usage.js";
-import { findModelInRegistry } from "../utils.js";
+import { findModelInRegistry, GIT_EXEC_TIMEOUT_MS } from "../utils.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { buildAgentPrompt, type PromptExtras } from "../prompt/prompts.js";
 import { preloadSkills, loadSkillMeta, type SkillMeta } from "../prompt/skill-loader.js";
 import { type EnvInfo, type RunCallbacks, type RunTunables, SHORT_ID_LENGTH } from "../types.js";
 import type { SubagentType, SystemPromptMode } from "./types.js";
 import { getStore } from "../shell.js";
-import { DEFAULT_GRACE_TURNS } from "../config/config-io.js";
-
-/** Path to custom prompt file. Exported for use in menus.ts. */
-export const CUSTOM_PROMPT_PATH = path.join(process.env.HOME || "", ".pi", "agent", "subagents-lite-prompt.md");
-
-
-/** Timeout for quick git commands (branch detection, repo check). */
-const GIT_EXEC_TIMEOUT_MS = 5000;
+import { DEFAULT_GRACE_TURNS, CUSTOM_PROMPT_PATH } from "../config/config-io.js";
 
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 function normalizeMaxTurns(n: number | undefined): number | undefined {

package/src/agents/agent-status.ts

@@ -12,11 +12,11 @@ import { SHORT_ID_LENGTH } from "../types.js";
 import { getManager } from "../shell.js";
 
 /**
- * Format a single agent record as "type·short_id·status".
+ * Format a single agent record as "short_id (type) status".
  */
 function formatAgent(record: AgentRecord): string {
   const shortId = record.id.slice(0, SHORT_ID_LENGTH);
-  return `${record.display.type}·${shortId}·${record.lifecycle.status}`;
+  return `${shortId} (${record.display.type}) ${record.lifecycle.status}`;
 }
 
 /**

package/src/agents/agent-types.ts

@@ -66,6 +66,15 @@ export function setAgentScanDirs(userDir: string, projectDir: string): void {
   projectAgentDir = projectDir;
 }
 
+/** Scan user and project agent directories, merge with defaults. Returns the merged Map. */
+async function scanAndMerge(options?: { disableDefaultAgents?: boolean }): Promise<Map<string, AgentConfig>> {
+  const [userAgents, projectAgents] = await Promise.all([
+    scanAgentFilesInDir(userAgentDir, "user"),
+    scanAgentFilesInDir(projectAgentDir, "project"),
+  ]);
+  const defaults = options?.disableDefaultAgents ? new Map<string, AgentConfig>() : DEFAULT_AGENTS;
+  return mergeAgents(defaults, userAgents, projectAgents);
+}
 /**
  * Scan the known agent directories and register any newly discovered agents
  * that aren't already in the registry. Returns the number of new agents added.
@@ -77,13 +86,7 @@ export function setAgentScanDirs(userDir: string, projectDir: string): void {
  * @param options - Optional settings. disableDefaultAgents skips DEFAULT_AGENTS in the merge.
  */
 export async function discoverNewAgents(worktreeDir?: string, options?: { disableDefaultAgents?: boolean }): Promise<number> {
-  const [userAgents, projectAgents] = await Promise.all([
-    scanAgentFilesInDir(userAgentDir, "user"),
-    scanAgentFilesInDir(projectAgentDir, "project"),
-  ]);
-
-  const defaults = options?.disableDefaultAgents ? new Map<string, AgentConfig>() : DEFAULT_AGENTS;
-  const merged = mergeAgents(defaults, userAgents, projectAgents);
+  const merged = await scanAndMerge(options);
 
   let count = 0;
   for (const [name, config] of merged) {
@@ -96,8 +99,6 @@ export async function discoverNewAgents(worktreeDir?: string, options?: { disabl
   // Scan worktree-local agents (only when worktreeDir is provided)
   if (worktreeDir) {
     const worktreeAgents = await scanAgentFilesInDir(worktreeDir, "project");
-    // Use mergeAgents to convert AgentConfigFromMd to AgentConfig (applies fromMd
-    // and BASE_DEFAULTS), then add only names not already in the registry.
     const wtMerged = mergeAgents(new Map(), [], worktreeAgents);
     for (const [name, config] of wtMerged) {
       if (!agents.has(name)) {
@@ -302,22 +303,23 @@ function applyGlobalDefaults(
   };
 }
 
+/** Find the first non-hidden config: resolved type, then general-purpose, then undefined. */
+function findActiveConfig(type: string): AgentConfig | undefined {
+  const key = resolveType(type);
+  const config = key ? agents.get(key) : undefined;
+  if (config?.hidden !== true) return config;
+  return agents.get("general-purpose");
+}
+
 /** Get config for a type (case-insensitive). Falls back to general-purpose. */
 export function getConfig(
   type: string,
   loadSkillsImplicitly: boolean = true,
   loadExtensionsImplicitly: boolean = true,
 ): ResolvedAgentConfig {
-  const resolvedKey = resolveType(type);
-  const config = resolvedKey ? agents.get(resolvedKey) : undefined;
-
-  // If config exists and is not hidden, use it; otherwise fall back to general-purpose
-  const activeConfig = config?.hidden !== true
-    ? config
-    : agents.get("general-purpose");
-
-  if (activeConfig && activeConfig.hidden !== true) {
-    const { skills, extensions, ...rest } = activeConfig;
+  const config = findActiveConfig(type);
+  if (config) {
+    const { skills, extensions, ...rest } = config;
     const defaults = applyGlobalDefaults(skills, extensions, loadSkillsImplicitly, loadExtensionsImplicitly);
     return {
       displayName: rest.displayName ?? rest.name,
@@ -328,7 +330,7 @@ export function getConfig(
     };
   }
 
-  // Absolute fallback — general-purpose was hidden or missing
+  // Absolute fallback — no config found at all
   const defaults = applyGlobalDefaults(undefined, undefined, loadSkillsImplicitly, loadExtensionsImplicitly);
   return {
     displayName: "Agent",

package/src/agents/output-file.ts

@@ -12,6 +12,26 @@ import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-
 import { formatTokens } from "./usage.js";
 import { summarizeToolArgs } from "../ui/format.js";
 
+
+/** Find the last sentence boundary in text. Returns the index of the
+ * terminal punctuation character, or -1 if none found. */
+function findLastSentenceBoundary(text: string): number {
+  // Search backward for the most recent sentence-ending punctuation
+  for (let i = text.length - 1; i >= 0; i--) {
+    const ch = text[i];
+    if ([".", "!", "?", ",", "\n"].includes(ch)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/** Format the [DONE] summary line with final stats. */
+function formatDoneLine(stats: { turnCount: number; toolUseCount: number; totalTokens: number; cost: number }): string {
+  const tokensStr = `${formatTokens(stats.totalTokens)} tokens`;
+  const costStr = `$${stats.cost.toFixed(3)}`;
+  return `${timestamp()} [DONE] ${stats.turnCount} turns, ${stats.toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`;
+}
 /** Max content length for full tool result display — longer results get a summary line. */
 const MAX_TOOL_RESULT_DISPLAY_LENGTH = 500;
 
@@ -111,12 +131,14 @@ function formatToolResult(toolName: string, content: ReadonlyArray<Record<string
 function formatMessageLine(
   role: "ASSISTANT" | "TOOL" | "USER",
   content: string | ReadonlyArray<Record<string, unknown>> | undefined,
+  skipThinkingCount: number = 0,
 ): string {
   if (typeof content === "string") {
     return splitAndPrefix(content, role);
   }
 
   if (Array.isArray(content)) {
+    let thinkingSkipped = 0;
     return content
       .map((item) => {
         if (item.type === "text" && typeof item.text === "string") {
@@ -126,6 +148,10 @@ function formatMessageLine(
           return formatToolItem(item);
         }
         if (item.type === "thinking" && typeof item.thinking === "string") {
+          if (thinkingSkipped < skipThinkingCount) {
+            thinkingSkipped++;
+            return ""; // Already streamed, skip
+          }
           const text = item.redacted ? "[redacted]" : item.thinking;
           return splitAndPrefix(text, "THINKING");
         }
@@ -136,7 +162,6 @@ function formatMessageLine(
 
   return "";
 }
-
 /**
  * Subscribe to session events and flush new messages to the output file
  * on each turn_end. Returns a cleanup function that writes the DONE line
@@ -148,15 +173,28 @@ export function streamToOutputFile(
   session: AgentSession,
   path: string,
   stats?: { turnCount: number; toolUseCount: number; totalTokens: number; cost: number },
+  bufferSize: number = 0,
 ): () => void {
   let writtenCount = 1; // initial user prompt already written
+  let thinkingBuffer = "";
+  let streamedThinkingBlocks = 0; // thinking blocks written live; skipped in the final flush
+  let streamedThinkingChars = 0; // track total chars streamed for deduplication
+  let thinkingBlockInProgress = false; // true between thinking_start and thinking_end
+
+  const flushThinkingBuffer = () => {
+    if (thinkingBuffer.length > 0) {
+      safeAppend(path, `${timestamp()} [THINKING] ${thinkingBuffer}\n`);
+      streamedThinkingChars += thinkingBuffer.length;
+      thinkingBuffer = "";
+    }
+  };
 
   const flush = () => {
     const messages = session.messages;
     while (writtenCount < messages.length) {
       const msg = messages[writtenCount];
       if (msg.role === "assistant") {
-        const lines = formatMessageLine("ASSISTANT", msg.content as any);
+        const lines = formatMessageLine("ASSISTANT", msg.content as any, streamedThinkingBlocks);
         if (lines) safeAppend(path, lines);
       } else if (msg.role === "user") {
         const text = extractUserText(msg.content as any);
@@ -176,18 +214,60 @@ export function streamToOutputFile(
   };
 
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "turn_end") flush();
+    if (event.type === "turn_end") {
+      flushThinkingBuffer();
+      // If thinking_end never fired, treat this as if it did to avoid duplicates
+      if (thinkingBlockInProgress) {
+        streamedThinkingBlocks++;
+        thinkingBlockInProgress = false;
+      }
+      flush();
+    }
+
+    if (bufferSize > 0 && event.type === "message_update") {
+      const assistantEvent = event.assistantMessageEvent;
+      if (assistantEvent.type === "thinking_start") {
+        // Reset counter for new thinking block
+        streamedThinkingChars = 0;
+        thinkingBlockInProgress = true;
+      } else if (assistantEvent.type === "thinking_delta") {
+        thinkingBuffer += assistantEvent.delta;
+        if (thinkingBuffer.length >= bufferSize) {
+          // Round down to nearest sentence boundary when possible
+          const boundary = findLastSentenceBoundary(thinkingBuffer);
+          if (boundary >= 0) {
+            const flushText = thinkingBuffer.slice(0, boundary + 1);
+            thinkingBuffer = thinkingBuffer.slice(boundary + 1);
+            safeAppend(path, `${timestamp()} [THINKING] ${flushText}\n`);
+            streamedThinkingChars += flushText.length;
+          } else {
+            // No sentence boundary found, flush at buffer limit
+            flushThinkingBuffer();
+          }
+        }
+      } else if (assistantEvent.type === "thinking_end") {
+        // thinking_end carries the full block. Flush the buffered tail first
+        // (counted in streamedThinkingChars), then stream whatever remains.
+        flushThinkingBuffer();
+        if (assistantEvent.content && assistantEvent.content.length > streamedThinkingChars) {
+          const remaining = assistantEvent.content.slice(streamedThinkingChars);
+          safeAppend(path, `${timestamp()} [THINKING] ${remaining}\n`);
+          streamedThinkingChars = assistantEvent.content.length;
+        }
+        streamedThinkingBlocks++;
+        thinkingBlockInProgress = false;
+      }
+    }
   });
 
   return () => {
     // Final flush
+    flushThinkingBuffer();
     flush();
 
     // Write DONE line
-    const { turnCount = 0, toolUseCount = 0, totalTokens = 0, cost = 0 } = stats ?? {};
-    const tokensStr = `${formatTokens(totalTokens)} tokens`;
-    const costStr = `$${cost.toFixed(3)}`;
-    safeAppend(path, `${timestamp()} [DONE] ${turnCount} turns, ${toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
+    const doneStats = stats ?? { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
+    safeAppend(path, formatDoneLine(doneStats));
 
     // Unsubscribe from session events
     unsubscribe();
@@ -219,10 +299,12 @@ export class AgentOutputLog {
   readonly path: string;
   private cleanup?: () => void;
   private statsRef?: OutputFinalStats;
+  private bufferSize: number;
 
-  constructor(agentId: string, prompt: string, baseDir?: string) {
+  constructor(agentId: string, prompt: string, baseDir?: string, bufferSize: number = 0) {
     this.path = createOutputFilePath(agentId, baseDir);
     writeInitialEntry(this.path, prompt);
+    this.bufferSize = bufferSize;
   }
 
   /**
@@ -232,7 +314,7 @@ export class AgentOutputLog {
    */
   attach(session: AgentSession): void {
     this.statsRef = { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
-    this.cleanup = streamToOutputFile(session, this.path, this.statsRef);
+    this.cleanup = streamToOutputFile(session, this.path, this.statsRef, this.bufferSize);
   }
 
   /**
@@ -254,9 +336,7 @@ export class AgentOutputLog {
       this.statsRef = undefined;
     } else {
       // No attach was called — write DONE directly
-      const tokensStr = `${formatTokens(stats.totalTokens)} tokens`;
-      const costStr = `$${stats.cost.toFixed(3)}`;
-      safeAppend(this.path, `${timestamp()} [DONE] ${stats.turnCount} turns, ${stats.toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
+      safeAppend(this.path, formatDoneLine(stats));
     }
   }
 }

package/src/agents/tool-execution.ts

@@ -52,16 +52,9 @@ function errorResult(text: string, details?: Record<string, unknown>) {
  * Consolidates the identical field-selection logic previously duplicated
  * across emitIndividualNudge, executeSpawnForeground, and executeSpawnBackground.
  */
-interface AgentDetailsOptions {
-  /** Include full stats (turns, tokens, context%, compactions, cost). Default: false. */
-  includeStats?: boolean;
-  /** Include status and outputFile. Default: false. */
-  includeStatus?: boolean;
-}
-
 export function buildAgentDetails(
   record: AgentRecord,
-  options?: AgentDetailsOptions,
+  opts?: { includeStats?: boolean; includeStatus?: boolean },
 ): Record<string, unknown> {
   const details: Record<string, unknown> = {
     type: record.display.type,
@@ -72,12 +65,12 @@ export function buildAgentDetails(
     details.worktreePath = record.display.worktreePath;
   }
 
-  if (options?.includeStatus) {
+  if (opts?.includeStatus) {
     details.status = record.lifecycle.status;
     details.outputFile = record.display.outputFile;
   }
 
-  if (options?.includeStats) {
+  if (opts?.includeStats) {
     const elapsedMs = record.lifecycle.completedAt ? record.lifecycle.completedAt - record.lifecycle.startedAt : 0;
 
     details.turnCount = record.stats.turnCount;
@@ -113,8 +106,13 @@ export async function executeAgentTool(
   if (rawWorktreePath && rawWorktreePath.trim() !== "") {
     try {
       const parentCwd = getSessionCtx()?.cwd ?? ctx.cwd;
-      const validation = await validateWorktreePath(getPiInstance(), rawWorktreePath, parentCwd);
+      const warnings: string[] = [];
+      const onWarning = (msg: string) => { warnings.push(msg); };
+      const validation = await validateWorktreePath(getPiInstance(), rawWorktreePath, parentCwd, onWarning);
       if (!validation.ok) {
+        for (const msg of warnings) {
+          if (ctx.ui?.notify) ctx.ui.notify(`[pi-subagents-lite] ${msg}`, "warning");
+        }
         return errorResult(validation.error);
       }
       validatedWorktreePath = validation.resolvedPath;
@@ -198,7 +196,7 @@ export async function executeAgentTool(
 
 /**
  * Build a compact list of running (or queued) agents.
- * Format: "type·short_id, type·short_id" — one line, easy for LLM to parse.
+ * Format: "short_id (type), short_id (type)" — one line, easy for LLM to parse.
  */
 function formatRunningAgents(): string {
   const agents = getManager()!.listAgents().filter(
@@ -208,7 +206,7 @@ function formatRunningAgents(): string {
   if (agents.length === 0) return "none";
 
   return agents
-    .map((a) => `${a.display.type}·${a.id.slice(0, SHORT_ID_LENGTH)}`)
+    .map((a) => `${a.id.slice(0, SHORT_ID_LENGTH)} (${a.display.type})`)
     .join(", ");
 }
 

package/src/agents/usage.ts

@@ -29,17 +29,10 @@ type SessionStatsLike = {
 };
 export type SessionLike = { getSessionStats(): SessionStatsLike };
 
-/** Format a token count compactly: "12.3k", "1.2M", or raw number. */
-export function formatTokens(count: number): string {
+/** Format a token count compactly: "12.3k", "1.2M", or raw number. When compact is true, thousands round to whole numbers. */
+export function formatTokens(count: number, compact = false): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-  return `${count}`;
-}
-
-/** Format token count for widget display: rounded to whole number for k. */
-export function formatTokensCompact(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-  if (count >= 1_000) return `${Math.round(count / 1_000)}k`;
+  if (count >= 1_000) return compact ? `${Math.round(count / 1_000)}k` : `${(count / 1_000).toFixed(1)}k`;
   return `${count}`;
 }
 

package/src/config/config-io.ts

@@ -11,46 +11,57 @@ import type { SubagentsConfig } from "../models/model-precedence.js";
 
 const CONFIG_DIR = path.join(process.env.HOME || "", ".pi", "agent");
 const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
-
+/** Path to custom prompt file for subagent system prompts. */
+export const CUSTOM_PROMPT_PATH = path.join(CONFIG_DIR, "subagents-lite-prompt.md");
 /** Default number of grace turns before an agent is force-stopped. */
 export const DEFAULT_GRACE_TURNS = 6;
 
-/** Default configuration — used when config file doesn't exist or is invalid. */
-export const DEFAULT_CONFIG: SubagentsConfig = {
-  agent: {
-    default: null,
-    forceBackground: false,
-    graceTurns: DEFAULT_GRACE_TURNS,
-    widgetMaxLines: 12,
-    // widgetMaxLinesCompact intentionally omitted — derives from widgetMaxLines
-    widgetDescLengthFull: 50,
-    widgetDescLengthCompact: 30,
-    widgetCompact: false,
-    widgetShortcut: false,
-    systemPromptMode: "replace",
-    includeContextFiles: true,
-    disableDefaultAgents: false,
-    showTools: true,
-    showTurns: true,
-    showInput: true,
-    showOutput: true,
-    showContext: true,
-    showCost: false,
-    showTime: true,
-  },
-  concurrency: { default: 4 },
+/** Valid system prompt modes. */
+export const VALID_SYSTEM_PROMPT_MODES = new Set<string>(["replace", "inherit", "custom"]);
+
+/** Default concurrency config — used for resets. */
+export const DEFAULT_CONCURRENCY: SubagentsConfig["concurrency"] = { default: 4 };
+
+/** Default agent settings — merged into loaded config so callers get a complete shape. */
+const DEFAULT_AGENT: SubagentsConfig["agent"] = {
+  default: null,
+  forceBackground: false,
+  graceTurns: DEFAULT_GRACE_TURNS,
+  widgetMaxLines: 12,
+  widgetDescLengthFull: 50,
+  widgetDescLengthCompact: 30,
+  widgetCompact: false,
+  widgetShortcut: false,
+  systemPromptMode: "replace",
+  includeContextFiles: true,
+  disableDefaultAgents: false,
+  showTools: true,
+  showTurns: true,
+  showInput: true,
+  showOutput: true,
+  showContext: true,
+  showCost: false,
+  showTime: true,
 };
 
 /**
- * Read config from disk. Returns defaults if file doesn't exist or is invalid.
+ * Read config from disk. Merges loaded values over defaults so the result
+ * is always a complete SubagentsConfig — no partial shapes for callers to handle.
  */
 export function loadConfig(): SubagentsConfig {
+  let raw: SubagentsConfig;
   try {
-    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
-    return JSON.parse(raw) as SubagentsConfig;
+    raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8")) as SubagentsConfig;
   } catch {
-    return { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
+    raw = {} as SubagentsConfig;
   }
+
+  // @ts-expect-error TS2783: spread may override 'default', which is intentional (loaded value wins)
+  const concurrency = { default: 4, ...(raw.concurrency ?? {}) } as SubagentsConfig["concurrency"];
+  return {
+    agent: { ...DEFAULT_AGENT, ...raw.agent },
+    concurrency,
+  };
 }
 
 /** Write config to disk with atomic rename. */