feat: support explicit subagent session files

Author: wenerme

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`session_file` for persistent subagent session lanes.** Custom agent frontmatter and the `Agent` tool can now point a subagent at an explicit JSONL session file, e.g. `.agents/sessions/KEY.dev.jsonl`, instead of only choosing a `session_dir` and accepting a generated filename. `session_file` implies persistence, resolves relative paths from the requested agent cwd before worktree isolation is applied, supports `~` and absolute paths, opens existing valid session files for append/resume, and creates missing files at the requested path. This builds on `persist_session` / `session_dir` while making long-running issue-keyed plan/dev/review lanes stable enough for humans and orchestration tools to inspect or continue later.
+
 ## [0.13.0] - 2026-06-30
 
 ### Added

README.md

@@ -18,6 +18,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
+- **Explicit session files** — persist subagents into stable JSONL lanes such as `.agents/sessions/KEY.dev.jsonl`, so humans and orchestration tools can inspect or continue the same role-specific session later
 - **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
@@ -220,13 +221,14 @@ All fields are optional — sensible defaults for everything.
 | `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
 | `persist_session` | `false` | Persist this subagent as a normal pi session instead of keeping the session in memory only. The sidechain output transcript is still written either way |
 | `session_dir` | pi default | Optional session directory when `persist_session: true`; omitted uses pi's normal session location, and relative paths resolve from the agent cwd |
+| `session_file` | — | Optional explicit session JSONL file. Implies persistence; relative paths resolve from the requested agent cwd before worktree isolation is applied; existing files are opened and appended/resumed instead of overwritten |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
 | `isolated` | `false` | Hermetic specialist mode: forces `extensions: false` + `skills: false` + drops `ext:` selectors. Only built-in tools. Distinct from `isolation: worktree` (filesystem) |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
-Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent. `Agent` tool parameters only fill fields the agent config leaves unspecified.
+Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, `isolation`, or `session_file`, those values are locked for that agent. `Agent` tool parameters only fill fields the agent config leaves unspecified.
 
 **Forgiving `model:` resolution.** A `model:` pin is matched against pi's model registry tolerantly, so cosmetic id variations don't silently drop the agent back to the parent's model: `.` and `-` are treated as equivalent in version numbers (`claude-haiku-4.5` ≡ `claude-haiku-4-5`), a trailing `-YYYYMMDD` date stamp is optional (`anthropic/claude-haiku-4-5-20251001` matches an undated registry id and vice-versa), and a `provider/modelId` whose named provider doesn't carry that model retries the bare id against every provider. Precedence is **exact → fuzzy under the named provider → same model under any provider → unavailable**, so an exact match always wins and dated snapshots aren't conflated. If nothing resolves, the pin can't run and the agent inherits the parent model — `/agents → Agent types` flags this case as `(unavailable, fallback: inherit)` and shows the resolved target `(→ provider/id)` when resolution lands on a different provider or version than configured. (This is distinct from [Model Scope](#model-scope) enforcement, which matches the `enabledModels` allowlist by *exact* entry.)
 
@@ -281,6 +283,7 @@ Launch a sub-agent.
 | `max_turns` | number | no | Max agentic turns. Omit for unlimited (default) |
 | `run_in_background` | boolean | no | Run without blocking |
 | `resume` | string | no | Agent ID to resume a previous session |
+| `session_file` | string | no | Explicit session JSONL file. Implies persistence; relative paths resolve from the requested agent cwd before worktree isolation is applied; existing files are opened and appended/resumed |
 | `isolated` | boolean | no | No extension/MCP tools |
 | `isolation` | `"worktree"` | no | Run in an isolated git worktree |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |

src/agent-manager.ts

@@ -70,6 +70,8 @@ interface SpawnOptions {
   bypassQueue?: boolean;
   /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
   isolation?: IsolationMode;
+  /** Explicit session JSONL file. Implies persistence and resumes/appends when it exists. */
+  sessionFile?: string;
   /**
    * Working directory for the agent (absolute path). Default: parent session
    * cwd. The agent's tools operate here, but .pi config (extensions, skills,
@@ -252,6 +254,8 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
+      sessionFile: options.sessionFile,
+      sessionFileCwd: baseCwd,
       // Worktree wins for the working dir (the agent must run in the copy —
       // which, with a custom cwd, was created from that target). Config stays
       // with the parent project when a caller-supplied cwd is in play; it must
@@ -379,7 +383,7 @@ export class AgentManager {
     while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
-      if (!record || record.status !== "queued") continue;
+      if (record?.status !== "queued") continue;
       try {
         this.startAgent(next.id, record, next.args);
       } catch (err) {

src/agent-runner.ts

@@ -2,6 +2,7 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
@@ -206,6 +207,10 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
+  /** Explicit session JSONL file. Implies persistence and resumes/appends when it exists. */
+  sessionFile?: string;
+  /** Base directory used to resolve a relative sessionFile. Defaults to the effective cwd. */
+  sessionFileCwd?: string;
   /**
    * Where .pi config is discovered (project extensions, skills, pi settings,
    * agent memory). Default: same as the working directory. The manager sets
@@ -288,11 +293,20 @@ function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () =>
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+function resolveConfiguredPath(path: string | undefined, cwd: string): string | undefined {
+  if (!path) return undefined;
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+  if (isAbsolute(path)) return path;
+  return resolve(cwd, path);
+}
+
 function resolveConfiguredSessionDir(sessionDir: string | undefined, cwd: string): string | undefined {
-  if (!sessionDir) return undefined;
-  if (sessionDir === "~" || sessionDir.startsWith("~/")) return resolve(homedir(), sessionDir.slice(2));
-  if (isAbsolute(sessionDir)) return sessionDir;
-  return resolve(cwd, sessionDir);
+  return resolveConfiguredPath(sessionDir, cwd);
+}
+
+function resolveConfiguredSessionFile(sessionFile: string | undefined, cwd: string): string | undefined {
+  return resolveConfiguredPath(sessionFile, cwd);
 }
 
 export async function runAgent(
@@ -563,11 +577,19 @@ export async function runAgent(
   });
 
   const settingsManager = SettingsManager.create(configCwd, agentDir);
-  const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, effectiveCwd);
+  const sessionFileInput = options.sessionFile ?? agentConfig?.sessionFile;
+  const sessionConfigCwd = sessionFileInput ? (options.sessionFileCwd ?? effectiveCwd) : effectiveCwd;
+  const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, sessionConfigCwd);
+  const configuredSessionFile = resolveConfiguredSessionFile(sessionFileInput, sessionConfigCwd);
   const defaultSessionDir = process.env.PI_CODING_AGENT_SESSION_DIR ?? settingsManager.getSessionDir?.();
-  const sessionManager = agentConfig?.persistSession
-    ? SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir)
-    : SessionManager.inMemory(effectiveCwd);
+  if (configuredSessionFile) {
+    mkdirSync(dirname(configuredSessionFile), { recursive: true });
+  }
+  const sessionManager = configuredSessionFile
+    ? SessionManager.open(configuredSessionFile, configuredSessionDir ?? dirname(configuredSessionFile), effectiveCwd)
+    : agentConfig?.persistSession
+      ? SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir)
+      : SessionManager.inMemory(effectiveCwd);
 
   const sessionOpts: Parameters<typeof createAgentSession>[0] = {
     cwd: effectiveCwd,

src/custom-agents.ts

@@ -67,6 +67,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       maxTurns: nonNegativeInt(fm.max_turns),
       persistSession: fm.persist_session != null ? fm.persist_session === true : undefined,
       sessionDir: str(fm.session_dir),
+      sessionFile: str(fm.session_file),
       systemPrompt: body.trim(),
       promptMode: fm.prompt_mode === "append" ? "append" : "replace",
       inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,

src/index.ts

@@ -860,6 +860,11 @@ Terse command-style prompts produce shallow, generic work.
           description: "Optional agent ID to resume from. Continues from previous context.",
         }),
       ),
+      session_file: Type.Optional(
+        Type.String({
+          description: "Optional explicit session JSONL file. Implies persistence and resumes/appends when the file exists. Relative paths resolve from the requested agent cwd before worktree isolation is applied.",
+        }),
+      ),
       isolated: Type.Optional(
         Type.Boolean({
           description: "If true, agent gets no extension/MCP tools — only built-in tools.",
@@ -1033,6 +1038,7 @@ Terse command-style prompts produce shallow, generic work.
       const runInBackground = resolvedConfig.runInBackground;
       const isolated = resolvedConfig.isolated;
       const isolation = resolvedConfig.isolation;
+      const sessionFile = resolvedConfig.sessionFile;
 
       const parentModelId = ctx.model?.id;
       const effectiveModelId = model?.id;
@@ -1092,6 +1098,7 @@ Terse command-style prompts produce shallow, generic work.
             max_turns: effectiveMaxTurns,
             isolated: isolated,
             isolation: isolation,
+            session_file: sessionFile,
           });
           const next = scheduler.getNextRun(job.id);
           return textResult(
@@ -1150,6 +1157,7 @@ Terse command-style prompts produce shallow, generic work.
             thinkingLevel: thinking,
             isBackground: true,
             isolation,
+            sessionFile,
             invocation: agentInvocation,
             ...bgCallbacks,
           });
@@ -1276,6 +1284,7 @@ Terse command-style prompts produce shallow, generic work.
           inheritContext,
           thinkingLevel: thinking,
           isolation,
+          sessionFile,
           invocation: agentInvocation,
           signal,
           ...fgCallbacks,

src/invocation-config.ts

@@ -8,6 +8,7 @@ interface AgentInvocationParams {
   inherit_context?: boolean;
   isolated?: boolean;
   isolation?: IsolationMode;
+  session_file?: string;
 }
 
 export function resolveAgentInvocationConfig(
@@ -22,6 +23,7 @@ export function resolveAgentInvocationConfig(
   runInBackground: boolean;
   isolated: boolean;
   isolation?: IsolationMode;
+  sessionFile?: string;
 } {
   return {
     modelInput: agentConfig?.model ?? params.model,
@@ -32,6 +34,7 @@ export function resolveAgentInvocationConfig(
     runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
     isolation: agentConfig?.isolation ?? params.isolation,
+    sessionFile: agentConfig?.sessionFile ?? params.session_file,
   };
 }
 

src/schedule.ts

@@ -43,6 +43,7 @@ export interface NewJobInput {
   max_turns?: number;
   isolated?: boolean;
   isolation?: IsolationMode;
+  session_file?: string;
 }
 
 export class SubagentScheduler {
@@ -106,6 +107,7 @@ export class SubagentScheduler {
       max_turns: input.max_turns,
       isolated: input.isolated,
       isolation: input.isolation,
+      session_file: input.session_file,
       enabled: true,
       createdAt: new Date().toISOString(),
       runCount: 0,
@@ -247,6 +249,7 @@ export class SubagentScheduler {
         isolated: job.isolated,
         thinkingLevel: job.thinking,
         isolation: job.isolation,
+        sessionFile: job.session_file,
       });
     } catch (err) {
       const error = err instanceof Error ? err.message : String(err);

src/types.ts

@@ -45,6 +45,8 @@ export interface AgentConfig {
   persistSession?: boolean;
   /** Optional session directory used when persistSession is true. Omitted = pi's normal session location. */
   sessionDir?: string;
+  /** Optional explicit session JSONL file. Implies persistence and resumes/appends when the file exists. */
+  sessionFile?: string;
   systemPrompt: string;
   promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
@@ -187,6 +189,8 @@ export interface ScheduledSubagent {
   max_turns?: number;
   isolated?: boolean;
   isolation?: IsolationMode;
+  /** Explicit session JSONL file. Implies persistence and resumes/appends when the file exists. */
+  session_file?: string;
 
   // state
   enabled: boolean;

test/agent-manager.test.ts

@@ -580,6 +580,28 @@ describe("AgentManager — SpawnOptions.cwd passthrough (#96)", () => {
     expect(cleanupWorktree).toHaveBeenCalledWith("/", expect.anything(), "test");
   });
 
+  it("worktree isolation resolves explicit session files against the original base cwd", async () => {
+    const { createWorktree } = await import("../src/worktree.js");
+    vi.mocked(createWorktree).mockReturnValueOnce({
+      path: "/wt/copy", branch: "pi-agent-x", baseSha: "abc", workPath: "/wt/copy/sub/dir",
+    });
+    vi.mocked(runAgent).mockClear();
+    resolvedRun();
+
+    manager = new AgentManager();
+    const id = manager.spawn(mockPi, mockCtx, "general-purpose", "test", {
+      description: "test",
+      isolation: "worktree",
+      sessionFile: ".agents/sessions/KEY.dev.jsonl",
+    });
+    await manager.getRecord(id)!.promise;
+
+    const opts = vi.mocked(runAgent).mock.lastCall![3];
+    expect(opts.cwd).toBe("/wt/copy");
+    expect(opts.sessionFile).toBe(".agents/sessions/KEY.dev.jsonl");
+    expect(opts.sessionFileCwd).toBe("/tmp");
+  });
+
   it("plain worktree (no cwd) keeps the historical root working dir even when workPath differs", async () => {
     // Parent session sitting in a repo subdirectory: workPath would point at
     // the copied subdir. Without SpawnOptions.cwd the agent must stay at the