@esso0428/pi-subagents 0.17.5 → 0.17.7

package/dist/agent-types.js

@@ -6,7 +6,7 @@
  */
 import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-import { applyNicoOverridesToMap, readNicoAgentOverrides } from "./nico-overrides.js";
+import { applyNicoOverride, applyNicoOverridesToMap, readNicoAgentOverrides } from "./nico-overrides.js";
 /**
  * All known built-in tool names, derived from pi's own tool factories rather
  * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
@@ -26,6 +26,38 @@ let disableDefaults = false;
 export function isDefaultsDisabled() { return disableDefaults; }
 /** Set whether default agents are disabled. */
 export function setDefaultsDisabled(b) { disableDefaults = b; }
+/** `fallbackSubagent` value that disables the fallback entirely (strict dispatch). */
+export const NO_FALLBACK = "none";
+/**
+ * Agent type substituted when a caller-supplied `subagent_type` doesn't resolve
+ * to exactly one enabled agent. `undefined` keeps the historical behavior
+ * (general-purpose); `NO_FALLBACK` makes dispatch fail closed. Set from
+ * `subagents.json` (`fallbackSubagent`).
+ *
+ * Module state rather than an index.ts closure because every caller-supplied
+ * spawn path needs it — the Agent tool, the scheduler, and cross-extension RPC.
+ */
+let fallbackSubagent;
+/** Get the configured fallback agent type. undefined = general-purpose. */
+export function getFallbackSubagent() { return fallbackSubagent; }
+/** Set the configured fallback agent type. undefined = general-purpose. */
+export function setFallbackSubagent(v) { fallbackSubagent = v; }
+/**
+ * Build a registry map: DEFAULT_AGENTS first (unless disabled via settings),
+ * then user agents overlaid on top (same name overrides the default).
+ * Pure — callers that must not disturb the process-wide registry (nested
+ * delegation resolving agents from its own config root) build their own map.
+ */
+export function buildAgentRegistry(userAgents) {
+    const registry = new Map();
+    if (!disableDefaults) {
+        for (const [name, config] of DEFAULT_AGENTS)
+            registry.set(name, config);
+    }
+    for (const [name, config] of userAgents)
+        registry.set(name, config);
+    return registry;
+}
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -33,52 +65,153 @@ export function setDefaultsDisabled(b) { disableDefaults = b; }
  */
 export function registerAgents(userAgents) {
     agents.clear();
-    // Start with defaults (unless disabled via settings)
-    if (!disableDefaults) {
-        for (const [name, config] of DEFAULT_AGENTS) {
-            agents.set(name, config);
-        }
-    }
-    // Overlay user agents (overrides defaults with same name)
-    for (const [name, config] of userAgents) {
+    for (const [name, config] of buildAgentRegistry(userAgents)) {
         agents.set(name, config);
     }
-}
-/**
- * Apply npm:pi-subagents-style JSON overrides to the current agent registry.
- * Reads from ~/.pi/agent/settings.json and .pi/settings.json and applies
- * them as the highest-priority layer. Auto-registers agents that don't
- * exist in the registry yet.
- */
-export function applyNicoOverrides() {
     const { overrides, defaultModel } = readNicoAgentOverrides(process.cwd());
-    applyNicoOverridesToMap(agents, overrides, defaultModel);
+    if (!disableDefaults) {
+        applyNicoOverridesToMap(agents, overrides, defaultModel);
+    }
+    else {
+        // Disabling built-ins must also prevent JSON-only built-ins from being
+        // synthesized; explicit user agents remain eligible for their overrides.
+        for (const [name, config] of agents) {
+            const override = overrides[name];
+            if (override)
+                agents.set(name, applyNicoOverride(config, override, defaultModel));
+        }
+    }
 }
-/** Case-insensitive key resolution. */
-function resolveKey(name) {
-    if (agents.has(name))
+/** Case-insensitive key resolution within a registry. */
+function resolveKeyIn(registry, name) {
+    if (registry.has(name))
         return name;
     const lower = name.toLowerCase();
-    for (const key of agents.keys()) {
+    for (const key of registry.keys()) {
         if (key.toLowerCase() === lower)
             return key;
     }
     return undefined;
 }
+/** Case-insensitive key resolution. */
+function resolveKey(name) {
+    return resolveKeyIn(agents, name);
+}
+/** Resolve a type name case-insensitively in a registry. Returns the canonical key or undefined. */
+export function resolveTypeIn(registry, name) {
+    return resolveKeyIn(registry, name);
+}
+/** Get the agent config for a type (case-insensitive) from a registry. */
+export function getAgentConfigIn(registry, name) {
+    const key = resolveKeyIn(registry, name);
+    return key ? registry.get(key) : undefined;
+}
+/** Check if a type is valid and enabled (case-insensitive) in a registry. */
+export function isValidTypeIn(registry, type) {
+    const key = resolveKeyIn(registry, type);
+    if (!key)
+        return false;
+    return registry.get(key)?.enabled !== false;
+}
+/** Get all enabled type names in a registry (for spawning and tool descriptions). */
+export function getAvailableTypesIn(registry) {
+    return [...registry.entries()]
+        .filter(([_, config]) => config.enabled !== false)
+        .map(([name]) => name);
+}
+/**
+ * Case-insensitive resolution that refuses to guess. An exact match always wins;
+ * otherwise the name must match exactly one key. Two agents differing only in
+ * case are reachable (`loadCustomAgents` keys by filename across three
+ * directories), and picking whichever came first would silently dispatch a
+ * different agent, model and tool policy than the caller meant.
+ */
+function resolveUnambiguousKeyIn(registry, name) {
+    if (registry.has(name))
+        return name;
+    const lower = name.toLowerCase();
+    const matches = [...registry.keys()].filter(key => key.toLowerCase() === lower);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * The canonical key for a caller-supplied name that identifies exactly one
+ * ENABLED agent, or undefined. Strict by construction: no fallback, no guessing
+ * between case-variants. Nested delegation resolves with this directly, since
+ * "unknown types are rejected rather than falling back" is its own contract.
+ */
+export function resolveEnabledTypeIn(registry, requested) {
+    const raw = typeof requested === "string" ? requested.trim() : "";
+    if (!raw)
+        return undefined;
+    const key = resolveUnambiguousKeyIn(registry, raw);
+    return key !== undefined && registry.get(key)?.enabled !== false ? key : undefined;
+}
+/**
+ * Resolve a caller-supplied agent type against a registry, applying the
+ * `fallbackSubagent` policy. The single decision point for every caller-supplied
+ * spawn — the Agent tool, the scheduler, cross-extension RPC, and the nested
+ * tools — so a type that fails here never reaches `runAgent`, where `getConfig`
+ * would silently substitute general-purpose.
+ *
+ * Unknown, disabled, and case-ambiguous names are all treated the same way:
+ * the caller named something that doesn't identify exactly one enabled agent.
+ *
+ * Pure over `registry` — callers that need fresh agent files reload before
+ * calling (the Agent tool already does, per spawn). Reloading here would mean
+ * importing custom-agents.ts, which imports this module.
+ */
+export function resolveSpawnTypeIn(registry, requested) {
+    const raw = typeof requested === "string" ? requested.trim() : "";
+    const available = () => getAvailableTypesIn(registry).join(", ") || "(none)";
+    const key = resolveEnabledTypeIn(registry, raw);
+    if (key !== undefined)
+        return { ok: true, type: key };
+    // A missing type follows the same policy as a wrong one rather than always
+    // erroring: before this setting existed an empty type fell back like any
+    // other unresolvable name, and only opting in should change that.
+    const reason = raw ? `Unknown or disabled agent type: "${raw}".` : "No agent type given.";
+    // Trimmed like `requested`: a padded value set programmatically would
+    // otherwise be reported as a missing agent.
+    const configured = typeof fallbackSubagent === "string" ? fallbackSubagent.trim() : undefined;
+    if (configured !== undefined && configured.toLowerCase() === NO_FALLBACK) {
+        return { ok: false, message: `${reason} Available: ${available()}.` };
+    }
+    if (configured !== undefined) {
+        // An explicitly configured fallback that is itself unusable is a
+        // misconfiguration, not a second chance to guess — say so rather than
+        // quietly dropping to general-purpose.
+        const fallbackKey = resolveUnambiguousKeyIn(registry, configured);
+        if (fallbackKey === undefined || registry.get(fallbackKey)?.enabled === false) {
+            return {
+                ok: false,
+                message: `${reason} The configured fallbackSubagent "${configured}" is itself ` +
+                    `unknown or disabled. Available: ${available()}.`,
+            };
+        }
+        return { ok: true, type: fallbackKey, fellBackFrom: raw };
+    }
+    // Unset: historical behavior, deliberately unchanged. #183 asks for the
+    // fallback to remain the default, so the pre-existing hole it leaves — an
+    // unregistered general-purpose resolving to `getConfig`'s all-tools hardcoded
+    // tier — is what `fallbackSubagent: none` is for, not something to close
+    // under everyone silently.
+    return { ok: true, type: "general-purpose", fellBackFrom: raw };
+}
+/** Resolve a caller-supplied agent type against the process-wide registry. */
+export function resolveSpawnType(requested) {
+    return resolveSpawnTypeIn(agents, requested);
+}
 /** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
 export function resolveType(name) {
     return resolveKey(name);
 }
 /** Get the agent config for a type (case-insensitive). */
 export function getAgentConfig(name) {
-    const key = resolveKey(name);
-    return key ? agents.get(key) : undefined;
+    return getAgentConfigIn(agents, name);
 }
 /** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes() {
-    return [...agents.entries()]
-        .filter(([_, config]) => config.enabled !== false)
-        .map(([name]) => name);
+    return getAvailableTypesIn(agents);
 }
 /** Get all type names including disabled (for UI listing). */
 export function getAllTypes() {
@@ -93,15 +226,12 @@ export function getDefaultAgentNames() {
 /** Get names of user-defined agents (non-defaults) currently in the registry. */
 export function getUserAgentNames() {
     return [...agents.entries()]
-        .filter(([_, config]) => config.isDefault !== true)
+        .filter(([_, config]) => config.isDefault !== true && !config.description.startsWith("Auto-registered from npm:pi-subagents JSON settings"))
         .map(([name]) => name);
 }
 /** Check if a type is valid and enabled (case-insensitive). */
 export function isValidType(type) {
-    const key = resolveKey(type);
-    if (!key)
-        return false;
-    return agents.get(key)?.enabled !== false;
+    return isValidTypeIn(agents, type);
 }
 /** Tool names required for memory management. */
 const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
@@ -135,6 +265,7 @@ export function getConfig(type) {
     if (config && config.enabled !== false) {
         return {
             displayName: config.displayName ?? config.name,
+            color: config.color,
             description: config.description,
             builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: config.extensions,
@@ -148,6 +279,7 @@ export function getConfig(type) {
     if (gp && gp.enabled !== false) {
         return {
             displayName: gp.displayName ?? gp.name,
+            color: gp.color,
             description: gp.description,
             builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: gp.extensions,

package/dist/agent-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../src/agent-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../src/agent-types.ts"],"names":[],"mappings":"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"}

package/dist/child-context.d.ts

@@ -0,0 +1,3 @@
+export declare function inChildSessionContext(): boolean;
+export declare function runInChildSessionContext<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=child-context.d.ts.map

package/dist/child-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-context.d.ts","sourceRoot":"","sources":["../src/child-context.ts"],"names":[],"mappings":"AAQA,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE5E"}

package/dist/child-context.js

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Marks resource loading/session construction performed for a subagent. This is
+ * async-context-local so concurrent top-level extension work is unaffected.
+ */
+const childSessionContext = new AsyncLocalStorage();
+export function inChildSessionContext() {
+    return childSessionContext.getStore() === true;
+}
+export function runInChildSessionContext(fn) {
+    return childSessionContext.run(true, fn);
+}
+//# sourceMappingURL=child-context.js.map

package/dist/child-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-context.js","sourceRoot":"","sources":["../src/child-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;GAGG;AACH,MAAM,mBAAmB,GAAG,IAAI,iBAAiB,EAAW,CAAC;AAE7D,MAAM,UAAU,qBAAqB;IACnC,OAAO,mBAAmB,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAI,EAAoB;IAC9D,OAAO,mBAAmB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/cross-extension-rpc.d.ts

@@ -1,13 +1,18 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
+ * Exposes ping, spawn, stop, and consume RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
  *
  * Reply envelope follows pi-mono convention:
  *   success → { success: true, data?: T }
  *   error   → { success: false, error: string }
+ *
+ * @see docs/rpc.md — the caller-facing integration reference: spawn options
+ * (including the fields spawnTopLevel strips), every error string, the
+ * completion-notification race, and what protocol version 2 does not promise.
  */
+import type { AgentRecord } from "./types.js";
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
     on(event: string, handler: (data: unknown) => void): () => void;
@@ -23,10 +28,24 @@ export type RpcReply<T = void> = {
 };
 /** RPC protocol version — bumped when the envelope or method contracts change. */
 export declare const PROTOCOL_VERSION = 2;
-/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
+/** Minimal AgentManager interface needed by the spawn/stop/consume RPCs. */
 export interface SpawnCapable {
     spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+    /** Resolves once the spawned agent is running; rejects on a startup failure. */
+    awaitStartup(id: string): Promise<void>;
     abort(id: string): boolean;
+    /**
+     * The record behind an id, for the stop handler's ownership check. Narrowed
+     * to the two fields `isTopLevelAgent` reads, so the RPC layer keeps its
+     * deliberately shallow view of the manager.
+     */
+    getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId"> | undefined;
+    /**
+     * Mark a settled agent's result as read by the caller, suppressing the
+     * completion notification — what `get_subagent_result` does when it returns
+     * one. False when there is no such agent, or it has not settled yet.
+     */
+    consumeResult(id: string): boolean;
 }
 export interface RpcDeps {
     events: EventBus;
@@ -38,9 +57,10 @@ export interface RpcHandle {
     unsubPing: () => void;
     unsubSpawn: () => void;
     unsubStop: () => void;
+    unsubConsume: () => void;
 }
 /**
- * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Register ping, spawn, stop, and consume RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export declare function registerRpcHandlers(deps: RpcDeps): RpcHandle;

package/dist/cross-extension-rpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-extension-rpc.d.ts","sourceRoot":"","sources":["../src/cross-extension-rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED,gEAAgE;AAChE,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,IAAI,IACzB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,MAAM,CAAC;IACrF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IAClC,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AA0BD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CA+C5D"}
+{"version":3,"file":"cross-extension-rpc.d.ts","sourceRoot":"","sources":["../src/cross-extension-rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED,gEAAgE;AAChE,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,IAAI,IACzB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,MAAM,CAAC;IACrF,gFAAgF;IAChF,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,YAAY,CAAC,GAAG,SAAS,CAAC;IACrF;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IAClC,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AA0BD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAqG5D"}

package/dist/cross-extension-rpc.js

@@ -1,14 +1,20 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
+ * Exposes ping, spawn, stop, and consume RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
  *
  * Reply envelope follows pi-mono convention:
  *   success → { success: true, data?: T }
  *   error   → { success: false, error: string }
+ *
+ * @see docs/rpc.md — the caller-facing integration reference: spawn options
+ * (including the fields spawnTopLevel strips), every error string, the
+ * completion-notification race, and what protocol version 2 does not promise.
  */
+import { isTopLevelAgent } from "./agent-manager.js";
 import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
 /** RPC protocol version — bumped when the envelope or method contracts change. */
 export const PROTOCOL_VERSION = 2;
 /**
@@ -33,7 +39,7 @@ function handleRpc(events, channel, fn) {
     });
 }
 /**
- * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Register ping, spawn, stop, and consume RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps) {
@@ -41,7 +47,7 @@ export function registerRpcHandlers(deps) {
     const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
         return { version: PROTOCOL_VERSION };
     });
-    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", async ({ type, prompt, options }) => {
         const ctx = getCtx();
         if (!ctx)
             throw new Error("No active session");
@@ -52,26 +58,82 @@ export function registerRpcHandlers(deps) {
         // agent's auth lookup doesn't crash with "No API key found for
         // undefined".
         let normalizedOptions = options ?? {};
-        if (typeof normalizedOptions.model === "string") {
-            const registry = ctx.modelRegistry;
-            if (!registry) {
-                throw new Error(`Model override "${normalizedOptions.model}" provided but ctx.modelRegistry is unavailable`);
+        // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
+        // field as null, and the runner reads `options.model ?? default`, so null
+        // means "inherit" — not an override to resolve or scope-check.
+        const override = normalizedOptions.model;
+        if (override != null) {
+            const { modelRegistry, cwd } = ctx;
+            // Names the override the same way in both messages below; an object
+            // override would otherwise interpolate as "[object Object]".
+            const label = typeof override === "string" ? override : `${override.provider}/${override.id}`;
+            if (!modelRegistry) {
+                throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
             }
-            const resolved = resolveModel(normalizedOptions.model, registry);
-            if (typeof resolved === "string") {
-                // resolveModel returns a human-readable error string when the
-                // input doesn't match any available model. Surface it instead of
-                // silently falling back so the caller sees the auth/typo issue.
-                throw new Error(resolved);
+            let model = override;
+            if (typeof override === "string") {
+                const resolved = resolveModel(override, modelRegistry);
+                if (typeof resolved === "string") {
+                    // resolveModel returns a human-readable error string when the
+                    // input doesn't match any available model. Surface it instead of
+                    // silently falling back so the caller sees the auth/typo issue.
+                    throw new Error(resolved);
+                }
+                model = resolved;
+                normalizedOptions = { ...normalizedOptions, model: resolved };
             }
-            normalizedOptions = { ...normalizedOptions, model: resolved };
+            // A model on the RPC payload is an orchestrator-level choice, exactly
+            // like Agent({ model }) — so it gets the Agent tool's hard error, never
+            // the frontmatter warn (#240). The check reads the RESOLVED model:
+            // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
+            // caller never named. Frontmatter-pinned and parent-inherited models are
+            // resolved later, in agent-runner, and keep warn-and-proceed.
+            const verdict = checkModelScope({
+                model,
+                cwd: cwd ?? process.cwd(),
+                modelRegistry,
+                callerSupplied: true,
+                agentLabel: type,
+                modelInput: label,
+            });
+            if (verdict.kind === "error")
+                throw new Error(verdict.message);
         }
-        return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
+        const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);
+        // With isolation: "worktree" the agent starts asynchronously — wait for
+        // it, so a strict-isolation failure is still an error envelope rather
+        // than an id for an agent that never ran.
+        await manager.awaitStartup(id);
+        return { id };
     });
     const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
-        if (!manager.abort(agentId))
+        const record = manager.getRecord(agentId);
+        if (!record)
             throw new Error("Agent not found");
+        // Only the session's own agents are this RPC's to stop. A nested child or
+        // a workflow's agent is owned by something that is *waiting on it*, and
+        // aborting it out from under that owner turns another extension's stop
+        // into a failed step here. Defence in depth rather than a live hole: no
+        // RPC hands out agent ids, so a caller has no ordinary way to name one it
+        // does not own — but the guard is cheap and the id may leak some other
+        // way. Same refuse-what-we-should-not-touch stance as `consume` below.
+        if (!isTopLevelAgent(record))
+            throw new Error("Agent is owned by another agent or workflow");
+        // Not "not found" — the lookup above already proved it exists. `abort`
+        // returns false only for a record that is neither running nor queued,
+        // which is an agent that has already finished.
+        if (!manager.abort(agentId))
+            throw new Error("Agent is not running");
+    });
+    // A caller that has already shown the model an agent's result — pi-tasks'
+    // TaskOutput is the one in practice — says so here, so the completion
+    // notification for that same result is not delivered on top of it and does
+    // not cost the parent a turn. Deliberately outside the ping version
+    // handshake: an extension built against protocol v2 simply never calls it.
+    const unsubConsume = handleRpc(events, "subagents:rpc:consume", ({ agentId }) => {
+        if (!manager.consumeResult(agentId))
+            throw new Error("Agent not found or still running");
     });
-    return { unsubPing, unsubSpawn, unsubStop };
+    return { unsubPing, unsubSpawn, unsubStop, unsubConsume };
 }
 //# sourceMappingURL=cross-extension-rpc.js.map

package/dist/cross-extension-rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-extension-rpc.js","sourceRoot":"","sources":["../src/cross-extension-rpc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cross-extension-rpc.js","sourceRoot":"","sources":["../src/cross-extension-rpc.ts"],"names":[],"mappings":"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"}

package/dist/custom-agents.d.ts

@@ -13,6 +13,43 @@ import type { AgentConfig } from "./types.js";
  * between the two project locations, .pi/agents wins — .pi stays the project
  * authority; .agents/agents is an additional read location.
  * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ *
+ * An agent's type comes from its frontmatter `name:`, falling back to the
+ * filename — Claude Code's rule, where "the filename doesn't have to match".
+ * Because the type is now declared rather than derived from a unique path, two
+ * files can claim the same one; the later load wins, as it always has for a
+ * filename clash, and `warnSkippedOverride` reports the substitution.
+ */
+export declare function loadCustomAgents(cwd: string, strict?: boolean): Map<string, AgentConfig>;
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. One bad file must not take the whole extension down with it — an
+ * unparseable `.md` used to abort activation, so pi exited before the TUI.
+ *
+ * The path is as much of the fix as the recovery: a bare YAML error ("line 2,
+ * column 14") is unactionable when agents come from three directories at once,
+ * and the only other symptom is `Unknown agent type`, which reads like a typo.
+ *
+ * Under `strict` the same failure rethrows, still naming the path, so callers
+ * that opted into failing closed stop rather than run a substituted agent.
+ */
+/**
+ * Parse an agent file's frontmatter, tolerating a leading UTF-8 BOM.
+ *
+ * Editors across the Windows/CJK world write UTF-8 with a BOM by default, and
+ * pi's parser did not look past one before 0.84.3: the fence never matched, so
+ * the frontmatter came back empty and the *whole file* — YAML and all — became
+ * the body. An agent authored that way silently lost every field. `tools: none`
+ * going missing is the sharp edge: the agent registers with the default
+ * toolset rather than none, which is a wider grant than its author wrote.
+ *
+ * Stripped here rather than detected per pi version, because this is the only
+ * place agent files are read and the BOM is a file-encoding artifact, not
+ * content — normalising it at the boundary keeps one behaviour across the whole
+ * supported peer range instead of forking on what happens to be installed.
  */
-export declare function loadCustomAgents(cwd: string): Map<string, AgentConfig>;
+export declare function parseAgentFrontmatter<T extends Record<string, unknown>>(content: string): {
+    frontmatter: T;
+    body: string;
+};
 //# sourceMappingURL=custom-agents.d.ts.map

package/dist/custom-agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-agents.d.ts","sourceRoot":"","sources":["../src/custom-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAUtE"}
+{"version":3,"file":"custom-agents.d.ts","sourceRoot":"","sources":["../src/custom-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,WAAW,EAA6C,MAAM,YAAY,CAAC;AAiBzF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAatF;AAqFD;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAE1H"}