@herbertgao/pi-subagents 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.2
+
+### Patch Changes
+
+- [#15](https://github.com/HerbertGao/pi-extensions/pull/15) [`bc083d2`](https://github.com/HerbertGao/pi-extensions/commit/bc083d27c974f6b5239561dbd2295b6dd53526c0) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Skip unreadable or malformed custom agent files by default, warn when an earlier same-named definition remains active, and add opt-in strict startup validation.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -7,6 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`strictAgentFiles` — fail startup on a broken agent file instead of skipping it.** Off by default and applied only during initial extension activation; later per-call reloads remain tolerant.
+
+### Fixed
+
+- **One malformed agent file no longer aborts extension activation** ([#212](https://github.com/tintinweb/pi-subagents/issues/212) — thanks [@daromaj](https://github.com/daromaj)). Unreadable and unparseable files are skipped with a path-specific warning, including the earlier source that remains active when a broken file was an override.
+
 ## [0.15.1] - 2026-08-10
 
 ### Fixed

package/README.md

@@ -180,6 +180,8 @@ Agents are discovered from three locations (higher priority wins):
 
 Project-level agents override global ones with the same name, so you can customize a global agent for a specific project. If both project locations define the same name, **`.pi/agents/` wins** — `.pi` stays the project authority; `.agents/agents/` is an additional read location for projects that keep their agent assets in the `.agents` workspace. The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
 
+An unreadable or unparseable agent file is skipped by default, with a warning that names the file and error. If the skipped file was overriding a same-named agent, another warning names the earlier file that remains active. Set `strictAgentFiles: true` in `subagents.json` (or `/agents → Settings → Strict agent files`) to fail startup on a broken file instead; mid-session reloads remain tolerant.
+
 ### Example: `.pi/agents/auditor.md`
 
 ```markdown
@@ -430,12 +432,14 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, widget all/background/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, strict agent files on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, widget all/background/off) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, defaults enabled).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, strict agent files disabled, defaults enabled).
+
+**Strict agent files** (`strictAgentFiles`, default `false`): fail extension startup when any discovered agent file is unreadable or malformed. Enable via `/agents → Settings → Strict agent files` or set `true` in `subagents.json`. Strictness applies only to startup; reloads before later Agent calls remain tolerant so a file edited incorrectly mid-session is skipped with a warning instead of aborting the call.
 
 **Nested depth** (`maxSubagentDepth`, default `2`): the hard ceiling on [nested delegation](#nested-subagents), counted from the main session (main = 0, its subagents = 1). `0` or `1` disables nesting project-wide regardless of any agent's `allowed_subagents`. Read when a subagent session is built, so a change applies to agents started after it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -64,8 +64,8 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.14.3",
+    "version": "0.15.0",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "2966cd5"
+    "commit": "140324c"
   }
 }

package/src/custom-agents.ts

@@ -8,6 +8,13 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent"
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js"
 import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js"
 
+interface WarningState {
+  previous: Set<string>
+  current: Set<string>
+}
+
+const warningHistoryByCwd = new Map<string, Set<string>>()
+
 /**
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
@@ -20,15 +27,36 @@ import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js"
  * authority; .agents/agents is an additional read location.
  * Any name is allowed — names matching defaults (e.g. "Explore") override them.
  */
-export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+export function loadCustomAgents(
+  cwd: string,
+  strict = false,
+): Map<string, AgentConfig> {
   const globalDir = join(getAgentDir(), "agents")
   const workspaceProjectDir = join(cwd, ".agents", "agents")
   const projectDir = join(cwd, ".pi", "agents")
 
   const agents = new Map<string, AgentConfig>()
-  loadFromDir(globalDir, agents, "global") // lowest priority
-  loadFromDir(workspaceProjectDir, agents, "project") // shared workspace
-  loadFromDir(projectDir, agents, "project") // highest priority (overwrites)
+  const skippedOverrides = new Set<string>()
+  const warnings: WarningState = {
+    previous: warningHistoryByCwd.get(cwd) ?? new Set(),
+    current: new Set(),
+  }
+
+  loadFromDir(globalDir, agents, "global", strict, warnings, skippedOverrides) // lowest priority
+  loadFromDir(
+    workspaceProjectDir,
+    agents,
+    "project",
+    strict,
+    warnings,
+    skippedOverrides,
+  ) // shared workspace
+  loadFromDir(projectDir, agents, "project", strict, warnings, skippedOverrides) // highest priority (overwrites)
+
+  for (const name of skippedOverrides) {
+    warnSkippedOverride(name, agents, warnings)
+  }
+  warningHistoryByCwd.set(cwd, warnings.current)
   return agents
 }
 
@@ -37,6 +65,9 @@ function loadFromDir(
   dir: string,
   agents: Map<string, AgentConfig>,
   source: "project" | "global",
+  strict: boolean,
+  warnings: WarningState,
+  skippedOverrides: Set<string>,
 ): void {
   if (!existsSync(dir)) return
 
@@ -49,16 +80,15 @@ function loadFromDir(
 
   for (const file of files) {
     const name = basename(file, ".md")
+    const path = join(dir, file)
 
-    let content: string
-    try {
-      content = readFileSync(join(dir, file), "utf-8")
-    } catch {
+    const parsed = readAgentFile(path, strict, warnings)
+    if (!parsed) {
+      skippedOverrides.add(name)
       continue
     }
-
-    const { frontmatter: fm, body } =
-      parseFrontmatter<Record<string, unknown>>(content)
+    skippedOverrides.delete(name)
+    const { frontmatter: fm, body } = parsed
 
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools)
 
@@ -97,10 +127,54 @@ function loadFromDir(
       isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false, // default true; explicitly false disables
       source,
+      sourcePath: path,
     })
   }
 }
 
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. Under strict mode the same failure aborts startup while naming the file.
+ */
+function readAgentFile(
+  path: string,
+  strict: boolean,
+  warnings: WarningState,
+): { frontmatter: Record<string, unknown>; body: string } | undefined {
+  try {
+    return parseFrontmatter<Record<string, unknown>>(
+      readFileSync(path, "utf-8"),
+    )
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    if (strict) throw new Error(`${path}: ${reason}`)
+    warnIfNew(`Skipping agent file ${path}: ${reason}`, warnings)
+    return undefined
+  }
+}
+
+/** Warn when a broken higher-priority file exposes an earlier definition. */
+function warnSkippedOverride(
+  name: string,
+  agents: Map<string, AgentConfig>,
+  warnings: WarningState,
+): void {
+  const surviving = agents.get(name)
+  if (!surviving?.sourcePath || surviving.enabled === false) return
+  warnIfNew(
+    `Agent "${name}" now loads from ${surviving.sourcePath} instead`,
+    warnings,
+  )
+}
+
+/** Warn once while an error is unchanged, but report it again after recovery. */
+function warnIfNew(message: string, warnings: WarningState): void {
+  if (warnings.current.has(message)) return
+  warnings.current.add(message)
+  if (warnings.previous.has(message)) return
+  console.warn(`[pi-subagents] ${message}`)
+}
+
 // ---- Field parsers ----
 // All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
 

package/src/index.ts

@@ -83,6 +83,7 @@ import { SubagentScheduler } from "./schedule.js"
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js"
 import {
   applyAndEmitLoaded,
+  loadSettings,
   type SubagentsSettings,
   saveAndEmitChanged,
   type ToolDescriptionMode,
@@ -426,14 +427,18 @@ export default function (pi: ExtensionAPI) {
     },
   )
 
+  // This setting controls the initial load, which runs before the normal settings
+  // application below. Later per-call reloads deliberately remain tolerant.
+  let strictAgentFiles = loadSettings(process.cwd()).strictAgentFiles === true
+
   /** Reload agents from project/global custom agent dirs and merge with defaults (called on init and each Agent invocation). */
-  const reloadCustomAgents = () => {
-    const userAgents = loadCustomAgents(process.cwd())
+  const reloadCustomAgents = (strict = false) => {
+    const userAgents = loadCustomAgents(process.cwd(), strict)
     registerAgents(userAgents)
   }
 
-  // Initial load
-  reloadCustomAgents()
+  // Initial load — the only strict one.
+  reloadCustomAgents(strictAgentFiles)
 
   // ---- Agent activity tracking + widget ----
   const agentActivity = new Map<string, AgentActivity>()
@@ -990,6 +995,9 @@ export default function (pi: ExtensionAPI) {
       setDefaultJoinMode,
       setSchedulingEnabled,
       setScopeModels: setScopeModelsEnabled,
+      setStrictAgentFiles: (enabled) => {
+        strictAgentFiles = enabled
+      },
       setDisableDefaultAgents: setDisableDefaultAgents,
       setToolDescriptionMode: setToolDescriptionMode,
       setFleetView: setFleetViewEnabled,
@@ -2673,6 +2681,7 @@ ${systemPrompt}
       defaultJoinMode: getDefaultJoinMode(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
+      strictAgentFiles,
       disableDefaultAgents: isDefaultsDisabled(),
       toolDescriptionMode: getToolDescriptionMode(),
       fleetView: isFleetViewEnabled(),
@@ -2762,6 +2771,14 @@ ${systemPrompt}
           currentValue: isScopeModelsEnabled() ? "on" : "off",
           values: ["on", "off"],
         },
+        {
+          id: "strictAgentFiles",
+          label: "Strict agent files",
+          description:
+            "Fail startup on an unreadable or unparseable agent .md instead of skipping it with a warning",
+          currentValue: strictAgentFiles ? "on" : "off",
+          values: ["on", "off"],
+        },
         {
           id: "disableDefaultAgents",
           label: "Disable defaults",
@@ -2867,6 +2884,13 @@ ${systemPrompt}
         const enabled = value === "on"
         setScopeModelsEnabled(enabled)
         notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`)
+      } else if (id === "strictAgentFiles") {
+        const enabled = value === "on"
+        strictAgentFiles = enabled
+        notifyApplied(
+          ctx,
+          `Strict agent files ${enabled ? "enabled" : "disabled"}. Takes effect on next pi session.`,
+        )
       } else if (id === "disableDefaultAgents") {
         const enabled = value === "on"
         setDisableDefaultAgents(enabled)

package/src/settings.ts

@@ -49,6 +49,12 @@ export interface SubagentsSettings {
    * against. Defaults to false: subagents may use any model.
    */
   scopeModels?: boolean
+  /**
+   * When true, an unreadable or unparseable agent `.md` aborts extension load
+   * instead of being skipped with a warning. This applies only during startup;
+   * later per-call reloads remain tolerant. Defaults to false.
+   */
+  strictAgentFiles?: boolean
   /**
    * When true, the three built-in default agents (general-purpose, Explore, Plan)
    * are not registered at startup. User-defined agents from project/global custom
@@ -129,6 +135,7 @@ export interface SettingsAppliers {
   setDefaultJoinMode: (mode: JoinMode) => void
   setSchedulingEnabled: (b: boolean) => void
   setScopeModels: (enabled: boolean) => void
+  setStrictAgentFiles: (b: boolean) => void
   setDisableDefaultAgents: (b: boolean) => void
   setToolDescriptionMode: (mode: ToolDescriptionMode) => void
   setFleetView: (b: boolean) => void
@@ -207,6 +214,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.scopeModels === "boolean") {
     out.scopeModels = r.scopeModels
   }
+  if (typeof r.strictAgentFiles === "boolean") {
+    out.strictAgentFiles = r.strictAgentFiles
+  }
   if (typeof r.disableDefaultAgents === "boolean") {
     out.disableDefaultAgents = r.disableDefaultAgents
   }
@@ -315,6 +325,8 @@ export function applySettings(
   if (typeof s.schedulingEnabled === "boolean")
     appliers.setSchedulingEnabled(s.schedulingEnabled)
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels)
+  if (typeof s.strictAgentFiles === "boolean")
+    appliers.setStrictAgentFiles(s.strictAgentFiles)
   if (typeof s.disableDefaultAgents === "boolean")
     appliers.setDisableDefaultAgents(s.disableDefaultAgents)
   if (s.toolDescriptionMode)

package/src/types.ts

@@ -77,6 +77,8 @@ export interface AgentConfig {
   enabled?: boolean
   /** Where this agent was loaded from */
   source?: "default" | "project" | "global"
+  /** Path of the .md it was loaded from. Unset for embedded defaults. */
+  sourcePath?: string
 }
 
 export type JoinMode = "async" | "group" | "smart"