@johnnywu/pi-subagents 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# [1.3.0](https://github.com/jwu/pi-subagents/compare/v1.2.0...v1.3.0) (2026-06-02)
+
+
+### Bug Fixes
+
+* filter available subagents by allowed agents ([adc6025](https://github.com/jwu/pi-subagents/commit/adc60252d96ef532719a0da1c128a8e433c74bb7))
+* preserve append-mode subagent context ([ada0a26](https://github.com/jwu/pi-subagents/commit/ada0a264565d686917b73126301884345f824bce))
+
+
+### Features
+
+* add debug subagent prompt command ([1c49d43](https://github.com/jwu/pi-subagents/commit/1c49d43af9569856407e2a97d512d9d3b617e6d9))
+* default subagent prompts to append ([5693c17](https://github.com/jwu/pi-subagents/commit/5693c17b2aea4244b106bff82fe7ebd5c954322c))
+* export subagent debug prompts from frontmatter ([afe8b23](https://github.com/jwu/pi-subagents/commit/afe8b23700b9a86ef1db97463225cd828f884026))
+* resolve package skills for subagents ([48651e1](https://github.com/jwu/pi-subagents/commit/48651e15010c501cacec9a2e71771a13c0e7c9ab))
+
 # [1.2.0](https://github.com/jwu/pi-subagents/compare/v1.1.0...v1.2.0) (2026-06-02)
 
 

package/README.md

@@ -50,11 +50,11 @@ Run the code-reviewer agent on the last three commits
 
 ### Available subagents in the prompt
 
-The extension exposes discovered sub-agents to the model in two places:
+The extension exposes discovered sub-agents to the model when the active tool set includes `subagent`:
 
 - The `subagent` tool keeps a one-line prompt guideline:
   `Available subagents: code-reviewer, refactor, test-writer`
-- The system prompt also gets an independent block:
+- At agent-start time, the system prompt gets an independent block:
 
 ```text
 Available subagents:
@@ -63,7 +63,25 @@ Available subagents:
 - test-writer
 ```
 
-For sub-agents launched with `systemPrompt: replace` or `systemPrompt: append`, the same block is written into the prompt passed via `--system-prompt` or `--append-system-prompt` when that agent has the `subagent` tool.
+The prompt file passed to the child process contains only the agent prompt plus skills. Runtime prompt assembly then depends on `systemPrompt` mode:
+
+- `append`: the child process uses pi's default prompt and project context files, then appends the agent prompt.
+- `replace`: the child process replaces pi's default prompt with the agent prompt and skips project context files; pi-subagents reinjects the active `Available tools` and `Guidelines` blocks at agent-start time so custom replace prompts still expose the selected tool affordances.
+
+The `Available subagents` block is injected by the child process at agent-start time, after `PI_SUBAGENT_ALLOWED` and recursion depth filtering are applied.
+
+### Debug a sub-agent prompt
+
+Set `debug: true` in an agent's frontmatter to export that sub-agent's effective runtime system prompt on each run:
+
+```markdown
+---
+name: scout
+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 behavior, tools/guidelines, skills, project context files in append mode, and pi-subagents' runtime `Available subagents` block when applicable.
 
 ## Agent configuration
 
@@ -76,9 +94,10 @@ Agents are Markdown files with YAML frontmatter.
 | `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`, `low`, `medium`, `high` |
-| `systemPrompt` | no | `replace` | How the body is applied: `replace` (default system prompt) or `append` |
+| `systemPrompt` | no | `append` | How the body is applied: `append` (append to pi default system prompt and project context) or `replace` (replace default prompt and skip project context) |
 | `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.
 
@@ -91,9 +110,10 @@ description: High-level planner that delegates to specialists
 tools: subagent, read, grep, find
 model: anthropic/claude-sonnet-4-6
 thinking: high
-systemPrompt: replace
+systemPrompt: append
 allowedAgents: code-reviewer, refactor, test-writer
 maxDepth: 2
+debug: false
 ---
 
 You are an orchestrator. Break complex tasks into sub-tasks and delegate
@@ -121,7 +141,7 @@ Sub-agents can spawn their own sub-agents (if the `subagent` tool is in their wh
 
 The available-subagents prompt entries respect the same filtering: parent sessions use the currently visible agents, and child sessions only list agents allowed by their parent.
 
-These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`).
+These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`). Child processes also receive `PI_SUBAGENT_NAME` and `PI_SUBAGENT_SYSTEM_PROMPT_MODE` so runtime hooks can distinguish append vs. replace behavior.
 
 ## Session storage
 

package/extensions/agent-loader.ts

@@ -15,6 +15,7 @@ export interface AgentConfig {
   systemPromptMode: SystemPromptMode;
   allowedAgents?: string[];
   maxDepth: number;
+  debug: boolean;
   skills?: string[];
   prompt: string;
   source: AgentSource;
@@ -107,7 +108,7 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
     throw new Error(`invalid thinking: ${data.thinking}`);
   }
 
-  const systemPromptMode = (data.systemPrompt ?? 'replace') as SystemPromptMode;
+  const systemPromptMode = (data.systemPrompt ?? 'append') as SystemPromptMode;
   if (!['replace', 'append'].includes(systemPromptMode)) {
     throw new Error(`invalid systemPrompt: ${data.systemPrompt}`);
   }
@@ -117,6 +118,14 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
     throw new Error(`invalid maxDepth: ${data.maxDepth}`);
   }
 
+  let debug = false;
+  if (data.debug !== undefined) {
+    if (data.debug !== 'true' && data.debug !== 'false') {
+      throw new Error(`invalid debug: ${data.debug}`);
+    }
+    debug = data.debug === 'true';
+  }
+
   const allowedAgents = splitCsv(data.allowedAgents);
   const skills = splitCsv(data.skills);
 
@@ -130,6 +139,7 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
     systemPromptMode,
     allowedAgents: allowedAgents.length > 0 ? allowedAgents : undefined,
     maxDepth,
+    debug,
     prompt: body,
     source,
     filePath,

package/extensions/env-utils.ts

@@ -1,5 +1,14 @@
+export type SystemPromptModeEnv = 'replace' | 'append';
+
 export type RecursionEnv = Partial<
-  Record<'PI_SUBAGENT_ALLOWED' | 'PI_SUBAGENT_DEPTH' | 'PI_SUBAGENT_MAX_DEPTH', string>
+  Record<
+    | 'PI_SUBAGENT_ALLOWED'
+    | 'PI_SUBAGENT_DEPTH'
+    | 'PI_SUBAGENT_MAX_DEPTH'
+    | 'PI_SUBAGENT_NAME'
+    | 'PI_SUBAGENT_SYSTEM_PROMPT_MODE',
+    string
+  >
 >;
 
 export function parseEnvNumber(value: string | undefined): number | undefined {
@@ -24,3 +33,18 @@ export function isPastMaxDepth(env: RecursionEnv): boolean {
   const maxDepth = parseEnvNumber(env?.PI_SUBAGENT_MAX_DEPTH);
   return depth !== undefined && maxDepth !== undefined && depth > maxDepth;
 }
+
+export function isSubagentProcess(env: RecursionEnv): boolean {
+  const depth = parseEnvNumber(env?.PI_SUBAGENT_DEPTH);
+  return depth !== undefined && depth > 0;
+}
+
+export function subagentSystemPromptMode(env: RecursionEnv): SystemPromptModeEnv | undefined {
+  const mode = env?.PI_SUBAGENT_SYSTEM_PROMPT_MODE;
+  if (mode === 'replace' || mode === 'append') return mode;
+  return undefined;
+}
+
+export function isSubagentReplaceSystemPrompt(env: RecursionEnv): boolean {
+  return isSubagentProcess(env) && subagentSystemPromptMode(env) === 'replace';
+}

package/extensions/index.ts

@@ -1,7 +1,12 @@
 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 } from './env-utils.ts';
-import { appendAvailableSubagentsBlock } from './subagent-prompt.ts';
+import { allowedAgentNames, isPastMaxDepth, isSubagentReplaceSystemPrompt } from './env-utils.ts';
+import {
+  appendAvailableSubagentsBlock,
+  appendAvailableToolsAndGuidelinesBlock,
+} from './subagent-prompt.ts';
 import { registerSubagentTool } from './subagent-tool.ts';
 
 export default async function (pi: ExtensionAPI) {
@@ -17,10 +22,32 @@ export default async function (pi: ExtensionAPI) {
     : result.agents;
   const agentNames = agents.map((agent) => agent.name);
 
+  if (isSubagentReplaceSystemPrompt(process.env)) {
+    pi.on('before_agent_start', (event) => {
+      return {
+        systemPrompt: appendAvailableToolsAndGuidelinesBlock(
+          event.systemPrompt,
+          event.systemPromptOptions,
+        ),
+      };
+    });
+  }
+
   if (!isPastMaxDepth(process.env) && agentNames.length > 0) {
-    pi.on('before_agent_start', (event) => ({
-      systemPrompt: appendAvailableSubagentsBlock(event.systemPrompt, agentNames),
-    }));
+    pi.on('before_agent_start', (event) => {
+      if (!event.systemPromptOptions.selectedTools?.includes('subagent')) return;
+      return {
+        systemPrompt: appendAvailableSubagentsBlock(event.systemPrompt, agentNames),
+      };
+    });
+  }
+
+  if (process.env.PI_SUBAGENT_DEBUG === 'true') {
+    pi.on('before_agent_start', (_event, ctx) => {
+      const prompt = ctx.getSystemPrompt();
+      const outputPath = path.join(ctx.cwd, 'debug-system-prompt.md');
+      fs.writeFileSync(outputPath, prompt, 'utf-8');
+    });
   }
 
   registerSubagentTool(pi, { agents: result.agents });

package/extensions/skill-resolver.ts

@@ -1,3 +1,9 @@
+import {
+  DefaultPackageManager,
+  SettingsManager,
+  getAgentDir,
+  type ResolvedResource,
+} from '@earendil-works/pi-coding-agent';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -15,8 +21,16 @@ export interface SkillResolverFs {
 
 export interface ResolveSkillsOptions {
   cwd: string;
+  agentDir?: string;
   globalDir?: string;
   fs?: SkillResolverFs;
+  packageSkillFiles?: string[];
+}
+
+export interface ResolveSkillsResult {
+  resolved: ResolvedSkill[];
+  missing: string[];
+  skippedPackages: string[];
 }
 
 const defaultSkillFs: SkillResolverFs = {
@@ -79,7 +93,7 @@ function parseSkillFrontmatter(content: string): { name: string; description: st
   return { name: data.name || '', description: data.description.trim() };
 }
 
-function findSkillFile(
+function findLocalSkillFile(
   skillName: string,
   cwd: string,
   globalDir: string,
@@ -104,43 +118,111 @@ function findSkillFile(
   return undefined;
 }
 
-export function resolveSkills(
+async function resolvePackageSkillFiles(options: ResolveSkillsOptions): Promise<{
+  files: string[];
+  skippedPackages: string[];
+}> {
+  if (options.packageSkillFiles) {
+    return { files: options.packageSkillFiles, skippedPackages: [] };
+  }
+  if (options.fs) {
+    return { files: [], skippedPackages: [] };
+  }
+
+  const skippedPackages: string[] = [];
+  const agentDir = options.agentDir ?? getAgentDir();
+  const settingsManager = SettingsManager.create(options.cwd, agentDir);
+  const packageManager = new DefaultPackageManager({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+  });
+  const resolvedPaths = await packageManager.resolve(async (source) => {
+    skippedPackages.push(source);
+    return 'skip';
+  });
+
+  return {
+    files: resolvedPaths.skills
+      .filter((resource: ResolvedResource) => resource.enabled)
+      .map((resource: ResolvedResource) => resource.path),
+    skippedPackages,
+  };
+}
+
+function readSkill(
+  filePath: string,
+  requestedName: string,
+  fileSystem: SkillResolverFs,
+  requireNameMatch: boolean,
+): ResolvedSkill | undefined {
+  const content = fileSystem.readFile(filePath);
+  const frontmatter = parseSkillFrontmatter(content);
+  if (!frontmatter) return undefined;
+
+  const fileSkillName = frontmatter.name || path.basename(path.dirname(filePath));
+  const markdownName = path.basename(filePath, '.md');
+  if (requireNameMatch && fileSkillName !== requestedName && markdownName !== requestedName) {
+    return undefined;
+  }
+
+  return {
+    name: fileSkillName || requestedName,
+    description: frontmatter.description,
+    location: filePath,
+  };
+}
+
+export async function resolveSkills(
   skillNames: string[],
   options: ResolveSkillsOptions,
-): { resolved: ResolvedSkill[]; missing: string[] } {
+): Promise<ResolveSkillsResult> {
   const cwd = options.cwd;
   const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
   const fileSystem = options.fs ?? defaultSkillFs;
   const resolved: ResolvedSkill[] = [];
   const missing: string[] = [];
+  const pendingPackageResolution: string[] = [];
 
   for (const name of skillNames) {
     const trimmed = name.trim();
     if (!trimmed) continue;
 
-    const filePath = findSkillFile(trimmed, cwd, globalDir, fileSystem);
-    if (!filePath) {
-      missing.push(trimmed);
-      continue;
+    const localFilePath = findLocalSkillFile(trimmed, cwd, globalDir, fileSystem);
+    if (localFilePath) {
+      try {
+        const skill = readSkill(localFilePath, trimmed, fileSystem, false);
+        if (skill) {
+          resolved.push(skill);
+          continue;
+        }
+      } catch {
+        // Try package skills before marking the skill as missing.
+      }
     }
 
-    try {
-      const content = fileSystem.readFile(filePath);
-      const frontmatter = parseSkillFrontmatter(content);
-      if (!frontmatter) {
-        missing.push(trimmed);
-        continue;
-      }
+    pendingPackageResolution.push(trimmed);
+  }
 
-      resolved.push({
-        name: frontmatter.name || trimmed,
-        description: frontmatter.description,
-        location: filePath,
-      });
-    } catch {
-      missing.push(trimmed);
+  const packageSkills =
+    pendingPackageResolution.length > 0
+      ? await resolvePackageSkillFiles(options)
+      : { files: [], skippedPackages: [] };
+
+  for (const trimmed of pendingPackageResolution) {
+    let packageSkill: ResolvedSkill | undefined;
+    for (const filePath of packageSkills.files) {
+      try {
+        packageSkill = readSkill(filePath, trimmed, fileSystem, true);
+        if (packageSkill) break;
+      } catch {
+        // Try the next package skill file.
+      }
     }
+
+    if (packageSkill) resolved.push(packageSkill);
+    else missing.push(trimmed);
   }
 
-  return { resolved, missing };
+  return { resolved, missing, skippedPackages: packageSkills.skippedPackages };
 }

package/extensions/subagent-executor.ts

@@ -5,7 +5,6 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { AgentConfig } from './agent-loader.ts';
-import { formatAvailableSubagentsBlock } from './subagent-prompt.ts';
 import { resolveSkills } from './skill-resolver.ts';
 
 export interface AgentUsage {
@@ -89,10 +88,38 @@ export interface RunSubagentOptions {
   now?: () => number;
 }
 
+export interface BuildSubagentSystemPromptOptions {
+  agent: AgentConfig;
+  cwd: string;
+  agentDir?: string;
+}
+
+export interface BuildSubagentSystemPromptResult {
+  prompt: string;
+  missingSkills: string[];
+  skippedSkillPackages: string[];
+}
+
 const TASK_FILE_THRESHOLD = 8000;
 const OUTPUT_MAX_BYTES = 50 * 1024;
 const OUTPUT_MAX_LINES = 2000;
 
+export function availableSubagentsForAgent(
+  agent: AgentConfig,
+  candidateNames?: string[],
+): string[] {
+  const names = candidateNames ?? agent.allowedAgents ?? [];
+  const allowed = agent.allowedAgents ? new Set(agent.allowedAgents) : undefined;
+  const seen = new Set<string>();
+
+  return names.filter((name) => {
+    if (seen.has(name)) return false;
+    if (allowed && !allowed.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+}
+
 const defaultFs: ExecutorFs = {
   makeTempDir(prefix) {
     return fs.mkdtemp(prefix);
@@ -333,6 +360,31 @@ function safeFilePart(value: string): string {
   return value.replace(/[^a-zA-Z0-9_.-]+/g, '_');
 }
 
+export async function buildSubagentSystemPrompt(
+  options: BuildSubagentSystemPromptOptions,
+): Promise<BuildSubagentSystemPromptResult> {
+  let prompt = options.agent.prompt;
+
+  const missingSkills: string[] = [];
+  const skippedSkillPackages: string[] = [];
+  const skillNames = options.agent.skills;
+  if (skillNames && skillNames.length > 0) {
+    const resolvedSkills = await resolveSkills(skillNames, {
+      cwd: options.cwd,
+      agentDir: options.agentDir,
+    });
+    missingSkills.push(...resolvedSkills.missing);
+    skippedSkillPackages.push(...resolvedSkills.skippedPackages);
+
+    const skillInjection = formatSkillsForPrompt(resolvedSkills.resolved);
+    if (skillInjection) {
+      prompt = `${prompt}${skillInjection}`;
+    }
+  }
+
+  return { prompt, missingSkills, skippedSkillPackages };
+}
+
 function progressFromPartialResult(partialResult: unknown): AgentProgress | undefined {
   if (!partialResult || typeof partialResult !== 'object') return undefined;
   const details = (partialResult as { details?: unknown }).details;
@@ -377,28 +429,18 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
   try {
     const promptFilePath = path.join(tempDir, 'system-prompt.md');
 
-    let promptContent = options.agent.prompt;
-    if (options.agent.tools.includes('subagent')) {
-      const availableSubagentsBlock = formatAvailableSubagentsBlock(
-        options.availableAgents ?? options.agent.allowedAgents ?? [],
-      );
-      if (availableSubagentsBlock) {
-        promptContent = `${promptContent.trimEnd()}\n\n${availableSubagentsBlock}`;
-      }
+    const promptResult = await buildSubagentSystemPrompt({
+      agent: options.agent,
+      cwd: options.cwd,
+      agentDir: options.agentDir,
+    });
+    for (const source of promptResult.skippedSkillPackages) {
+      console.warn(`[pi-subagents] package not installed, skipping skills: ${source}`);
     }
-
-    const skillNames = options.agent.skills;
-    if (skillNames && skillNames.length > 0) {
-      const { resolved, missing } = resolveSkills(skillNames, { cwd: options.cwd });
-      for (const name of missing) {
-        console.warn(`[pi-subagents] skill not found: ${name}`);
-      }
-      const skillInjection = formatSkillsForPrompt(resolved);
-      if (skillInjection) {
-        promptContent = `${promptContent}${skillInjection}`;
-      }
+    for (const name of promptResult.missingSkills) {
+      console.warn(`[pi-subagents] skill not found: ${name}`);
     }
-    await fileSystem.writeFile(promptFilePath, promptContent);
+    await fileSystem.writeFile(promptFilePath, promptResult.prompt);
 
     let taskFilePath: string | undefined;
     if (options.task.length > TASK_FILE_THRESHOLD) {
@@ -411,16 +453,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       AuthStorage.create(options.agentDir ? path.join(options.agentDir, 'auth.json') : undefined),
       options.agentDir ? path.join(options.agentDir, 'models.json') : undefined,
     );
-    const args = [
-      pi.entryPoint,
-      '--mode',
-      'json',
-      '-p',
-      '--no-skills',
-      '--no-prompt-templates',
-      '--no-context-files',
-    ];
+    const args = [pi.entryPoint, '--mode', 'json', '-p', '--no-skills', '--no-prompt-templates'];
 
+    if (options.agent.systemPromptMode === 'replace') args.push('--no-context-files');
     if (options.agent.model) args.push('--model', options.agent.model);
     args.push('--thinking', options.agent.thinking);
     if (options.agent.tools.length > 0) args.push('--tools', options.agent.tools.join(','));
@@ -435,10 +470,14 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       ...process.env,
       PI_SUBAGENT_DEPTH: String(options.depth ?? 1),
       PI_SUBAGENT_MAX_DEPTH: String(options.agent.maxDepth),
+      PI_SUBAGENT_NAME: options.agent.name,
+      PI_SUBAGENT_SYSTEM_PROMPT_MODE: options.agent.systemPromptMode,
     };
-    if (options.agent.tools.includes('subagent') && options.agent.allowedAgents?.length) {
-      env.PI_SUBAGENT_ALLOWED = options.agent.allowedAgents.join(',');
+    const visibleAgents = availableSubagentsForAgent(options.agent, options.availableAgents);
+    if (visibleAgents.length > 0) {
+      env.PI_SUBAGENT_ALLOWED = visibleAgents.join(',');
     }
+    env.PI_SUBAGENT_DEBUG = options.agent.debug ? 'true' : 'false';
 
     const processLine = (line: string) => {
       if (!line.trim()) return;

package/extensions/subagent-prompt.ts

@@ -1,3 +1,77 @@
+export interface ToolGuidelinePromptOptions {
+  selectedTools?: string[];
+  toolSnippets?: Record<string, string>;
+  promptGuidelines?: string[];
+}
+
+function uniqueNonEmpty(values: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = value.trim();
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+export function formatAvailableToolsAndGuidelinesBlock(
+  options: ToolGuidelinePromptOptions,
+): string | undefined {
+  const selectedTools = options.selectedTools ?? ['read', 'bash', 'edit', 'write'];
+  const visibleTools = selectedTools.filter((name) => options.toolSnippets?.[name]);
+  const toolsList =
+    visibleTools.length > 0
+      ? visibleTools.map((name) => `- ${name}: ${options.toolSnippets![name]}`).join('\n')
+      : '(none)';
+
+  const hasBashOnlyForFileExploration =
+    selectedTools.includes('bash') &&
+    !selectedTools.includes('grep') &&
+    !selectedTools.includes('find') &&
+    !selectedTools.includes('ls');
+  const guidelines = uniqueNonEmpty([
+    ...(hasBashOnlyForFileExploration ? ['Use bash for file operations like ls, rg, find'] : []),
+    ...(options.promptGuidelines ?? []),
+    'Be concise in your responses',
+    'Show file paths clearly when working with files',
+  ]);
+  const guidelineLines = guidelines.map((guideline) => `- ${guideline}`).join('\n');
+
+  return [
+    'Available tools:',
+    toolsList,
+    '',
+    'In addition to the tools above, you may have access to other custom tools depending on the project.',
+    '',
+    'Guidelines:',
+    guidelineLines || '(none)',
+  ].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(
+  systemPrompt: string,
+  options: ToolGuidelinePromptOptions,
+): string {
+  const block = formatAvailableToolsAndGuidelinesBlock(options);
+  if (!block || systemPrompt.includes('Available tools:') || systemPrompt.includes('Guidelines:')) {
+    return systemPrompt;
+  }
+
+  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;

package/extensions/subagent-tool.ts

@@ -8,7 +8,12 @@ import {
 } from '@earendil-works/pi-coding-agent';
 import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui';
 import type { AgentConfig } from './agent-loader.ts';
-import { type AgentProgress, type AgentResult, runSubagent } from './subagent-executor.ts';
+import {
+  availableSubagentsForAgent,
+  type AgentProgress,
+  type AgentResult,
+  runSubagent,
+} from './subagent-executor.ts';
 import {
   contextUsageSeverity,
   formatSubagentCall,
@@ -250,7 +255,7 @@ export function registerSubagentTool(
         cwd: params.cwd ?? ctx.cwd,
         signal,
         depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
-        availableAgents: availableSubagents,
+        availableAgents: availableSubagentsForAgent(agent, availableSubagents),
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
       });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnnywu/pi-subagents",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {