@johnnywu/pi-subagents 2.1.1 → 2.2.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.2.1](https://github.com/jwu/pi-subagents/compare/v2.2.0...v2.2.1) (2026-08-24)
+
+
+### Bug Fixes
+
+* support bundled pi CLI invocation ([0651956](https://github.com/jwu/pi-subagents/commit/065195604d1d3b54ea2810f10d20049c4023daf9))
+
+# [2.2.0](https://github.com/jwu/pi-subagents/compare/v2.1.1...v2.2.0) (2026-08-06)
+
+
+### Features
+
+* inject runtime tools automatically ([eac6f01](https://github.com/jwu/pi-subagents/commit/eac6f01b4f27e463cba7623fede2602498de421d))
+
 ## [2.1.1](https://github.com/jwu/pi-subagents/compare/v2.1.0...v2.1.1) (2026-07-21)
 
 

package/README.md

@@ -51,14 +51,18 @@ Run the code-reviewer agent on the last three commits
 By default, sub-agents do not inherit parent conversation history. For tasks that need the current conversation, request a forked session:
 
 ```ts
-subagent({ agent: "code-reviewer", task: "Review the approach we just discussed", session: "fork" })
+subagent({
+  agent: 'code-reviewer',
+  task: 'Review the approach we just discussed',
+  session: 'fork',
+});
 ```
 
 `session` is optional and accepts:
 
-| Value | Behavior |
-|-------|----------|
-| `none` | Default. Start a new sub-agent session in the subagents session directory. |
+| Value  | Behavior                                                                                             |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| `none` | Default. Start a new sub-agent session in the subagents session directory.                           |
 | `fork` | Fork the current parent session at its active leaf and run the sub-agent with that branched session. |
 
 If `fork` is requested but unavailable, pi-subagents falls back to `none` and shows a warning in the tool details/rendering. Fallback happens when the parent session is not persisted, has no current leaf, the forked session file is not materialized, or the call uses a `cwd` different from the parent session cwd.
@@ -84,22 +88,24 @@ The prompt file passed to the child process contains only the agent prompt plus
 
 ### What goes into the sub-agent system prompt
 
-| Component | `append` | `replace` | `replace-all` |
-|------|----------|-----------|---------------|
-| pi default system prompt | ✅ kept | ❌ replaced | ❌ replaced |
-| Project context files (AGENTS.md/CLAUDE.md, etc.) | ✅ included | ✅ included | ❌ skipped |
-| Agent body (.md file body) | ✅ appended | ✅ becomes the prompt | ✅ becomes the prompt |
-| Skills XML block | ✅ appended | ✅ appended | ✅ appended |
-| Available tools / Guidelines block | from default prompt | re-injected by `before_agent_start` hook | re-injected by `before_agent_start` hook |
-| Available subagents block | injected at agent start | injected at agent start | injected at agent start |
+| Component                                         | `append`                                    | `replace`                                     | `replace-all`                                 |
+| ------------------------------------------------- | ------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
+| pi default system prompt                          | ✅ kept                                     | ❌ replaced                                   | ❌ replaced                                   |
+| Project context files (AGENTS.md/CLAUDE.md, etc.) | ✅ included                                 | ✅ included                                   | ❌ skipped                                    |
+| Agent body (.md file body)                        | ✅ appended                                 | ✅ becomes the prompt                         | ✅ becomes the prompt                         |
+| Skills XML block                                  | ✅ appended                                 | ✅ appended                                   | ✅ appended                                   |
+| Available tools / Guidelines block                | from default prompt                         | automatically injected after agent body        | automatically injected after agent body        |
+| Available subagents                               | supplied by active `subagent` tool metadata | supplied by active `subagent` tool metadata   | supplied by active `subagent` tool metadata   |
 
-`append` keeps pi's full default prompt (with project context) and adds the agent body at the end.
+`append` keeps pi's default prompt and its built-in tools/guidelines block. The agent body and its skills block are appended before pi project context.
 `replace` swaps out pi's default prompt for the agent body while keeping pi context files.
-`replace-all` is the fully isolated mode: it swaps out pi's default prompt and skips pi context files, then the runtime hook re-injects tool and guideline blocks to preserve tool visibility.
+`replace-all` is the fully isolated mode: it swaps out pi's default prompt and skips pi context files.
+
+For `replace` and `replace-all`, pi-subagents automatically injects Pi's runtime `Available tools` and `Guidelines` blocks after the agent body and before its skills block. Agent definitions do not need a placeholder.
 
 Breaking change: the old `replace` behavior is now `replace-all`. Existing agents that need to keep skipping AGENTS.md/CLAUDE.md should change `systemPrompt: replace` to `systemPrompt: replace-all`.
 
-The `Available subagents` block is injected by the child process at agent-start time, after `PI_SUBAGENT_ALLOWED` and recursion depth filtering are applied.
+Available subagents are supplied through the active `subagent` tool's `promptGuidelines`, after `PI_SUBAGENT_ALLOWED` and recursion depth filtering are applied.
 
 ### Debug a sub-agent prompt
 
@@ -112,24 +118,24 @@ debug: true
 ---
 ```
 
-The child process writes `debug-system-prompt.md` in the project cwd. The file contains the prompt visible during `before_agent_start`, including `systemPrompt` append/replace/replace-all behavior, tools/guidelines, skills, project context files in append and replace modes, and pi-subagents' runtime `Available subagents` block when applicable.
+The child process writes `debug-system-prompt.md` in the project cwd. The file contains the prompt visible during `before_agent_start`, including `systemPrompt` append/replace/replace-all behavior, tools/guidelines, skills, project context files in append and replace modes, and active tool prompt metadata.
 
 ## Agent configuration
 
 Agents are Markdown files with YAML frontmatter.
 
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `name` | **yes** | — | Unique agent identifier |
-| `description` | no | — | Human-readable summary |
-| `tools` | no | _none_ | Comma-separated tool whitelist (`read, write, bash, grep`, etc.) |
-| `model` | no | parent's model | Provider/model-id (`anthropic/claude-sonnet-4-6`) |
-| `thinking` | no | `off` | Reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
-| `systemPrompt` | no | `append` | How the body is applied: `append` (append to pi default system prompt and project context), `replace` (replace pi default prompt while keeping project context), or `replace-all` (replace pi default prompt and skip project context) |
-| `skills` | no | _none_ | Comma-separated skill names or simple wildcard patterns (`*`, `obsidian-*`) to load (resolved from project `.agents/skills/`, `.pi/skills/`, global `~/.pi/agent/skills/`, or npm packages) |
-| `allowedAgents` | no | _all_ | Comma-separated list of sub-agents this agent may spawn |
-| `maxDepth` | no | `10` | Maximum recursion depth (`0` = no sub-agents, `1` = one level, etc.) |
-| `debug` | no | `false` | When `true`, export the effective runtime system prompt to `debug-system-prompt.md` |
+| Field           | Required | Default        | Description                                                                                                                                                                                                                                                                                                             |
+| --------------- | -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`          | **yes**  | —              | Unique agent identifier                                                                                                                                                                                                                                                                                                 |
+| `description`   | no       | —              | Human-readable summary                                                                                                                                                                                                                                                                                                  |
+| `tools`         | no       | _none_         | Comma-separated tool whitelist (`read, write, bash, grep`, etc.)                                                                                                                                                                                                                                                        |
+| `model`         | no       | parent's model | Provider/model-id (`anthropic/claude-sonnet-4-6`)                                                                                                                                                                                                                                                                       |
+| `thinking`      | no       | `off`          | Reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`                                                                                                                                                                                                                                                     |
+| `systemPrompt`  | no       | `append`       | How the body is applied: `append` (append to pi default system prompt and project context), `replace` (replace pi default prompt while keeping project context), or `replace-all` (replace pi default prompt and skip project context). In `replace` modes, the runtime tools/guidelines block is injected automatically. |
+| `skills`        | no       | _none_         | Comma-separated skill names or simple wildcard patterns (`*`, `obsidian-*`) to load (resolved from project `.agents/skills/`, `.pi/skills/`, global `~/.pi/agent/skills/`, or npm packages)                                                                                                                             |
+| `allowedAgents` | no       | _all_          | Comma-separated list of sub-agents this agent may spawn                                                                                                                                                                                                                                                                 |
+| `maxDepth`      | no       | `10`           | Maximum recursion depth (`0` = no sub-agents, `1` = one level, etc.)                                                                                                                                                                                                                                                    |
+| `debug`         | no       | `false`        | When `true`, export the effective runtime system prompt to `debug-system-prompt.md`                                                                                                                                                                                                                                     |
 
 The Markdown body after the frontmatter is the agent's system prompt.
 
@@ -159,10 +165,10 @@ them to specialist agents. Combine their results and report a summary.
 
 Agents are discovered from two locations (project overrides global):
 
-| Scope | Path |
-|-------|------|
-| Global | `~/.pi/agent/agents/*.md` |
-| Project | `.pi/agents/*.md` |
+| Scope   | Path                      |
+| ------- | ------------------------- |
+| Global  | `~/.pi/agent/agents/*.md` |
+| Project | `.pi/agents/*.md`         |
 
 Only `.md` files are scanned. Files are parsed at extension load time; parse errors produce warnings but don't block other agents.
 

package/extensions/agent-loader.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { LEGACY_RUNTIME_TOOLS_MARKER } from './subagent-prompt.ts';
 
 export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 export type SystemPromptMode = 'replace' | 'replace-all' | 'append';
@@ -126,13 +127,14 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
     debug = data.debug === 'true';
   }
 
+  const tools = splitCsv(data.tools);
   const allowedAgents = splitCsv(data.allowedAgents);
   const skills = splitCsv(data.skills);
 
   return {
     name: data.name,
     description: data.description,
-    tools: splitCsv(data.tools),
+    tools,
     skills: skills.length > 0 ? skills : undefined,
     model: data.model || undefined,
     thinking,
@@ -140,7 +142,7 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
     allowedAgents: allowedAgents.length > 0 ? allowedAgents : undefined,
     maxDepth,
     debug,
-    prompt: body,
+    prompt: body.replaceAll(LEGACY_RUNTIME_TOOLS_MARKER, ''),
     source,
     filePath,
   };

package/extensions/index.ts

@@ -2,11 +2,8 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { loadAgentDefinitions } from './agent-loader.ts';
-import { allowedAgentNames, isPastMaxDepth, isSubagentReplaceSystemPrompt } from './env-utils.ts';
-import {
-  appendAvailableSubagentsBlock,
-  appendAvailableToolsAndGuidelinesBlock,
-} from './subagent-prompt.ts';
+import { isSubagentReplaceSystemPrompt } from './env-utils.ts';
+import { injectRuntimeToolsBlock } from './subagent-prompt.ts';
 import { registerSubagentTool } from './subagent-tool.ts';
 
 export default async function (pi: ExtensionAPI) {
@@ -16,31 +13,27 @@ export default async function (pi: ExtensionAPI) {
     console.warn(`[pi-subagents] skipped ${warning.filePath}: ${warning.message}`);
   }
 
-  const allowed = allowedAgentNames(process.env);
-  const agents = allowed
-    ? result.agents.filter((candidate) => allowed.has(candidate.name))
-    : result.agents;
-  const agentNames = agents.map((agent) => agent.name);
+  const registerScopedSubagentTool = (allowedAgents?: readonly string[]) => {
+    registerSubagentTool(pi, { agents: result.agents, allowedAgents });
+  };
 
   if (isSubagentReplaceSystemPrompt(process.env)) {
-    pi.on('before_agent_start', (event) => {
-      return {
-        systemPrompt: appendAvailableToolsAndGuidelinesBlock(
-          event.systemPrompt,
-          event.systemPromptOptions,
-        ),
-      };
-    });
+    pi.on('before_agent_start', (event) => ({
+      systemPrompt: injectRuntimeToolsBlock(event.systemPrompt, event.systemPromptOptions),
+    }));
   }
 
-  if (!isPastMaxDepth(process.env) && agentNames.length > 0) {
-    pi.on('before_agent_start', (event) => {
-      if (!event.systemPromptOptions.selectedTools?.includes('subagent')) return;
-      return {
-        systemPrompt: appendAvailableSubagentsBlock(event.systemPrompt, agentNames),
-      };
-    });
-  }
+  pi.events.on('pi-subagents:configure', (configuration: unknown) => {
+    const allowedAgents =
+      configuration &&
+      typeof configuration === 'object' &&
+      Array.isArray((configuration as { allowedAgents?: unknown }).allowedAgents)
+        ? (configuration as { allowedAgents: unknown[] }).allowedAgents.filter(
+            (name): name is string => typeof name === 'string',
+          )
+        : undefined;
+    registerScopedSubagentTool(allowedAgents);
+  });
 
   if (process.env.PI_SUBAGENT_DEBUG === 'true') {
     pi.on('before_agent_start', (_event, ctx) => {
@@ -50,5 +43,5 @@ export default async function (pi: ExtensionAPI) {
     });
   }
 
-  registerSubagentTool(pi, { agents: result.agents });
+  registerScopedSubagentTool();
 }

package/extensions/subagent-executor.ts

@@ -6,9 +6,10 @@ import {
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
+import { existsSync } from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import type { AgentConfig } from './agent-loader.ts';
+import { AUTO_RUNTIME_TOOLS_MARKER } from './subagent-prompt.ts';
 import { resolveSkills } from './skill-resolver.ts';
 
 export interface AgentUsage {
@@ -58,7 +59,13 @@ export interface AgentResult extends AgentProgress {
 
 export interface PiResolution {
   command: string;
-  entryPoint: string;
+  entryPoint: string | null;
+}
+
+export interface PiRuntime {
+  currentScript?: string;
+  execPath: string;
+  fileExists(filePath: string): boolean;
 }
 
 export interface ProcessInvocation {
@@ -170,14 +177,25 @@ export function subagentSessionDir(
   return path.join(agentDir, 'sessions', safeProject, 'subagents');
 }
 
-export function resolvePiEntryPoint(): PiResolution {
-  const packageEntryPoint = fileURLToPath(import.meta.resolve('@earendil-works/pi-coding-agent'));
-  const packageRoot = path.dirname(path.dirname(packageEntryPoint));
+export function resolvePiEntryPoint(
+  runtime: PiRuntime = {
+    currentScript: process.argv[1],
+    execPath: process.execPath,
+    fileExists: existsSync,
+  },
+): PiResolution {
+  const currentScript = runtime.currentScript;
+  const isBunVirtualScript = currentScript?.startsWith('/$bunfs/root/');
 
-  return {
-    command: process.execPath,
-    entryPoint: path.join(packageRoot, 'dist', 'cli.js'),
-  };
+  if (currentScript && !isBunVirtualScript && runtime.fileExists(currentScript)) {
+    return { command: runtime.execPath, entryPoint: currentScript };
+  }
+
+  const execName = path.basename(runtime.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) return { command: runtime.execPath, entryPoint: null };
+
+  return { command: 'pi', entryPoint: null };
 }
 
 export const defaultRunner: ProcessRunner = (invocation, handlers, signal) =>
@@ -380,6 +398,12 @@ export async function buildSubagentSystemPrompt(
   options: BuildSubagentSystemPromptOptions,
 ): Promise<BuildSubagentSystemPromptResult> {
   let prompt = options.agent.prompt;
+  if (
+    options.agent.systemPromptMode === 'replace' ||
+    options.agent.systemPromptMode === 'replace-all'
+  ) {
+    prompt = `${prompt}\n\n${AUTO_RUNTIME_TOOLS_MARKER}`;
+  }
 
   const missingSkills: string[] = [];
   const skippedSkillPackages: string[] = [];
@@ -476,7 +500,14 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       modelsPath: options.agentDir ? path.join(options.agentDir, 'models.json') : undefined,
     });
     const modelRegistry = new ModelRegistry(runtime);
-    const args = [pi.entryPoint, '--mode', 'json', '-p', '--no-skills', '--no-prompt-templates'];
+    const args = [
+      ...(pi.entryPoint ? [pi.entryPoint] : []),
+      '--mode',
+      'json',
+      '-p',
+      '--no-skills',
+      '--no-prompt-templates',
+    ];
 
     if (options.agent.systemPromptMode === 'replace-all') args.push('--no-context-files');
     if (options.agent.model) args.push('--model', options.agent.model);

package/extensions/subagent-prompt.ts

@@ -1,3 +1,6 @@
+export const AUTO_RUNTIME_TOOLS_MARKER = '<pi-subagents-runtime-tools />';
+export const LEGACY_RUNTIME_TOOLS_MARKER = '<pi-runtime-tools />';
+
 export interface ToolGuidelinePromptOptions {
   selectedTools?: string[];
   toolSnippets?: Record<string, string>;
@@ -50,38 +53,15 @@ export function formatAvailableToolsAndGuidelinesBlock(
   ].join('\n');
 }
 
-function appendBeforeTrailingRuntimeMetadata(systemPrompt: string, block: string): string {
-  const marker = '\nCurrent date:';
-  const index = systemPrompt.lastIndexOf(marker);
-  if (index === -1) return `${systemPrompt.trimEnd()}\n\n${block}`;
-
-  const before = systemPrompt.slice(0, index).trimEnd();
-  const after = systemPrompt.slice(index);
-  return `${before}\n\n${block}${after}`;
-}
-
-export function appendAvailableToolsAndGuidelinesBlock(
+export function injectRuntimeToolsBlock(
   systemPrompt: string,
   options: ToolGuidelinePromptOptions,
 ): string {
-  const block = formatAvailableToolsAndGuidelinesBlock(options);
-  if (!block || systemPrompt.includes(block)) {
-    return systemPrompt;
+  const block = formatAvailableToolsAndGuidelinesBlock(options) ?? '';
+  if (systemPrompt.includes(AUTO_RUNTIME_TOOLS_MARKER)) {
+    return systemPrompt
+      .replace(AUTO_RUNTIME_TOOLS_MARKER, block)
+      .replaceAll(LEGACY_RUNTIME_TOOLS_MARKER, '');
   }
-
-  return appendBeforeTrailingRuntimeMetadata(systemPrompt, block);
-}
-
-export function formatAvailableSubagentsBlock(agentNames: string[]): string | undefined {
-  const names = [...new Set(agentNames.map((name) => name.trim()).filter(Boolean))].sort();
-  if (names.length === 0) return undefined;
-
-  return ['Available subagents:', ...names.map((name) => `- ${name}`)].join('\n');
-}
-
-export function appendAvailableSubagentsBlock(systemPrompt: string, agentNames: string[]): string {
-  const block = formatAvailableSubagentsBlock(agentNames);
-  if (!block || systemPrompt.includes(block)) return systemPrompt;
-
-  return `${systemPrompt.trimEnd()}\n\n${block}`;
+  return systemPrompt.replace(LEGACY_RUNTIME_TOOLS_MARKER, block);
 }

package/extensions/subagent-tool.ts

@@ -59,6 +59,8 @@ export interface RegisterSubagentToolOptions {
   agents: AgentConfig[];
   run?: typeof runSubagent;
   env?: RecursionEnv;
+  /** Explicit allowlist for the current session. An empty list disables delegation. */
+  allowedAgents?: readonly string[];
   agentDir?: string;
 }
 
@@ -300,7 +302,8 @@ export function registerSubagentTool(
   const env: RecursionEnv = options.env ?? process.env;
   if (isPastMaxDepth(env)) return;
 
-  const allowed = allowedAgentNames(env);
+  const allowed =
+    options.allowedAgents === undefined ? allowedAgentNames(env) : new Set(options.allowedAgents);
   const agents = allowed
     ? options.agents.filter((candidate) => allowed.has(candidate.name))
     : options.agents;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnnywu/pi-subagents",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {
@@ -82,13 +82,14 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": ">=0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",