@tintinweb/pi-subagents 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-05-14
+
+### Added
+- **`<active_agent name="…"/>` tag prepended to every child system prompt** ([#73](https://github.com/tintinweb/pi-subagents/pull/73) — thanks [@chris-lasher](https://github.com/chris-lasher)). `buildAgentPrompt` now emits `<active_agent name="${config.name}"/>` as the first line of the assembled prompt in both `replace` and `append` modes, before the env block. Downstream extensions (e.g. permission/policy systems) can parse it from inside the child session to resolve per-agent policy. The tag uses the agent's `config.name` verbatim — no escaping or normalization — and does not couple this extension to any specific downstream consumer; ignoring it is harmless.
+
+### Changed
+- **Subagent sessions now get a stable, type-derived name with an id suffix for parallel spawns** ([#51](https://github.com/tintinweb/pi-subagents/pull/51) — thanks [@forcepushdev](https://github.com/forcepushdev)). `runAgent` calls `session.setSessionName(agentConfig?.name ?? type)`, and when the manager assigns an `agentId` (always, in production), the name is suffixed with an 8-char slice — e.g. `Explore#a1b2c3d4` — so concurrent spawns of the same agent type are distinguishable in the overlay instead of all collapsing onto the same bare name. Direct `runAgent` callers without an `agentId` (e.g. tests) get the bare name.
+
+### Fixed
+- **Cross-extension spawn RPC now accepts a string `options.model`** ([#59](https://github.com/tintinweb/pi-subagents/pull/59), fixes [#60](https://github.com/tintinweb/pi-subagents/issues/60)). Cross-extension callers (e.g. `@tintinweb/pi-tasks@>=0.4.3`'s `TaskExecute`) naturally forward `model` as a serializable `"provider/modelId"` string. Previously the spawn handler passed strings straight through to `runAgent()`, which expects a `Model` object — the spawned agent then crashed with `No API key found for undefined`. The handler now resolves strings via the same `resolveModel(ctx.modelRegistry)` path the scheduler uses; `Model` objects pass through unchanged. Unresolved strings surface the human-readable `Model not found: "…"` error instead of the auth-lookup crash. Thanks @any-victor.
+
 ## [0.7.2] - 2026-05-12
 
 > **Heads-up — behavior changes in skill preloading:**

package/README.md

@@ -406,6 +406,8 @@ pi.events.emit("subagents:rpc:spawn", {
 });
 ```
 
+`options.model` accepts either a `Model` object (e.g. `ctx.model`) or a `"provider/modelId"` string — strings are resolved against `ctx.modelRegistry` at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
+
 ### Stop
 
 Stop a running agent by ID:

package/dist/agent-manager.js

@@ -107,6 +107,7 @@ export class AgentManager {
         const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
         const promise = runAgent(ctx, type, prompt, {
             pi,
+            agentId: id,
             model: options.model,
             maxTurns: options.maxTurns,
             isolated: options.isolated,

package/dist/agent-runner.d.ts

@@ -23,6 +23,8 @@ export interface ToolActivity {
 export interface RunOptions {
     /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
     pi: ExtensionAPI;
+    /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
+    agentId?: string;
     model?: Model<any>;
     maxTurns?: number;
     signal?: AbortSignal;

package/dist/agent-runner.js

@@ -187,6 +187,8 @@ export async function runAgent(ctx, type, prompt, options) {
         sessionOpts.thinkingLevel = thinkingLevel;
     }
     const { session } = await createAgentSession(sessionOpts);
+    const baseSessionName = agentConfig?.name ?? type;
+    session.setSessionName(options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName);
     // Build disallowed tools set from agent config
     const disallowedSet = agentConfig?.disallowedTools
         ? new Set(agentConfig.disallowedTools)

package/dist/cross-extension-rpc.js

@@ -8,6 +8,7 @@
  *   success → { success: true, data?: T }
  *   error   → { success: false, error: string }
  */
+import { resolveModel } from "./model-resolver.js";
 /** RPC protocol version — bumped when the envelope or method contracts change. */
 export const PROTOCOL_VERSION = 2;
 /**
@@ -44,7 +45,28 @@ export function registerRpcHandlers(deps) {
         const ctx = getCtx();
         if (!ctx)
             throw new Error("No active session");
-        return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+        // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+        // forward serializable values, so options.model can be a string like
+        // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+        // — same pattern the scheduler path already uses — so the spawned
+        // 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`);
+            }
+            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);
+            }
+            normalizedOptions = { ...normalizedOptions, model: resolved };
+        }
+        return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
     });
     const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
         if (!manager.abort(agentId))

package/dist/prompts.d.ts

@@ -19,6 +19,10 @@ export interface PromptExtras {
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */

package/dist/prompts.js

@@ -8,10 +8,15 @@
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(config, cwd, env, parentSystemPrompt, extras) {
+    const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
     const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
@@ -44,14 +49,14 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+        return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
     }
     // "replace" mode — env header + the config's full system prompt
     const replaceHeader = `You are a pi coding agent sub-agent.
 You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
-    return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
+    return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */
 const genericBase = `# Role

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -183,6 +183,7 @@ export class AgentManager {
 
     const promise = runAgent(ctx, type, prompt, {
       pi,
+      agentId: id,
       model: options.model,
       maxTurns: options.maxTurns,
       isolated: options.isolated,

package/src/agent-runner.ts

@@ -88,6 +88,8 @@ export interface ToolActivity {
 export interface RunOptions {
   /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
   pi: ExtensionAPI;
+  /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
+  agentId?: string;
   model?: Model<any>;
   maxTurns?: number;
   signal?: AbortSignal;
@@ -280,6 +282,11 @@ export async function runAgent(
 
   const { session } = await createAgentSession(sessionOpts);
 
+  const baseSessionName = agentConfig?.name ?? type;
+  session.setSessionName(
+    options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
+  );
+
   // Build disallowed tools set from agent config
   const disallowedSet = agentConfig?.disallowedTools
     ? new Set(agentConfig.disallowedTools)

package/src/cross-extension-rpc.ts

@@ -9,6 +9,8 @@
  *   error   → { success: false, error: string }
  */
 
+import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
   on(event: string, handler: (data: unknown) => void): () => void;
@@ -81,7 +83,32 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
       const ctx = getCtx();
       if (!ctx) throw new Error("No active session");
-      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+
+      // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+      // forward serializable values, so options.model can be a string like
+      // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+      // — same pattern the scheduler path already uses — so the spawned
+      // 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 as { modelRegistry?: ModelRegistry }).modelRegistry;
+        if (!registry) {
+          throw new Error(
+            `Model override "${normalizedOptions.model}" 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);
+        }
+        normalizedOptions = { ...normalizedOptions, model: resolved };
+      }
+
+      return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
     },
   );
 

package/src/prompts.ts

@@ -19,6 +19,10 @@ export interface PromptExtras {
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
@@ -29,6 +33,8 @@ export function buildAgentPrompt(
   parentSystemPrompt?: string,
   extras?: PromptExtras,
 ): string {
+  const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+
   const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
@@ -66,7 +72,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 
-    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+    return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -75,7 +81,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
+  return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */