@johnnywu/pi-subagents 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.1.1](https://github.com/jwu/pi-subagents/compare/v2.1.0...v2.1.1) (2026-07-21)
+
+
+### Bug Fixes
+
+* migrate model registry to Pi 0.80 runtime ([00026d6](https://github.com/jwu/pi-subagents/commit/00026d6e6aaea112896f358c0f86d20f48e73318))
+
+# [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)
 
 

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`:
@@ -159,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
 
@@ -171,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/subagent-executor.ts

@@ -1,4 +1,8 @@
-import { AuthStorage, ModelRegistry, withFileMutationQueue } from '@earendil-works/pi-coding-agent';
+import {
+  ModelRegistry,
+  ModelRuntime,
+  withFileMutationQueue,
+} from '@earendil-works/pi-coding-agent';
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
@@ -25,6 +29,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 +47,7 @@ export interface AgentProgress {
   startedAt: number;
   elapsedMs: number;
   model?: string;
+  session?: SubagentSessionInfo;
 }
 
 export interface AgentResult extends AgentProgress {
@@ -82,6 +96,7 @@ export interface RunSubagentOptions {
   tempRoot?: string;
   outputArchiveDir?: string;
   agentDir?: string;
+  session?: SubagentSessionInfo;
   resolvePi?: () => Promise<PiResolution> | PiResolution;
   runner?: ProcessRunner;
   fs?: ExecutorFs;
@@ -424,6 +439,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') =>
@@ -455,10 +471,11 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     }
 
     const pi = await resolvePi();
-    const modelRegistry = ModelRegistry.create(
-      AuthStorage.create(options.agentDir ? path.join(options.agentDir, 'auth.json') : undefined),
-      options.agentDir ? path.join(options.agentDir, 'models.json') : undefined,
-    );
+    const runtime = await ModelRuntime.create({
+      authPath: options.agentDir ? path.join(options.agentDir, 'auth.json') : undefined,
+      modelsPath: options.agentDir ? path.join(options.agentDir, 'models.json') : undefined,
+    });
+    const modelRegistry = new ModelRegistry(runtime);
     const args = [pi.entryPoint, '--mode', 'json', '-p', '--no-skills', '--no-prompt-templates'];
 
     if (options.agent.systemPromptMode === 'replace-all') args.push('--no-context-files');
@@ -470,6 +487,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 +498,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-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": "2.0.0",
+  "version": "2.1.1",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {
@@ -82,7 +82,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.80.10",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },