@johnnywu/pi-subagents 1.5.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# [2.1.0](https://github.com/jwu/pi-subagents/compare/v2.0.0...v2.1.0) (2026-06-17)
+
+
+### Features
+
+* support forked subagent sessions ([50f27f5](https://github.com/jwu/pi-subagents/commit/50f27f5ea45f559f0125944f4f42c8c955cddd49))
+
+# [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

@@ -2,7 +2,7 @@
 
 Sub-agents extension for [pi](https://github.com/badlogic/pi-mono) coding agent.
 
-Delegates tasks to isolated pi child processes — each running with its own model, system prompt, and tool set. Sub-agents inherit zero conversation context; all necessary context must be provided in the task description.
+Delegates tasks to isolated pi child processes — each running with its own model, system prompt, and tool set. Sub-agents start with a fresh session by default; pass `session: "fork"` to branch from the current parent pi session.
 
 ## Install
 
@@ -48,6 +48,23 @@ Or instruct pi to delegate:
 Run the code-reviewer agent on the last three commits
 ```
 
+By default, sub-agents do not inherit parent conversation history. For tasks that need the current conversation, request a forked session:
+
+```ts
+subagent({ agent: "code-reviewer", task: "Review the approach we just discussed", session: "fork" })
+```
+
+`session` is optional and accepts:
+
+| Value | Behavior |
+|-------|----------|
+| `none` | Default. Start a new sub-agent session in the subagents session directory. |
+| `fork` | Fork the current parent session at its active leaf and run the sub-agent with that branched session. |
+
+If `fork` is requested but unavailable, pi-subagents falls back to `none` and shows a warning in the tool details/rendering. Fallback happens when the parent session is not persisted, has no current leaf, the forked session file is not materialized, or the call uses a `cwd` different from the parent session cwd.
+
+The tool prompt also guides the model to choose `session: "fork"` when a delegated task depends on the current conversation, prior discussion, or parent session history, and to keep `session: "none"` for self-contained tasks.
+
 ### Available subagents in the prompt
 
 The extension exposes discovered sub-agents to the model when the active tool set includes `subagent`:
@@ -63,10 +80,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.
+
+### 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.
 
-- `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.
+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 +112,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 +125,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.) |
@@ -145,7 +176,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`). Child processes also receive `PI_SUBAGENT_NAME` and `PI_SUBAGENT_SYSTEM_PROMPT_MODE` so runtime hooks can distinguish append vs. replace behavior.
+These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`). Child processes also receive `PI_SUBAGENT_NAME`, `PI_SUBAGENT_SYSTEM_PROMPT_MODE`, and `PI_SUBAGENT_SESSION` so runtime hooks can distinguish prompt mode and effective session mode.
 
 ## Session storage
 
@@ -157,7 +188,7 @@ Sub-agent sessions are saved as `.jsonl` files for post-hoc debugging:
   └── ...
 ```
 
-Each file contains one JSON object per line — session headers, messages, tool calls, and usage data. Parent pi sessions live in the same project directory (no `subagents/` subdirectory).
+Each file contains one JSON object per line — session headers, messages, tool calls, and usage data. Parent pi sessions live in the same project directory (no `subagents/` subdirectory). When `session: "fork"` succeeds, the branched child session is still written under `subagents/` and points back to the parent session in its header.
 
 ## Development
 

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

@@ -25,6 +25,15 @@ export interface AgentToolLog {
   nested?: AgentProgress;
 }
 
+export type SubagentSessionMode = 'none' | 'fork';
+
+export interface SubagentSessionInfo {
+  requested: SubagentSessionMode;
+  effective: SubagentSessionMode;
+  warning?: string;
+  file?: string;
+}
+
 export interface AgentProgress {
   agent: string;
   status: 'running' | 'done' | 'error';
@@ -34,6 +43,7 @@ export interface AgentProgress {
   startedAt: number;
   elapsedMs: number;
   model?: string;
+  session?: SubagentSessionInfo;
 }
 
 export interface AgentResult extends AgentProgress {
@@ -82,6 +92,7 @@ export interface RunSubagentOptions {
   tempRoot?: string;
   outputArchiveDir?: string;
   agentDir?: string;
+  session?: SubagentSessionInfo;
   resolvePi?: () => Promise<PiResolution> | PiResolution;
   runner?: ProcessRunner;
   fs?: ExecutorFs;
@@ -424,6 +435,7 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     startedAt,
     elapsedMs: now() - startedAt,
     model,
+    session: options.session ?? { requested: 'none', effective: 'none' },
   });
 
   const emit = (status: AgentProgress['status'] = 'running') =>
@@ -461,7 +473,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(','));
@@ -470,6 +482,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       promptFilePath,
     );
     args.push('--session-dir', subagentSessionDir(options.cwd, options.agentDir));
+    if (options.session?.effective === 'fork' && options.session.file) {
+      args.push('--session', options.session.file);
+    }
     args.push(buildTaskArgument(options.task, taskFilePath));
 
     const env: NodeJS.ProcessEnv = {
@@ -478,6 +493,7 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       PI_SUBAGENT_MAX_DEPTH: String(options.agent.maxDepth),
       PI_SUBAGENT_NAME: options.agent.name,
       PI_SUBAGENT_SYSTEM_PROMPT_MODE: options.agent.systemPromptMode,
+      PI_SUBAGENT_SESSION: options.session?.effective ?? 'none',
     };
     const visibleAgents = availableSubagentsForAgent(options.agent, options.availableAgents);
     if (visibleAgents.length > 0) {

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/extensions/subagent-render.ts

@@ -4,6 +4,7 @@ import { numberArg, preview, shortenPath, stringArg } from './tool-args.ts';
 export interface SubagentCallArgs {
   agent?: string;
   task?: string;
+  session?: 'none' | 'fork';
 }
 
 export interface RenderTextOptions {
@@ -195,7 +196,8 @@ export function formatSubagentResultLines(
   options: RenderTextOptions,
 ): SubagentResultLine[] {
   const icon = progress.status === 'error' ? '✗' : progress.status === 'done' ? '✓' : '▸';
-  const statusLine = `${icon} ${progress.agent}${progress.model ? ` (${progress.model})` : ''} — ${
+  const sessionBadge = progress.session?.effective === 'fork' ? ' [fork]' : '';
+  const statusLine = `${icon} ${progress.agent}${sessionBadge}${progress.model ? ` (${progress.model})` : ''} — ${
     progress.tools.length
   } tools · ${elapsedSeconds(progress.elapsedMs)}s`;
   const toolLines = formatToolLineItems(progress, options);
@@ -203,6 +205,9 @@ export function formatSubagentResultLines(
   const lines: SubagentResultLine[] = [
     { text: '', kind: 'blank', singleLine: false },
     { text: statusLine, kind: 'status', singleLine: false },
+    ...(progress.session?.warning
+      ? [{ text: `session: ${progress.session.warning}`, kind: 'hint' as const, singleLine: true }]
+      : []),
     ...toolLines,
   ];
 

package/extensions/subagent-tool.ts

@@ -1,18 +1,24 @@
 import {
   getMarkdownTheme,
   keyHint,
+  SessionManager,
   type AgentToolUpdateCallback,
   type ExtensionAPI,
   type ExtensionContext,
   type ThemeColor,
 } from '@earendil-works/pi-coding-agent';
 import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
 import type { AgentConfig } from './agent-loader.ts';
 import {
   availableSubagentsForAgent,
   type AgentProgress,
   type AgentResult,
   runSubagent,
+  subagentSessionDir,
+  type SubagentSessionInfo,
+  type SubagentSessionMode,
 } from './subagent-executor.ts';
 import {
   contextUsageSeverity,
@@ -30,6 +36,12 @@ const SubagentParams = {
     agent: { type: 'string', description: 'Name of the agent to invoke' },
     task: { type: 'string', description: 'Task to delegate to the agent' },
     cwd: { type: 'string', description: 'Working directory for the agent process' },
+    session: {
+      type: 'string',
+      enum: ['none', 'fork'],
+      description:
+        'Parent session handling: none starts a fresh subagent session, fork branches from the current session',
+    },
   },
   required: ['agent', 'task'],
   additionalProperties: false,
@@ -39,6 +51,7 @@ type SubagentParamsType = {
   agent: string;
   task: string;
   cwd?: string;
+  session?: SubagentSessionMode;
 };
 
 type RegisterablePi = Pick<ExtensionAPI, 'registerTool'>;
@@ -46,6 +59,7 @@ export interface RegisterSubagentToolOptions {
   agents: AgentConfig[];
   run?: typeof runSubagent;
   env?: RecursionEnv;
+  agentDir?: string;
 }
 
 function availableAgentsText(agents: AgentConfig[]): string {
@@ -72,6 +86,76 @@ function toProgressResult(progress: AgentProgress) {
   };
 }
 
+function freshSessionInfo(requested: SubagentSessionMode, warning?: string): SubagentSessionInfo {
+  return {
+    requested,
+    effective: 'none',
+    ...(warning ? { warning } : {}),
+  };
+}
+
+function resolveSubagentSession(
+  requested: SubagentSessionMode | undefined,
+  childCwd: string,
+  ctx: ExtensionContext,
+  agentDir?: string,
+): SubagentSessionInfo {
+  const mode = requested ?? 'none';
+  if (mode === 'none') return freshSessionInfo(mode);
+
+  if (path.resolve(childCwd) !== path.resolve(ctx.cwd)) {
+    return freshSessionInfo(
+      mode,
+      `Requested fork session but cwd differs from the parent session; running with a fresh subagent session instead.`,
+    );
+  }
+
+  const parentSessionFile = ctx.sessionManager?.getSessionFile();
+  if (!parentSessionFile) {
+    return freshSessionInfo(
+      mode,
+      'Requested fork session but the parent session is not persisted; running with a fresh subagent session instead.',
+    );
+  }
+  if (!existsSync(parentSessionFile)) {
+    return freshSessionInfo(
+      mode,
+      'Requested fork session but the parent session file was not materialized; running with a fresh subagent session instead.',
+    );
+  }
+
+  const parentLeafId = ctx.sessionManager?.getLeafId();
+  if (!parentLeafId) {
+    return freshSessionInfo(
+      mode,
+      'Requested fork session but the parent session has no current leaf; running with a fresh subagent session instead.',
+    );
+  }
+
+  try {
+    const forkSource = SessionManager.open(
+      parentSessionFile,
+      subagentSessionDir(childCwd, agentDir),
+      childCwd,
+    );
+    const sessionFile = forkSource.createBranchedSession(parentLeafId);
+    if (!sessionFile || !existsSync(sessionFile)) {
+      return freshSessionInfo(
+        mode,
+        'Requested fork session but the forked session file was not materialized; running with a fresh subagent session instead.',
+      );
+    }
+
+    return { requested: mode, effective: 'fork', file: sessionFile };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return freshSessionInfo(
+      mode,
+      `Requested fork session but creating the fork failed (${message}); running with a fresh subagent session instead.`,
+    );
+  }
+}
+
 type CollapsedTheme = {
   fg: (name: ThemeColor, text: string) => string;
   bold: (text: string) => string;
@@ -224,14 +308,16 @@ export function registerSubagentTool(
 
   const availableSubagents = agents.map((agent) => agent.name);
   const agentNames = [...availableSubagents].sort().join(', ');
+  const sessionGuideline =
+    'Use session: "fork" when the delegated task depends on the current conversation, prior discussion, or parent session history. Use the default session: "none" for self-contained tasks.';
   const promptGuidelines =
-    agentNames.length > 0 ? [`Available subagents: ${agentNames}`] : undefined;
+    agentNames.length > 0 ? [`Available subagents: ${agentNames}`, sessionGuideline] : undefined;
 
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
     description: 'Delegate a task to a named sub-agent running in an isolated pi process.',
-    promptSnippet: 'Delegate isolated tasks with subagent({ agent, task, cwd? }).',
+    promptSnippet: 'Delegate isolated tasks with subagent({ agent, task, cwd?, session? }).',
     promptGuidelines,
     parameters: SubagentParams,
 
@@ -249,13 +335,17 @@ export function registerSubagentTool(
         );
       }
 
+      const childCwd = params.cwd ?? ctx.cwd;
+      const session = resolveSubagentSession(params.session, childCwd, ctx, options.agentDir);
       const result = await runner({
         agent,
         task: params.task,
-        cwd: params.cwd ?? ctx.cwd,
+        cwd: childCwd,
         signal,
         depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
         availableAgents: availableSubagentsForAgent(agent, availableSubagents),
+        agentDir: options.agentDir,
+        session,
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
       });
 

package/package.json

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