@johnnywu/pi-subagents 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# [2.0.0](https://github.com/jwu/pi-subagents/compare/v1.5.0...v2.0.0) (2026-06-16)
+
+
+* feat!: clarify systemPrompt replace semantics ([5cdb603](https://github.com/jwu/pi-subagents/commit/5cdb603e814b966f43fa0537dae5ac90799233b7))
+
+
+### BREAKING CHANGES
+
+* systemPrompt: replace now preserves pi context files.
+Use systemPrompt: replace-all for the previous isolated behavior.
+
 # [1.5.0](https://github.com/jwu/pi-subagents/compare/v1.4.0...v1.5.0) (2026-06-03)
 
 

package/README.md

@@ -63,10 +63,24 @@ Available subagents:
 - 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:
+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.
+### 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 |
+
+`append` keeps pi's full default prompt (with project context) and adds the agent body at the end.
+`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.
+
+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.
 
@@ -81,7 +95,7 @@ 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.
+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.
 
 ## Agent configuration
 
@@ -94,7 +108,7 @@ 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`, `minimal`, `low`, `medium`, `high`, `xhigh` |
-| `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) |
+| `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.) |

package/extensions/agent-loader.ts

@@ -3,7 +3,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
-export type SystemPromptMode = 'replace' | 'append';
+export type SystemPromptMode = 'replace' | 'replace-all' | 'append';
 export type AgentSource = 'global' | 'project';
 
 export interface AgentConfig {
@@ -109,7 +109,7 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
   }
 
   const systemPromptMode = (data.systemPrompt ?? 'append') as SystemPromptMode;
-  if (!['replace', 'append'].includes(systemPromptMode)) {
+  if (!['replace', 'replace-all', 'append'].includes(systemPromptMode)) {
     throw new Error(`invalid systemPrompt: ${data.systemPrompt}`);
   }
 

package/extensions/env-utils.ts

@@ -1,4 +1,4 @@
-export type SystemPromptModeEnv = 'replace' | 'append';
+export type SystemPromptModeEnv = 'replace' | 'replace-all' | 'append';
 
 export type RecursionEnv = Partial<
   Record<
@@ -41,10 +41,11 @@ export function isSubagentProcess(env: RecursionEnv): boolean {
 
 export function subagentSystemPromptMode(env: RecursionEnv): SystemPromptModeEnv | undefined {
   const mode = env?.PI_SUBAGENT_SYSTEM_PROMPT_MODE;
-  if (mode === 'replace' || mode === 'append') return mode;
+  if (mode === 'replace' || mode === 'replace-all' || mode === 'append') return mode;
   return undefined;
 }
 
 export function isSubagentReplaceSystemPrompt(env: RecursionEnv): boolean {
-  return isSubagentProcess(env) && subagentSystemPromptMode(env) === 'replace';
+  const mode = subagentSystemPromptMode(env);
+  return isSubagentProcess(env) && (mode === 'replace' || mode === 'replace-all');
 }

package/extensions/subagent-executor.ts

@@ -461,7 +461,7 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     );
     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.systemPromptMode === 'replace-all') 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(','));

package/extensions/subagent-prompt.ts

@@ -65,7 +65,7 @@ export function appendAvailableToolsAndGuidelinesBlock(
   options: ToolGuidelinePromptOptions,
 ): string {
   const block = formatAvailableToolsAndGuidelinesBlock(options);
-  if (!block || systemPrompt.includes('Available tools:') || systemPrompt.includes('Guidelines:')) {
+  if (!block || systemPrompt.includes(block)) {
     return systemPrompt;
   }
 

package/package.json

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