@herbertgao/pi-subagents 0.15.1 → 0.15.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.15.3
+
+### Patch Changes
+
+- [#27](https://github.com/HerbertGao/pi-extensions/pull/27) [`32bb76c`](https://github.com/HerbertGao/pi-extensions/commit/32bb76c117971de27db9c2b521d19df3ba9ea322) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Keep worktree-isolated agents inside their copy, preserve real Agent tool startup errors, and render unknown or failed Agent results without misleading completion status.
+
+## 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 +19,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.3",
   "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": "c83dd82"
   }
 }

package/src/agent-manager.ts

@@ -321,6 +321,7 @@ export class AgentManager {
       // stay undefined otherwise so plain worktree runs keep resolving config
       // (incl. relative extension paths and memory) inside the worktree copy.
       cwd: worktreeCwd ?? customCwd,
+      worktreeBase: worktreeCwd ? baseCwd : undefined,
       configCwd:
         options.configCwd ?? (customCwd !== undefined ? ctx.cwd : undefined),
       signal: record.abortController!.signal,

package/src/agent-runner.ts

@@ -414,6 +414,8 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string
+  /** Original checkout path when cwd is an isolated worktree copy. */
+  worktreeBase?: string
   /**
    * Where .pi config is discovered (project extensions, skills, pi settings,
    * agent memory). Default: same as the working directory. The manager sets
@@ -602,7 +604,7 @@ export async function runAgent(
   const parentSystemPrompt = ctx.getSystemPrompt()
 
   // Build prompt extras (memory, skill preloading)
-  const extras: PromptExtras = {}
+  const extras: PromptExtras = { worktreeBase: options.worktreeBase }
 
   // Resolve extensions/skills: isolated overrides to false
   const extensions = options.isolated ? false : config.extensions

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,
@@ -1233,12 +1241,12 @@ Terse command-style prompts produce shallow, generic work.
         )
       },
 
-      renderResult(result, { expanded, isPartial }, theme) {
+      renderResult(result, { expanded, isPartial }, theme, renderContext) {
+        const resultText =
+          result.content[0]?.type === "text" ? result.content[0].text : ""
         const details = result.details as AgentDetails | undefined
-        if (!details) {
-          const text =
-            result.content[0]?.type === "text" ? result.content[0].text : ""
-          return new Text(text, 0, 0)
+        if (renderContext?.isError || !details?.status) {
+          return new Text(resultText, 0, 0)
         }
 
         // Helper: build "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k tokens" stats string
@@ -1293,8 +1301,6 @@ Terse command-style prompts produce shallow, generic work.
           line += " " + theme.fg("dim", "·") + " " + theme.fg("dim", duration)
 
           if (expanded) {
-            const resultText =
-              result.content[0]?.type === "text" ? result.content[0].text : ""
             if (resultText) {
               const lines = resultText.split("\n").slice(0, 50)
               for (const l of lines) {
@@ -1324,6 +1330,10 @@ Terse command-style prompts produce shallow, generic work.
           return new Text(line, 0, 0)
         }
 
+        if (details.status !== "error" && details.status !== "aborted") {
+          return new Text(resultText, 0, 0)
+        }
+
         // ---- Error / Aborted (hard max_turns) ----
         const s = stats(details)
         let line = theme.fg("error", "✗") + (s ? " " + s : "")
@@ -1590,23 +1600,22 @@ Terse command-style prompts produce shallow, generic work.
             }
           }
 
-          try {
-            id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-              description: params.description,
-              model,
-              maxTurns: effectiveMaxTurns,
-              isolated,
-              inheritContext,
-              thinkingLevel: thinking,
-              isBackground: true,
-              isolation,
-              invocation: agentInvocation,
-              rootSessionId: ctx.sessionManager.getSessionId(),
-              ...bgCallbacks,
-            })
-          } catch (err) {
-            return textResult(err instanceof Error ? err.message : String(err))
-          }
+          // A throw here means the agent never started. Let it out: Pi marks a
+          // tool call failed only when execute throws, while a returned message
+          // reads to the model as a subagent that ran and reported this.
+          id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+            description: params.description,
+            model,
+            maxTurns: effectiveMaxTurns,
+            isolated,
+            inheritContext,
+            thinkingLevel: thinking,
+            isBackground: true,
+            isolation,
+            invocation: agentInvocation,
+            rootSessionId: ctx.sessionManager.getSessionId(),
+            ...bgCallbacks,
+          })
 
           // Set output file + join mode synchronously after spawn, before the
           // event loop yields — onSessionCreated is async so this is safe.
@@ -1766,18 +1775,15 @@ Terse command-style prompts produce shallow, generic work.
             },
           )
           record = fgResult.record
-        } catch (err) {
+        } finally {
+          // A startup throw propagates as a failed tool call without leaving
+          // the spinner running or a finished agent in the widget.
           clearInterval(spinnerInterval)
-          return textResult(err instanceof Error ? err.message : String(err))
-        }
-
-        clearInterval(spinnerInterval)
-
-        // Clean up foreground agent from widget
-        if (fgId) {
-          agentActivity.delete(fgId)
-          widget.markFinished(fgId)
-          fleet.onAgentFinished(fgId)
+          if (fgId) {
+            agentActivity.delete(fgId)
+            widget.markFinished(fgId)
+            fleet.onAgentFinished(fgId)
+          }
         }
 
         // Get final token count
@@ -2673,6 +2679,7 @@ ${systemPrompt}
       defaultJoinMode: getDefaultJoinMode(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
+      strictAgentFiles,
       disableDefaultAgents: isDefaultsDisabled(),
       toolDescriptionMode: getToolDescriptionMode(),
       fleetView: isFleetViewEnabled(),
@@ -2762,6 +2769,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 +2882,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/nested-tools.ts

@@ -399,47 +399,38 @@ export function createNestedSubagentTools(
       // one earlier would silently give a grandchild the wrong worktree base, the
       // wrong conversation under inherit_context, and the wrong inherited model.
       //
-      // spawn() throws on strict worktree-isolation failure and cwd validation —
-      // report it as a tool error, like the top-level Agent tool does, instead of
-      // letting it escape into the child's turn.
-      try {
-        if (invocation.runInBackground) {
-          const id = context.manager.spawn(
-            context.pi,
-            ctx,
-            resolvedType,
-            params.prompt,
-            {
-              ...options,
-              isBackground: true,
-            },
-          )
-          // Synchronous, before the event loop yields — onSessionCreated fires
-          // asynchronously inside runAgent, so the file is attached in time.
-          attachTranscript(id)
-          return textResult(
-            `Nested agent started in background. Agent ID: ${id}`,
-          )
-        }
-
-        const { record } = await context.manager.spawnAndWait(
+      // Startup throws mean no child ran. Let them propagate so Pi marks the
+      // nested Agent tool call failed instead of presenting the message as a
+      // successful child result.
+      if (invocation.runInBackground) {
+        const id = context.manager.spawn(
           context.pi,
           ctx,
           resolvedType,
           params.prompt,
-          { ...options, signal },
-          attachTranscript,
-        )
-        return textResult(
-          formatRecord(record, "inline"),
-          record.status === "error",
-        )
-      } catch (err) {
-        return textResult(
-          err instanceof Error ? err.message : String(err),
-          true,
+          {
+            ...options,
+            isBackground: true,
+          },
         )
+        // Synchronous, before the event loop yields — onSessionCreated fires
+        // asynchronously inside runAgent, so the file is attached in time.
+        attachTranscript(id)
+        return textResult(`Nested agent started in background. Agent ID: ${id}`)
       }
+
+      const { record } = await context.manager.spawnAndWait(
+        context.pi,
+        ctx,
+        resolvedType,
+        params.prompt,
+        { ...options, signal },
+        attachTranscript,
+      )
+      return textResult(
+        formatRecord(record, "inline"),
+        record.status === "error",
+      )
     },
   })
 

package/src/prompts.ts

@@ -10,6 +10,8 @@ export interface PromptExtras {
   memoryBlock?: string
   /** Preloaded skill contents to inject. */
   skillBlocks?: { name: string; content: string }[]
+  /** Original checkout path when cwd is an isolated worktree copy. */
+  worktreeBase?: string
 }
 
 /**
@@ -55,6 +57,12 @@ Platform: ${env.platform}`
   }
   const extrasSuffix =
     extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : ""
+  const worktreeSection = extras?.worktreeBase
+    ? `\n\n<worktree_isolation>
+Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
+Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
+</worktree_isolation>`
+    : ""
 
   if (config.promptMode === "append") {
     const identity = parentSystemPrompt || genericBase
@@ -88,6 +96,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       "\n\n" +
       activeAgentTag +
       envBlock +
+      worktreeSection +
       customSection +
       extrasSuffix
     )
@@ -100,7 +109,12 @@ You have been invoked to handle a specific task autonomously.
 ${envBlock}`
 
   return (
-    activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix
+    activeAgentTag +
+    replaceHeader +
+    worktreeSection +
+    "\n\n" +
+    config.systemPrompt +
+    extrasSuffix
   )
 }
 

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"