@johnnywu/pi-subagents 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# [1.4.0](https://github.com/jwu/pi-subagents/compare/v1.3.0...v1.4.0) (2026-06-02)
+
+
+### Features
+
+* support wildcard skills ([962eaa4](https://github.com/jwu/pi-subagents/commit/962eaa486cd73342629cfecf4e7bcc8a1ceb4710))
+
+# [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,12 +94,16 @@ 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) |
+| `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.
 
+`skills` entries match the skill frontmatter `name`. Use `skills: *` to load all available skills, or prefix-style patterns such as `skills: obsidian-*` to load matching skills. Only `*` is supported as a wildcard; glob features like `?` or `{a,b}` are not supported.
+
 ### Example with all fields
 
 ```markdown
@@ -91,9 +113,11 @@ 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
+skills: tdd, obsidian-*
 allowedAgents: code-reviewer, refactor, test-writer
 maxDepth: 2
+debug: false
 ---
 
 You are an orchestrator. Break complex tasks into sub-tasks and delegate
@@ -121,7 +145,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';
@@ -11,12 +17,22 @@ export interface ResolvedSkill {
 export interface SkillResolverFs {
   exists(filePath: string): boolean;
   readFile(filePath: string): string;
+  listFiles?(dir: string): string[];
 }
 
 export interface ResolveSkillsOptions {
   cwd: string;
+  agentDir?: string;
   globalDir?: string;
   fs?: SkillResolverFs;
+  packageSkillFiles?: string[];
+}
+
+export interface ResolveSkillsResult {
+  resolved: ResolvedSkill[];
+  missing: string[];
+  skippedPackages: string[];
+  warnings: string[];
 }
 
 const defaultSkillFs: SkillResolverFs = {
@@ -26,6 +42,16 @@ const defaultSkillFs: SkillResolverFs = {
   readFile(filePath) {
     return fs.readFileSync(filePath, 'utf-8');
   },
+  listFiles(dir) {
+    try {
+      return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .map((entry) => path.join(dir, entry.name))
+        .sort();
+    } catch {
+      return [];
+    }
+  },
 };
 
 function defaultGlobalSkillsDir(): string {
@@ -75,72 +101,200 @@ function parseSkillFrontmatter(content: string): { name: string; description: st
   }
   delete data._currentBlockKey;
 
-  if (!data.description || !data.description.trim()) return undefined;
-  return { name: data.name || '', description: data.description.trim() };
+  return { name: data.name || '', description: (data.description ?? '').trim() };
 }
 
-function findSkillFile(
-  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;
+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,
+  };
+}
+
+interface ReadSkillResult {
+  skill?: ResolvedSkill;
+  warning?: string;
+}
 
-  // Priority 1: Project .pi/skills/<name>/SKILL.md
-  const projectPiPath = path.join(cwd, '.pi', 'skills', skillName, 'SKILL.md');
-  if (fileSystem.exists(projectPiPath)) return projectPiPath;
+function readSkill(filePath: string, fileSystem: SkillResolverFs): ReadSkillResult | undefined {
+  const content = fileSystem.readFile(filePath);
+  const frontmatter = parseSkillFrontmatter(content);
+  if (!frontmatter) return undefined;
 
-  // Priority 4: Global ~/.pi/agent/skills/<name>/SKILL.md
-  const globalPiPath = path.join(globalDir, skillName, 'SKILL.md');
-  if (fileSystem.exists(globalPiPath)) return globalPiPath;
+  const fileSkillName = frontmatter.name.trim();
+  if (!fileSkillName) {
+    return { warning: `skill missing required field: name: ${filePath}` };
+  }
+  if (!frontmatter.description) return undefined;
 
-  // 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 {
+    skill: {
+      name: fileSkillName,
+      description: frontmatter.description,
+      location: filePath,
+    },
+  };
+}
 
-  return undefined;
+interface CollectedSkills {
+  byName: Map<string, ResolvedSkill>;
+  warnings: string[];
+  skippedPackages: string[];
 }
 
-export function resolveSkills(
-  skillNames: string[],
-  options: ResolveSkillsOptions,
-): { resolved: ResolvedSkill[]; missing: string[] } {
+const collectedSkillsCache = new Map<string, Promise<CollectedSkills>>();
+
+function listSkillFilesInDir(dir: string, fileSystem: SkillResolverFs): string[] {
+  if (!fileSystem.listFiles) return [];
+
+  return fileSystem
+    .listFiles(dir)
+    .map((entry) => path.join(entry, 'SKILL.md'))
+    .filter((filePath) => fileSystem.exists(filePath));
+}
+
+function addSkillFile(
+  filePath: string,
+  fileSystem: SkillResolverFs,
+  byName: Map<string, ResolvedSkill>,
+  warnings: string[],
+): void {
+  try {
+    const result = readSkill(filePath, fileSystem);
+    if (!result) return;
+    if (result.warning) warnings.push(result.warning);
+    if (result.skill && !byName.has(result.skill.name)) byName.set(result.skill.name, result.skill);
+  } catch (error) {
+    warnings.push(
+      `skill could not be read: ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function collectSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
   const cwd = options.cwd;
   const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
   const fileSystem = options.fs ?? defaultSkillFs;
+  const byName = new Map<string, ResolvedSkill>();
+  const warnings: string[] = [];
+
+  for (const dir of [
+    path.join(cwd, '.agents', 'skills'),
+    path.join(cwd, '.pi', 'skills'),
+    globalDir,
+    path.join(os.homedir(), '.agents', 'skills'),
+  ]) {
+    for (const filePath of listSkillFilesInDir(dir, fileSystem)) {
+      addSkillFile(filePath, fileSystem, byName, warnings);
+    }
+  }
+
+  const packageSkills = await resolvePackageSkillFiles(options);
+  for (const filePath of packageSkills.files) {
+    addSkillFile(filePath, fileSystem, byName, warnings);
+  }
+
+  return { byName, warnings, skippedPackages: packageSkills.skippedPackages };
+}
+
+function skillsCacheKey(options: ResolveSkillsOptions): string | undefined {
+  if (options.fs) return undefined;
+  return JSON.stringify({
+    cwd: options.cwd,
+    agentDir: options.agentDir,
+    globalDir: options.globalDir ?? defaultGlobalSkillsDir(),
+    packageSkillFiles: options.packageSkillFiles,
+  });
+}
+
+async function getCollectedSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
+  const cacheKey = skillsCacheKey(options);
+  if (!cacheKey) return collectSkills(options);
+
+  let cached = collectedSkillsCache.get(cacheKey);
+  if (!cached) {
+    cached = collectSkills(options);
+    collectedSkillsCache.set(cacheKey, cached);
+  }
+  return cached;
+}
+
+function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function hasWildcard(pattern: string): boolean {
+  return pattern.includes('*');
+}
+
+export async function resolveSkills(
+  skillNames: string[],
+  options: ResolveSkillsOptions,
+): Promise<ResolveSkillsResult> {
+  const requestedNames = skillNames.map((name) => name.trim()).filter(Boolean);
+  if (requestedNames.length === 0) {
+    return { resolved: [], missing: [], skippedPackages: [], warnings: [] };
+  }
+
+  const collected = await getCollectedSkills(options);
   const resolved: ResolvedSkill[] = [];
   const missing: string[] = [];
+  const seen = new Set<string>();
 
-  for (const name of skillNames) {
-    const trimmed = name.trim();
-    if (!trimmed) continue;
+  function addSkill(skill: ResolvedSkill): void {
+    if (seen.has(skill.name)) return;
+    seen.add(skill.name);
+    resolved.push(skill);
+  }
 
-    const filePath = findSkillFile(trimmed, cwd, globalDir, fileSystem);
-    if (!filePath) {
-      missing.push(trimmed);
+  for (const requestedName of requestedNames) {
+    if (hasWildcard(requestedName)) {
+      const regex = wildcardToRegex(requestedName);
+      let matched = false;
+      for (const skill of collected.byName.values()) {
+        if (!regex.test(skill.name)) continue;
+        matched = true;
+        addSkill(skill);
+      }
+      if (!matched) missing.push(requestedName);
       continue;
     }
 
-    try {
-      const content = fileSystem.readFile(filePath);
-      const frontmatter = parseSkillFrontmatter(content);
-      if (!frontmatter) {
-        missing.push(trimmed);
-        continue;
-      }
-
-      resolved.push({
-        name: frontmatter.name || trimmed,
-        description: frontmatter.description,
-        location: filePath,
-      });
-    } catch {
-      missing.push(trimmed);
-    }
+    const skill = collected.byName.get(requestedName);
+    if (skill) addSkill(skill);
+    else missing.push(requestedName);
   }
 
-  return { resolved, missing };
+  return {
+    resolved,
+    missing,
+    skippedPackages: collected.skippedPackages,
+    warnings: collected.warnings,
+  };
 }

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,39 @@ export interface RunSubagentOptions {
   now?: () => number;
 }
 
+export interface BuildSubagentSystemPromptOptions {
+  agent: AgentConfig;
+  cwd: string;
+  agentDir?: string;
+}
+
+export interface BuildSubagentSystemPromptResult {
+  prompt: string;
+  missingSkills: string[];
+  skippedSkillPackages: string[];
+  skillWarnings: 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 +361,33 @@ 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 skillWarnings: 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);
+    skillWarnings.push(...resolvedSkills.warnings);
+
+    const skillInjection = formatSkillsForPrompt(resolvedSkills.resolved);
+    if (skillInjection) {
+      prompt = `${prompt}${skillInjection}`;
+    }
+  }
+
+  return { prompt, missingSkills, skippedSkillPackages, skillWarnings };
+}
+
 function progressFromPartialResult(partialResult: unknown): AgentProgress | undefined {
   if (!partialResult || typeof partialResult !== 'object') return undefined;
   const details = (partialResult as { details?: unknown }).details;
@@ -377,28 +432,21 @@ 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 warning of promptResult.skillWarnings) {
+      console.warn(`[pi-subagents] ${warning}`);
+    }
+    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 +459,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 +476,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.4.0",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {