@johnnywu/pi-subagents 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [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)
+
+
+### Features
+
+* agent skills frontmatter support ([e479b0c](https://github.com/jwu/pi-subagents/commit/e479b0cc57c8097a89f73b491c32a099ba56bc77))
+* expose available subagents in prompts ([047035a](https://github.com/jwu/pi-subagents/commit/047035a49e9749dc719a97f2556be9f60551cf97))
+
 # [1.1.0](https://github.com/jwu/pi-subagents/compare/v1.0.1...v1.1.0) (2026-05-31)
 
 

package/README.md

@@ -48,6 +48,41 @@ Or instruct pi to delegate:
 Run the code-reviewer agent on the last three commits
 ```
 
+### Available subagents in the prompt
+
+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`
+- At agent-start time, the system prompt gets an independent block:
+
+```text
+Available subagents:
+- code-reviewer
+- refactor
+- test-writer
+```
+
+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
 
 Agents are Markdown files with YAML frontmatter.
@@ -59,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.
 
@@ -74,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
@@ -102,7 +139,9 @@ Sub-agents can spawn their own sub-agents (if the `subagent` tool is in their wh
 
 **`allowedAgents`** — Whitelist enforced by the parent before spawning. A child process never sees agent names outside its parent's whitelist.
 
-These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`).
+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`). 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,8 @@ export interface AgentConfig {
   systemPromptMode: SystemPromptMode;
   allowedAgents?: string[];
   maxDepth: number;
+  debug: boolean;
+  skills?: string[];
   prompt: string;
   source: AgentSource;
   filePath: string;
@@ -106,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}`);
   }
@@ -116,17 +118,28 @@ 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);
 
   return {
     name: data.name,
     description: data.description,
     tools: splitCsv(data.tools),
+    skills: skills.length > 0 ? skills : undefined,
     model: data.model || undefined,
     thinking,
     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,5 +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, isSubagentReplaceSystemPrompt } from './env-utils.ts';
+import {
+  appendAvailableSubagentsBlock,
+  appendAvailableToolsAndGuidelinesBlock,
+} from './subagent-prompt.ts';
 import { registerSubagentTool } from './subagent-tool.ts';
 
 export default async function (pi: ExtensionAPI) {
@@ -9,5 +16,39 @@ 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);
+
+  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) => {
+      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

@@ -0,0 +1,228 @@
+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';
+
+export interface ResolvedSkill {
+  name: string;
+  description: string;
+  location: string;
+}
+
+export interface SkillResolverFs {
+  exists(filePath: string): boolean;
+  readFile(filePath: string): string;
+}
+
+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 = {
+  exists(filePath) {
+    return fs.existsSync(filePath);
+  },
+  readFile(filePath) {
+    return fs.readFileSync(filePath, 'utf-8');
+  },
+};
+
+function defaultGlobalSkillsDir(): string {
+  return path.join(os.homedir(), '.pi', 'agent', 'skills');
+}
+
+function parseSkillFrontmatter(content: string): { name: string; description: string } | undefined {
+  const normalized = content.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---')) return undefined;
+
+  const endIndex = normalized.indexOf('\n---', 3);
+  if (endIndex === -1) return undefined;
+
+  const frontmatterBlock = normalized.slice(4, endIndex);
+  const lines = frontmatterBlock.split('\n');
+  const data: Record<string, string> = {};
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Check if this is a YAML block scalar continuation (| or >)
+    if (
+      data._currentBlockKey !== undefined &&
+      (lines[i].startsWith('  ') || lines[i].startsWith('\t'))
+    ) {
+      const current = data[data._currentBlockKey] ?? '';
+      data[data._currentBlockKey] = current ? `${current} ${trimmed}` : trimmed;
+      continue;
+    }
+    delete data._currentBlockKey;
+
+    const separator = trimmed.indexOf(':');
+    if (separator === -1) continue;
+    const key = trimmed.slice(0, separator).trim();
+    let value = trimmed.slice(separator + 1).trim();
+
+    // Handle YAML block scalar indicators (| and >)
+    if (value === '|' || value === '>') {
+      data._currentBlockKey = key;
+      data[key] = '';
+      continue;
+    }
+
+    value = value.replace(/^['"]|['"]$/g, '');
+    if (key) data[key] = value;
+  }
+  delete data._currentBlockKey;
+
+  if (!data.description || !data.description.trim()) return undefined;
+  return { name: data.name || '', description: data.description.trim() };
+}
+
+function findLocalSkillFile(
+  skillName: string,
+  cwd: string,
+  globalDir: string,
+  fileSystem: SkillResolverFs,
+): string | undefined {
+  // Priority 1: Project .agents/skills/<name>/SKILL.md
+  const projectAgentsPath = path.join(cwd, '.agents', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(projectAgentsPath)) return projectAgentsPath;
+
+  // Priority 1: Project .pi/skills/<name>/SKILL.md
+  const projectPiPath = path.join(cwd, '.pi', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(projectPiPath)) return projectPiPath;
+
+  // Priority 4: Global ~/.pi/agent/skills/<name>/SKILL.md
+  const globalPiPath = path.join(globalDir, skillName, 'SKILL.md');
+  if (fileSystem.exists(globalPiPath)) return globalPiPath;
+
+  // Priority 4: Global ~/.agents/skills/<name>/SKILL.md
+  const globalAgentsPath = path.join(os.homedir(), '.agents', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(globalAgentsPath)) return globalAgentsPath;
+
+  return undefined;
+}
+
+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,
+): 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 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.
+      }
+    }
+
+    pendingPackageResolution.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, skippedPackages: packageSkills.skippedPackages };
+}

package/extensions/subagent-executor.ts

@@ -5,6 +5,7 @@ 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 { resolveSkills } from './skill-resolver.ts';
 
 export interface AgentUsage {
   input: number;
@@ -77,6 +78,7 @@ export interface RunSubagentOptions {
   signal?: AbortSignal;
   onProgress?: (progress: AgentProgress) => void;
   depth?: number;
+  availableAgents?: string[];
   tempRoot?: string;
   outputArchiveDir?: string;
   agentDir?: string;
@@ -86,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);
@@ -274,6 +304,40 @@ function buildTaskArgument(task: string, taskFilePath: string | undefined): stri
   return taskFilePath ? `Task: @${taskFilePath}` : `Task: ${task}`;
 }
 
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function formatSkillsForPrompt(
+  skills: Array<{ name: string; description: string; location: string }>,
+): string {
+  if (skills.length === 0) return '';
+
+  const lines = [
+    '\n\nThe following skills provide specialized instructions for specific tasks.',
+    "Use the read tool to load a skill's file when the task matches its description.",
+    'When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.',
+    '',
+    '<available_skills>',
+  ];
+
+  for (const skill of skills) {
+    lines.push('  <skill>');
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+    lines.push('  </skill>');
+  }
+
+  lines.push('</available_skills>');
+  return lines.join('\n');
+}
+
 function byteLength(text: string): number {
   return Buffer.byteLength(text, 'utf8');
 }
@@ -296,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;
@@ -339,7 +428,19 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
 
   try {
     const promptFilePath = path.join(tempDir, 'system-prompt.md');
-    await fileSystem.writeFile(promptFilePath, options.agent.prompt);
+
+    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}`);
+    }
+    for (const name of promptResult.missingSkills) {
+      console.warn(`[pi-subagents] skill not found: ${name}`);
+    }
+    await fileSystem.writeFile(promptFilePath, promptResult.prompt);
 
     let taskFilePath: string | undefined;
     if (options.task.length > TASK_FILE_THRESHOLD) {
@@ -352,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(','));
@@ -376,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

@@ -0,0 +1,87 @@
+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;
+
+  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}`;
+}

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,
@@ -217,10 +222,8 @@ export function registerSubagentTool(
     : options.agents;
   const runner = options.run ?? runSubagent;
 
-  const agentNames = agents
-    .map((a) => a.name)
-    .sort()
-    .join(', ');
+  const availableSubagents = agents.map((agent) => agent.name);
+  const agentNames = [...availableSubagents].sort().join(', ');
   const promptGuidelines =
     agentNames.length > 0 ? [`Available subagents: ${agentNames}`] : undefined;
 
@@ -252,6 +255,7 @@ export function registerSubagentTool(
         cwd: params.cwd ?? ctx.cwd,
         signal,
         depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
+        availableAgents: availableSubagentsForAgent(agent, availableSubagents),
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
       });
 

package/package.json

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