pi-sessions 0.19.0 → 0.20.0

package/README.md

@@ -116,7 +116,7 @@ When a host claims peers, pi-sessions leaves all user-facing coordination and la
 
 Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions tabs show status, age, launch details, and the actions currently available: stop, copy an observation command, or copy a resume command. With a peer-claiming host, only Subagents are shown.
 
-Both launch tools take `goal`, `title` (at most 64 characters), and `requestResponse`, with optional `cwd`, `provider`, `model`, and `thinkingLevel` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). `session_handoff` additionally requires `launch` (`left`, `right`, `up`, `down` when a split backend is available, or `deferred` when enabled). `subagent_launch` has no `launch` parameter. Provider and model must be supplied together.
+Both launch tools take `goal`, `title` (at most 64 characters), and `requestResponse`, with optional `cwd`, `provider`, `model`, and `thinkingLevel` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). `session_handoff` additionally requires `launch` (`left`, `right`, `up`, `down` when a split backend is available, or `deferred` when enabled). `subagent_launch` has no `launch` parameter, but takes an optional `agent` naming an [agent profile](#agent-profiles). Provider and model must be supplied together.
 
 ## Session Messaging
 
@@ -236,6 +236,27 @@ Subagents require the handoff and messaging features. Limit recursive delegation
 
 `contextLimit` sets a max context limit before compaction is triggered. It works identically to setting a global value in pi itself, but only applies to subagents.
 
+### Agent profiles
+
+An agent profile lets `subagent_launch` start a subagent with extra instructions, a pinned model, and a thinking level, by name. Profiles are Markdown files in `~/.pi/agent/agents/`, in Claude Code's subagent format, so the same file works in both:
+
+```markdown
+---
+name: oracle
+description: Read-only second opinion on a plan, diff, or hard bug. Use for reviews and high-impact judgment calls.
+model: anthropic/claude-fable-5-1:high
+---
+
+You are the Oracle: a read-only reviewer. Do not modify files. ...
+```
+
+- `name` must match the file name, and `description` tells the calling agent when to use the profile; both are required. The `subagent_launch` prompt guidelines list every valid profile with its description.
+- `model` is a pi model pattern (`provider/id` or a bare id, optionally with `:<thinking>`), and `thinkingLevel` sets the level separately. Explicit `provider`/`model` and `thinkingLevel` on the launch win, and the resolved model must still be on the handoff roster.
+- `tools` is a comma-separated allowlist passed to `--tools`; `submit_task_report` is always kept. Without it, the subagent has every tool.
+- The body is added to the subagent's system prompt, in the subagent section after its standard instructions; `AGENTS.md`, extensions, and the report flow are unchanged. The instructions are stored in the child session when it launches, so later edits to the file don't change a running subagent.
+
+Naming a missing or malformed profile fails the launch with the reason. Profiles apply only to subagents, not to `session_handoff`. Move the directory with `sessions.subagents.agentsDir` (an absolute path or one starting with `~/`).
+
 ## Session Index
 
 The index is a shared cache of your transcripts, used by search, messaging, and the other session features. Pi checks transcripts at startup and syncs files that changed, including sessions run without pi-sessions loaded. Missing, older-schema, or unreadable indexes rebuild automatically in the background; unreadable databases are moved aside rather than overwritten. A malformed transcript is skipped and reported.

package/extensions/session-handoff/agent-profiles.ts

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { formatError } from "../shared/errors.ts";
+import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
+import { parseTypeBoxValue } from "../shared/typebox.ts";
+
+// Claude Code's subagent file format, so one file can serve several harnesses.
+// Keys other harnesses define, such as Claude Code's `color`, are ignored.
+const AGENT_PROFILE_FRONTMATTER_SCHEMA = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  description: Type.String({ minLength: 1 }),
+  model: Type.Optional(Type.String({ minLength: 1 })),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+  tools: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+export interface AgentProfile {
+  name: string;
+  description: string;
+  /** A Pi model pattern; a `:<thinking>` suffix travels with the model it names. */
+  model: string | undefined;
+  thinkingLevel: ThinkingLevel | undefined;
+  /** An allowlist for the child's `--tools`, or undefined to inherit every tool. */
+  tools: readonly string[] | undefined;
+  instructions: string;
+}
+
+export interface AgentProfileCatalog {
+  profiles: readonly AgentProfile[];
+  /** Validation errors by file name, so a launch naming a broken profile reports why. */
+  invalid: ReadonlyMap<string, string>;
+}
+
+export const EMPTY_AGENT_PROFILE_CATALOG: AgentProfileCatalog = {
+  profiles: [],
+  invalid: new Map(),
+};
+
+export function loadAgentProfiles(dir: string): AgentProfileCatalog {
+  let fileNames: string[];
+  try {
+    fileNames = readdirSync(dir)
+      .filter((fileName) => fileName.endsWith(".md"))
+      .sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return EMPTY_AGENT_PROFILE_CATALOG;
+    }
+    throw error;
+  }
+
+  const profiles: AgentProfile[] = [];
+  const invalid = new Map<string, string>();
+  for (const fileName of fileNames) {
+    const path = join(dir, fileName);
+    try {
+      profiles.push(parseAgentProfile(path, readFileSync(path, "utf8")));
+    } catch (error) {
+      invalid.set(basename(fileName, ".md"), `${path}: ${formatError(error)}`);
+    }
+  }
+  return { profiles, invalid };
+}
+
+export function parseAgentProfile(path: string, content: string): AgentProfile {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const fields = parseTypeBoxValue(AGENT_PROFILE_FRONTMATTER_SCHEMA, frontmatter, "frontmatter");
+  const fileName = basename(path, ".md");
+  if (fields.name !== fileName) {
+    throw new Error(`name "${fields.name}" must match the file name "${fileName}".`);
+  }
+  const instructions = body.trim();
+  if (!instructions) {
+    throw new Error("the body must hold the profile's instructions.");
+  }
+  const tools = fields.tools
+    ?.split(",")
+    .map((tool) => tool.trim())
+    .filter(Boolean);
+  if (tools?.length === 0) {
+    throw new Error("tools must name at least one tool.");
+  }
+
+  return {
+    name: fields.name,
+    description: fields.description.replace(/\s+/g, " ").trim(),
+    model: fields.model?.trim(),
+    thinkingLevel: fields.thinkingLevel,
+    tools,
+    instructions,
+  };
+}
+
+export function requireAgentProfile(catalog: AgentProfileCatalog, name: string): AgentProfile {
+  const profile = catalog.profiles.find((candidate) => candidate.name === name);
+  if (profile) {
+    return profile;
+  }
+  const error = catalog.invalid.get(name);
+  if (error) {
+    throw new Error(`Agent profile "${name}" is invalid: ${error}`);
+  }
+  const available = catalog.profiles.map((candidate) => candidate.name).join(", ");
+  throw new Error(
+    `Unknown agent profile "${name}". Available agent profiles: ${available || "none"}.`,
+  );
+}

package/extensions/session-handoff/install.ts

@@ -8,6 +8,11 @@ import { isTuiMode } from "../shared/pi-mode.ts";
 import type { SessionSettings } from "../shared/settings.ts";
 import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import {
+  type AgentProfileCatalog,
+  EMPTY_AGENT_PROFILE_CATALOG,
+  loadAgentProfiles,
+} from "./agent-profiles.ts";
 import { type HandoffBoardServices, openHandoffBoard } from "./board.ts";
 import { consumePendingHandoffBootstrap } from "./bootstrap.ts";
 import { renderHandoffBootstrapFailedEntry } from "./bootstrap-failed-renderer.ts";
@@ -64,9 +69,11 @@ export function installHandoff(
     models: readonly Model<Api>[],
     launchTargets: readonly HandoffLaunchTarget[],
     roster: HandoffRoster | undefined,
+    agentProfiles: AgentProfileCatalog,
     name: "session_handoff" | "subagent_launch",
   ): void {
     const offersSubagent = offersSubagentLaunch(launchTargets);
+    const offersAgents = name === "subagent_launch" && agentProfiles.profiles.length > 0;
     pi.registerTool({
       name,
       label: "Session Handoff",
@@ -76,7 +83,12 @@ export function installHandoff(
       promptSnippet: offersSubagent
         ? "Delegate bounded work to a background subagent"
         : "Hand off context to another Pi session",
-      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
+      promptGuidelines: buildHandoffPromptGuidelines(
+        launchTargets,
+        models,
+        roster,
+        offersAgents ? agentProfiles.profiles : [],
+      ),
       parameters: Type.Object({
         goal: Type.String({
           description:
@@ -117,6 +129,16 @@ export function installHandoff(
             },
           ),
         ),
+        ...(offersAgents
+          ? {
+              agent: Type.Optional(
+                Type.String({
+                  description:
+                    "Agent profile to run the subagent as. The profile adds instructions to the subagent's system prompt and may set its model and thinking level; explicit provider/model and thinkingLevel take precedence.",
+                }),
+              ),
+            }
+          : {}),
       }),
       renderCall(args, theme, context) {
         const state = context.state as HandoffToolRendererState;
@@ -151,14 +173,18 @@ export function installHandoff(
         if (typeof launch !== "string") throw new Error("session_handoff requires launch.");
         if (name === "subagent_launch" && !deps.getLaunchTargets?.().length)
           throw new Error("Subagent launch is unavailable.");
+        const { agent, ...rest } = params;
+        if (agent !== undefined && typeof agent !== "string")
+          throw new Error("agent must name an agent profile.");
         const modelRuntime = await deps.getModelRuntime(ctx.modelRegistry);
         return executeSessionHandoffTool(
           pi,
-          { ...params, launch },
+          { ...rest, launch, ...(agent === undefined ? {} : { agent }) },
           ctx,
           modelRuntime,
           launchTargets,
           roster,
+          agentProfiles,
           (sessionId, status) => clipboardStatusBySessionId.set(sessionId, status),
         );
       },
@@ -222,6 +248,10 @@ export function installHandoff(
         patterns: settings.handoff.roster,
         scopedModels: ctx.scopedModels,
       });
+      const subagentTargets = deps.getLaunchTargets?.() ?? [];
+      const agentProfiles = subagentTargets.length
+        ? loadAgentProfiles(settings.subagents.agentsDir)
+        : EMPTY_AGENT_PROFILE_CATALOG;
       if (!deps.claimsPeers?.()) {
         registerHandoffTool(
           models,
@@ -232,15 +262,15 @@ export function installHandoff(
             additionalTargets: [],
           }),
           roster,
+          EMPTY_AGENT_PROFILE_CATALOG,
           "session_handoff",
         );
         pi.setActiveTools([...new Set([...pi.getActiveTools(), "session_handoff"])]);
       } else {
         pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "session_handoff"));
       }
-      const subagentTargets = deps.getLaunchTargets?.() ?? [];
       if (subagentTargets.length) {
-        registerHandoffTool(models, subagentTargets, roster, "subagent_launch");
+        registerHandoffTool(models, subagentTargets, roster, agentProfiles, "subagent_launch");
         pi.setActiveTools([...new Set([...pi.getActiveTools(), "subagent_launch"])]);
       } else {
         pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "subagent_launch"));

package/extensions/session-handoff/launch-target.ts

@@ -2,7 +2,7 @@ import type { SessionManager } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { formatError } from "../shared/errors.ts";
 import type { ClipboardStatus, LaunchBackend } from "./launch/backend.ts";
-import type { HandoffSubagent } from "./metadata.ts";
+import type { HandoffSubagent, HandoffSubagentAgent } from "./metadata.ts";
 import type { PreparedHandoff } from "./spawn.ts";
 
 export const DEFERRED_LAUNCH = "deferred" as const;
@@ -61,11 +61,14 @@ export interface HandoffLaunchTarget {
   /** Unattended children skip the startup trust prompt; watched ones let the user answer it. */
   approveProjectTrust: boolean;
   useDefaultSessionDir?: boolean;
+  /** Tools the child keeps when an agent profile narrows its tool allowlist. */
+  requiredTools?: readonly string[];
   /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
     ownerSessionId: string;
     requestResponse: boolean;
+    agent: HandoffSubagentAgent | undefined;
   }): HandoffSubagent;
   prepareChild(input: HandoffLaunchTargetPreparation): void;
   launch(input: HandoffLaunchTargetInput): Promise<HandoffLaunchTargetOutcome>;

package/extensions/session-handoff/metadata.ts

@@ -20,6 +20,14 @@ export const HANDOFF_STALE_SESSION_MESSAGE =
 export const SESSION_STARTING_MESSAGE =
   "Target session is still starting. wait for session_reachable to report it as live, then resend.";
 
+// An agent profile's instructions travel with the child, which adds them to
+// its subagent prompt section, so they survive wakes and restarts without
+// depending on the profile file.
+export const HANDOFF_SUBAGENT_AGENT_SCHEMA = Type.Object({
+  name: Type.String(),
+  instructions: Type.String(),
+});
+
 // A subagent's self-knowledge, stamped into its child-local bootstrap so the
 // child never opens the parent transcript to learn who it is.
 export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
@@ -27,6 +35,7 @@ export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
   ownerSessionId: Type.String(),
   depth: Type.Integer({ minimum: 1 }),
   requestResponse: Type.Boolean(),
+  agent: Type.Optional(HANDOFF_SUBAGENT_AGENT_SCHEMA),
 });
 
 const HANDOFF_METADATA_BASE = {
@@ -84,6 +93,7 @@ export const HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA = Type.Object({
 });
 
 export type HandoffSubagent = Static<typeof HANDOFF_SUBAGENT_SCHEMA>;
+export type HandoffSubagentAgent = Static<typeof HANDOFF_SUBAGENT_AGENT_SCHEMA>;
 export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 export type ChildGeneratedHandoffBootstrap = HandoffBootstrap;

package/extensions/session-handoff/model.ts

@@ -52,6 +52,28 @@ export function resolveChildModel(
   return { model, thinkingLevel: level };
 }
 
+/**
+ * Resolves an agent profile's model. The pattern is user-written, so it gets Pi's
+ * CLI grammar, but the model it lands on must still clear the roster.
+ */
+export function resolveProfileModel(
+  modelRuntime: ModelRuntime,
+  roster: HandoffRoster | undefined,
+  modelPattern: string,
+  thinkingLevel: ThinkingLevel | undefined,
+): HandoffModelOverride {
+  const resolved = resolveModelPattern(modelRuntime, modelPattern, thinkingLevel);
+  if (!roster) {
+    return resolved;
+  }
+  return resolveChildModel(
+    modelRuntime,
+    roster,
+    { provider: resolved.model.provider, modelId: resolved.model.id },
+    resolved.thinkingLevel,
+  );
+}
+
 /**
  * Resolves a user-configured model pattern with Pi's CLI grammar, including fuzzy
  * aliases. Only for settings the user writes by hand; never for a model's choice.

package/extensions/session-handoff/spawn.ts

@@ -21,6 +21,7 @@ export function prepareHandoffLaunch(options: {
   parentSessionFile: string;
   title: string;
   model: string | undefined;
+  tools: readonly string[] | undefined;
   approveProjectTrust: boolean;
   useDefaultSessionDir?: boolean;
   buildBootstrap: (sessionId: string) => HandoffBootstrap;
@@ -54,6 +55,7 @@ export function prepareHandoffLaunch(options: {
     sessionId: manager.getSessionId(),
     sessionDir: manager.usesDefaultSessionDir() ? undefined : manager.getSessionDir(),
     model: options.model,
+    tools: options.tools,
     approveProjectTrust: options.approveProjectTrust,
   });
 
@@ -94,6 +96,7 @@ export function buildPiResumeCommand(options: {
   sessionId: string;
   sessionDir?: string | undefined;
   model?: string | undefined;
+  tools?: readonly string[] | undefined;
   approveProjectTrust: boolean;
 }): string {
   const args = ["pi"];
@@ -107,6 +110,9 @@ export function buildPiResumeCommand(options: {
   if (options.model) {
     args.push("--model", shellQuote(options.model));
   }
+  if (options.tools) {
+    args.push("--tools", shellQuote(options.tools.join(",")));
+  }
 
   const command = args.join(" ");
   return options.targetCwd === options.parentCwd

package/extensions/session-handoff/tool-schema.ts

@@ -1,5 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import type { AgentProfile } from "./agent-profiles.ts";
 import {
   DEFERRED_LAUNCH,
   type HandoffLaunchTarget,
@@ -42,10 +43,14 @@ const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
 const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
   "Only override the model when the task clearly warrants it.";
 
+const AGENT_PROFILE_GUIDELINE =
+  "Set agent to run a subagent as one of the agent profiles below when its description fits the task; the profile supplies the model, so leave provider, model, and thinkingLevel unset unless the user asks otherwise.";
+
 export function buildHandoffPromptGuidelines(
   targets: readonly HandoffLaunchTarget[],
   models: readonly Model<Api>[],
   roster: HandoffRoster | undefined,
+  agentProfiles: readonly AgentProfile[],
 ): string[] {
   const hasSubagent = offersSubagentLaunch(targets);
   const userFacingKinds = describeUserFacingLaunchKinds(targets);
@@ -62,6 +67,14 @@ export function buildHandoffPromptGuidelines(
       ? [`Available models, given as provider/model-id: ${selectable.join(", ")}.`]
       : []),
     ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
+    ...(agentProfiles.length > 0
+      ? [
+          AGENT_PROFILE_GUIDELINE,
+          ...agentProfiles.map(
+            (profile) => `Agent profile "${profile.name}": ${profile.description}`,
+          ),
+        ]
+      : []),
   ];
 }
 

package/extensions/session-handoff/tool.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type AgentProfileCatalog, requireAgentProfile } from "./agent-profiles.ts";
 import { resolveHandoffSource } from "./extract.ts";
 import type { ClipboardStatus } from "./launch/backend.ts";
 import { resolveHandoffLaunchTarget } from "./launch-options.ts";
@@ -10,9 +11,10 @@ import {
   DEFERRED_LAUNCH,
   type HandoffLaunchTarget,
   type HandoffLaunchValue,
+  SUBAGENT_LAUNCH,
 } from "./launch-target.ts";
 import { createChildGeneratedHandoffBootstrap } from "./metadata.ts";
-import { formatModelArgument, resolveChildModel } from "./model.ts";
+import { formatModelArgument, resolveChildModel, resolveProfileModel } from "./model.ts";
 import { buildLaunchReceipt } from "./receipt.ts";
 import type { HandoffRoster } from "./roster.ts";
 import { formatHandoffLaunchFailure, prepareHandoffLaunch } from "./spawn.ts";
@@ -32,6 +34,7 @@ export interface HandoffToolParams {
   provider?: string | undefined;
   model?: string | undefined;
   thinkingLevel?: ThinkingLevel | undefined;
+  agent?: string | undefined;
 }
 
 export async function executeSessionHandoffTool(
@@ -41,6 +44,7 @@ export async function executeSessionHandoffTool(
   modelRuntime: ModelRuntime,
   launchTargets: readonly HandoffLaunchTarget[],
   roster: HandoffRoster | undefined,
+  agentProfiles: AgentProfileCatalog,
   recordClipboardStatus: (sessionId: string, status: ClipboardStatus) => void,
 ) {
   const goal = params.goal.trim();
@@ -61,6 +65,11 @@ export async function executeSessionHandoffTool(
   }
 
   const { target, degradedFrom } = resolveHandoffLaunchTarget(params.launch, launchTargets);
+  if (params.agent !== undefined && target.value !== SUBAGENT_LAUNCH) {
+    throw new Error("Agent profiles apply only to subagent launches.");
+  }
+  const profile =
+    params.agent === undefined ? undefined : requireAgentProfile(agentProfiles, params.agent);
 
   const targetCwd = resolveHandoffCwd(ctx.cwd, params.cwd);
   if (targetCwd.error) {
@@ -90,12 +99,15 @@ export async function executeSessionHandoffTool(
   if (Boolean(provider) !== Boolean(modelId)) {
     throw new Error("session_handoff requires provider and model together, or neither.");
   }
+  const requestedThinkingLevel = params.thinkingLevel ?? profile?.thinkingLevel;
   const override =
     provider && modelId
-      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, params.thinkingLevel)
-      : undefined;
+      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, requestedThinkingLevel)
+      : profile?.model
+        ? resolveProfileModel(modelRuntime, roster, profile.model, requestedThinkingLevel)
+        : undefined;
   const childModel = override?.model ?? ctx.model;
-  const thinkingLevel = override?.thinkingLevel ?? params.thinkingLevel ?? pi.getThinkingLevel();
+  const thinkingLevel = override?.thinkingLevel ?? requestedThinkingLevel ?? pi.getThinkingLevel();
   const model = formatModelArgument(childModel, thinkingLevel);
   if (!model) {
     throw new Error("No active model is available for the handoff.");
@@ -107,6 +119,7 @@ export async function executeSessionHandoffTool(
     parentSessionFile,
     title,
     model,
+    tools: profile?.tools && [...new Set([...profile.tools, ...(target.requiredTools ?? [])])],
     approveProjectTrust: target.approveProjectTrust,
     useDefaultSessionDir: target.useDefaultSessionDir ?? false,
     buildBootstrap: (sessionId) =>
@@ -123,6 +136,7 @@ export async function executeSessionHandoffTool(
           childSessionId: sessionId,
           ownerSessionId: ctx.sessionManager.getSessionId(),
           requestResponse,
+          agent: profile && { name: profile.name, instructions: profile.instructions },
         }),
       }),
     prepareChild: (manager, childSessionId) =>

package/extensions/shared/settings.ts

@@ -23,6 +23,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       enable: Type.Optional(Type.Boolean()),
       maxDepth: Type.Optional(Type.Integer({ minimum: 0 })),
       contextLimit: Type.Optional(Type.Integer({ minimum: 1 })),
+      agentsDir: Type.Optional(Type.String()),
     }),
   ),
   handoff: Type.Optional(
@@ -125,6 +126,8 @@ export interface SessionSettings {
     maxDepth: number;
     /** Effective context window for a subagent, when smaller than its model's. */
     contextLimit?: number;
+    /** Where agent profiles for subagent launches live. */
+    agentsDir: string;
   };
   handoff: HandoffSettings;
   index: {
@@ -140,6 +143,10 @@ export function getDefaultIndexDir(): string {
   return path.join(getAgentDir(), "pi-sessions");
 }
 
+export function getDefaultAgentsDir(): string {
+  return path.join(getAgentDir(), "agents");
+}
+
 export function getDefaultIndexPath(): string {
   return path.join(getDefaultIndexDir(), "index.sqlite");
 }
@@ -168,19 +175,19 @@ function expandHome(rawPath: string): string {
   return rawPath;
 }
 
-function normalizeIndexDir(value: string | undefined): string {
+function normalizeDir(value: string | undefined, defaultDir: string, key: string): string {
   if (value === undefined) {
-    return getDefaultIndexDir();
+    return defaultDir;
   }
 
   const trimmed = value.trim();
   if (trimmed.length === 0) {
-    return getDefaultIndexDir();
+    return defaultDir;
   }
 
   const expanded = expandHome(trimmed);
   if (!path.isAbsolute(expanded)) {
-    throw new Error('sessions.index.dir must be an absolute path or start with "~/".');
+    throw new Error(`${key} must be an absolute path or start with "~/".`);
   }
 
   return path.normalize(expanded);
@@ -254,7 +261,11 @@ function resolveFeatureToggles(value: SessionFileSettings): FeatureToggles {
 }
 
 function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSettings {
-  const indexDir = normalizeIndexDir(fileSettings.index?.dir);
+  const indexDir = normalizeDir(
+    fileSettings.index?.dir,
+    getDefaultIndexDir(),
+    "sessions.index.dir",
+  );
 
   return {
     features: resolveFeatureToggles(fileSettings),
@@ -263,6 +274,11 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       ...(fileSettings.subagents?.contextLimit === undefined
         ? {}
         : { contextLimit: fileSettings.subagents.contextLimit }),
+      agentsDir: normalizeDir(
+        fileSettings.subagents?.agentsDir,
+        getDefaultAgentsDir(),
+        "sessions.subagents.agentsDir",
+      ),
     },
     handoff: {
       ...resolveAgentModelSettings(fileSettings.handoff),

package/extensions/subagents/install.ts

@@ -149,7 +149,10 @@ export function installSubagents(
 
   pi.on("before_agent_start", (event) => {
     if (current?.child) {
-      event.systemPromptOptions.sections[SUBAGENT_PROMPT_SECTION] = SUBAGENT_PROMPT;
+      const agent = current.child.identity.agent;
+      event.systemPromptOptions.sections[SUBAGENT_PROMPT_SECTION] = agent
+        ? `${SUBAGENT_PROMPT}\n\n${agent.instructions}`
+        : SUBAGENT_PROMPT;
     }
   });
 
@@ -166,12 +169,12 @@ export function installSubagents(
 
   pi.on("agent_start", (_event, ctx) => {
     settledChildLifecycle.cancel();
-    if (current?.child) {
+    if (current?.child && !current.child.paused) {
       current.child.reportsAtTurnStart = countSubagentReports(ctx.sessionManager.getBranch());
     }
   });
 
-  pi.on("agent_settled", async (_event, ctx) => {
+  pi.on("agent_settled", async (event, ctx) => {
     const session = current;
     if (!session || session.parent.sessionId !== ctx.sessionManager.getSessionId()) {
       return;
@@ -187,7 +190,11 @@ export function installSubagents(
     }
     if (session.child) {
       await contextLimit.compactIfOverLimit(ctx);
-      await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
+      // Escape in the child's pane pauses the delegated turn; it still owes its parent a report.
+      session.child.paused = event.aborted;
+      if (!event.aborted) {
+        await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
+      }
     }
   });
 

package/extensions/subagents/launch-target.ts

@@ -21,12 +21,14 @@ export function createSubagentLaunchTarget(
       "'subagent' delegates one task to a detached tmux worker and requests a report by default.",
     bootstrapMode: "automatic",
     approveProjectTrust: true,
+    requiredTools: ["submit_task_report"],
     describeSubagentChild(input) {
       return {
         childSessionId: input.childSessionId,
         ownerSessionId: input.ownerSessionId,
         depth: state.depth + 1,
         requestResponse: input.requestResponse,
+        ...(input.agent ? { agent: input.agent } : {}),
       };
     },
     prepareChild(input) {

package/extensions/subagents/settle.ts

@@ -17,6 +17,7 @@ export interface SubagentChildSessionState {
   identity: HandoffSubagent;
   requestResponse: boolean;
   reportsAtTurnStart: number;
+  paused: boolean;
 }
 
 export interface SettledChildParentSession {
@@ -159,6 +160,7 @@ export function refreshSubagentChildState(
     identity,
     requestResponse: identity.requestResponse,
     reportsAtTurnStart: reports,
+    paused: false,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,10 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@earendil-works/pi-agent-core": "^1.2.0",
-    "@earendil-works/pi-ai": "^1.2.0",
-    "@earendil-works/pi-coding-agent": "^1.2.0",
-    "@earendil-works/pi-tui": "^1.2.0",
+    "@earendil-works/pi-agent-core": "^1.3.0",
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0",
     "@types/node": "^24.13.3",
     "strip-ansi": "^7.2.0",
     "typebox": "1.3.27",