@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.5

package/src/agent-source-badge.ts

@@ -0,0 +1,75 @@
+/**
+ * agent-source-badge.ts — How `/agents → Agent types` shows where an agent came
+ * from: the per-row badge, the legend that explains the badges actually on
+ * screen, and the description line under the highlighted row.
+ *
+ * These live outside src/index.ts for the same reason as agent-file-toggle.ts:
+ * the `/agents` handler is a large closure reached only through
+ * `registerCommand`, which every test mocks, so nothing inside it can be
+ * asserted on directly.
+ *
+ * The badges are deliberately terse — the list is one row per agent and the
+ * model already occupies the right-hand column. Anything wordier than a glyph
+ * (the package's name, in particular) goes on the description line, which
+ * `SettingsList` renders for the highlighted row only.
+ */
+
+import type { AgentConfig } from "./types.js";
+
+/**
+ * The badge column: a two-cell glyph plus a space, so every label starts at the
+ * same offset whether or not the agent is badged.
+ *
+ * Built-in defaults are unmarked. They are the majority of the list, and a
+ * badge on them would make the three that matter — the agents the user or a
+ * package put there — harder to pick out, not easier.
+ */
+export function sourceIndicator(cfg: AgentConfig | undefined): string {
+  const disabled = cfg?.enabled === false;
+  if (cfg?.source === "project") return disabled ? "✕• " : "•  ";
+  if (cfg?.source === "global") return disabled ? "✕◦ " : "◦  ";
+  if (cfg?.source === "package") return disabled ? "✕▪ " : "▪  ";
+  if (disabled) return "✕  ";
+  return "   ";
+}
+
+/**
+ * The legend line, naming only the badges the given roster actually renders.
+ *
+ * Keyed on what `sourceIndicator` would emit, so the two cannot drift into a
+ * glyph with no key (which is what `▪` was) or a key for a glyph that is not on
+ * screen. A defaults-only roster returns "", and the caller omits the line.
+ *
+ * `source` is undefined for built-in defaults — the `"default"` member of the
+ * union is declared but never assigned, since default-agents.ts sets only
+ * `isDefault` — so they contribute no key, matching their blank badge.
+ */
+export function sourceLegend(cfgs: readonly (AgentConfig | undefined)[]): string {
+  const parts: string[] = [];
+  if (cfgs.some(c => c?.source === "project")) parts.push("• = project");
+  if (cfgs.some(c => c?.source === "global")) parts.push("◦ = global");
+  if (cfgs.some(c => c?.source === "package")) parts.push("▪ = package");
+  if (cfgs.some(c => c?.enabled === false)) parts.push("✕ = disabled");
+  return parts.join("  ");
+}
+
+/**
+ * The description line under the highlighted row.
+ *
+ * `packageName` is the one piece of provenance a badge cannot carry: with two
+ * agent-providing packages installed, `▪` says only that *some* package won.
+ * It is prefixed rather than appended so it stays visible when a long
+ * description wraps, and it prefixes "(disabled)" too — a disabled package
+ * agent is exactly the case where you want to know whose it was.
+ *
+ * Falls back to the agent's own name when it has no description, which is what
+ * a hand-written agent file without one already showed.
+ */
+export function rowDescription(
+  name: string,
+  cfg: AgentConfig | undefined,
+  packageName?: string,
+): string {
+  const base = cfg?.enabled === false ? "(disabled)" : (cfg?.description ?? name);
+  return packageName ? `${packageName} · ${base}` : base;
+}

package/src/agent-types.ts

@@ -0,0 +1,346 @@
+/**
+ * agent-types.ts — Unified agent type registry.
+ *
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md, .agents/agents/*.md, and global agents.
+ * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
+ */
+
+import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_AGENTS } from "./default-agents.js";
+import type { AgentConfig } from "./types.js";
+
+/**
+ * All known built-in tool names, derived from pi's own tool factories rather
+ * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
+ * `createCodingTools` → read/bash/edit/write; `createReadOnlyTools` →
+ * read/grep/find/ls; their de-duplicated union is the 7 built-ins
+ * (read, bash, edit, write, grep, find, ls). The `cwd` only binds tool
+ * operations we never invoke here — we read each tool's `.name` and discard it.
+ */
+export const BUILTIN_TOOL_NAMES: string[] = [
+  ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
+];
+
+/** Unified runtime registry of all agents (defaults + user-defined). */
+const agents = new Map<string, AgentConfig>();
+
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+
+/** Check whether default agents are disabled. */
+export function isDefaultsDisabled(): boolean { return disableDefaults; }
+
+/** Set whether default agents are disabled. */
+export function setDefaultsDisabled(b: boolean): void { disableDefaults = b; }
+
+/** `fallbackSubagent` value that disables the fallback entirely (strict dispatch). */
+export const NO_FALLBACK = "none";
+
+/**
+ * Agent type substituted when a caller-supplied `subagent_type` doesn't resolve
+ * to exactly one enabled agent. `undefined` keeps the historical behavior
+ * (general-purpose); `NO_FALLBACK` makes dispatch fail closed. Set from
+ * `subagents.json` (`fallbackSubagent`).
+ *
+ * Module state rather than an index.ts closure because every caller-supplied
+ * spawn path needs it — the Agent tool, the scheduler, and cross-extension RPC.
+ */
+let fallbackSubagent: string | undefined;
+
+/** Get the configured fallback agent type. undefined = general-purpose. */
+export function getFallbackSubagent(): string | undefined { return fallbackSubagent; }
+
+/** Set the configured fallback agent type. undefined = general-purpose. */
+export function setFallbackSubagent(v: string | undefined): void { fallbackSubagent = v; }
+
+/**
+ * Build a registry map: DEFAULT_AGENTS first (unless disabled via settings),
+ * then user agents overlaid on top (same name overrides the default).
+ * Pure — callers that must not disturb the process-wide registry (nested
+ * delegation resolving agents from its own config root) build their own map.
+ */
+export function buildAgentRegistry(userAgents: Map<string, AgentConfig>): Map<string, AgentConfig> {
+  const registry = new Map<string, AgentConfig>();
+  if (!disableDefaults) {
+    for (const [name, config] of DEFAULT_AGENTS) registry.set(name, config);
+  }
+  for (const [name, config] of userAgents) registry.set(name, config);
+  return registry;
+}
+
+/**
+ * Register agents into the unified registry.
+ * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
+ * Disabled agents (enabled === false) are kept in the registry but excluded from spawning.
+ */
+export function registerAgents(userAgents: Map<string, AgentConfig>): void {
+  agents.clear();
+  for (const [name, config] of buildAgentRegistry(userAgents)) {
+    agents.set(name, config);
+  }
+}
+
+/** Case-insensitive key resolution within a registry. */
+function resolveKeyIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  if (registry.has(name)) return name;
+  const lower = name.toLowerCase();
+  for (const key of registry.keys()) {
+    if (key.toLowerCase() === lower) return key;
+  }
+  return undefined;
+}
+
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+  return resolveKeyIn(agents, name);
+}
+
+/** Resolve a type name case-insensitively in a registry. Returns the canonical key or undefined. */
+export function resolveTypeIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  return resolveKeyIn(registry, name);
+}
+
+/** Get the agent config for a type (case-insensitive) from a registry. */
+export function getAgentConfigIn(registry: Map<string, AgentConfig>, name: string): AgentConfig | undefined {
+  const key = resolveKeyIn(registry, name);
+  return key ? registry.get(key) : undefined;
+}
+
+/** Check if a type is valid and enabled (case-insensitive) in a registry. */
+export function isValidTypeIn(registry: Map<string, AgentConfig>, type: string): boolean {
+  const key = resolveKeyIn(registry, type);
+  if (!key) return false;
+  return registry.get(key)?.enabled !== false;
+}
+
+/** Get all enabled type names in a registry (for spawning and tool descriptions). */
+export function getAvailableTypesIn(registry: Map<string, AgentConfig>): string[] {
+  return [...registry.entries()]
+    .filter(([_, config]) => config.enabled !== false)
+    .map(([name]) => name);
+}
+
+/**
+ * Case-insensitive resolution that refuses to guess. An exact match always wins;
+ * otherwise the name must match exactly one key. Two agents differing only in
+ * case are reachable (`loadCustomAgents` keys by filename across three
+ * directories), and picking whichever came first would silently dispatch a
+ * different agent, model and tool policy than the caller meant.
+ */
+function resolveUnambiguousKeyIn(registry: Map<string, AgentConfig>, name: string): string | undefined {
+  if (registry.has(name)) return name;
+  const lower = name.toLowerCase();
+  const matches = [...registry.keys()].filter(key => key.toLowerCase() === lower);
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+/**
+ * The canonical key for a caller-supplied name that identifies exactly one
+ * ENABLED agent, or undefined. Strict by construction: no fallback, no guessing
+ * between case-variants. Nested delegation resolves with this directly, since
+ * "unknown types are rejected rather than falling back" is its own contract.
+ */
+export function resolveEnabledTypeIn(
+  registry: Map<string, AgentConfig>,
+  requested: unknown,
+): string | undefined {
+  const raw = typeof requested === "string" ? requested.trim() : "";
+  if (!raw) return undefined;
+  const key = resolveUnambiguousKeyIn(registry, raw);
+  return key !== undefined && registry.get(key)?.enabled !== false ? key : undefined;
+}
+
+/** Outcome of resolving a caller-supplied `subagent_type` into a spawnable type. */
+export type SpawnTypeResolution =
+  /** Spawn this type. `fellBackFrom` is set when it isn't what the caller asked for. */
+  | { ok: true; type: string; fellBackFrom?: string }
+  /** Refuse the spawn and return this message to the caller. */
+  | { ok: false; message: string };
+
+/**
+ * Resolve a caller-supplied agent type against a registry, applying the
+ * `fallbackSubagent` policy. The single decision point for every caller-supplied
+ * spawn — the Agent tool, the scheduler, cross-extension RPC, and the nested
+ * tools — so a type that fails here never reaches `runAgent`, where `getConfig`
+ * would silently substitute general-purpose.
+ *
+ * Unknown, disabled, and case-ambiguous names are all treated the same way:
+ * the caller named something that doesn't identify exactly one enabled agent.
+ *
+ * Pure over `registry` — callers that need fresh agent files reload before
+ * calling (the Agent tool already does, per spawn). Reloading here would mean
+ * importing custom-agents.ts, which imports this module.
+ */
+export function resolveSpawnTypeIn(
+  registry: Map<string, AgentConfig>,
+  requested: unknown,
+): SpawnTypeResolution {
+  const raw = typeof requested === "string" ? requested.trim() : "";
+  const available = () => getAvailableTypesIn(registry).join(", ") || "(none)";
+
+  const key = resolveEnabledTypeIn(registry, raw);
+  if (key !== undefined) return { ok: true, type: key };
+
+  // A missing type follows the same policy as a wrong one rather than always
+  // erroring: before this setting existed an empty type fell back like any
+  // other unresolvable name, and only opting in should change that.
+  const reason = raw ? `Unknown or disabled agent type: "${raw}".` : "No agent type given.";
+
+  // Trimmed like `requested`: a padded value set programmatically would
+  // otherwise be reported as a missing agent.
+  const configured = typeof fallbackSubagent === "string" ? fallbackSubagent.trim() : undefined;
+
+  if (configured !== undefined && configured.toLowerCase() === NO_FALLBACK) {
+    return { ok: false, message: `${reason} Available: ${available()}.` };
+  }
+
+  if (configured !== undefined) {
+    // An explicitly configured fallback that is itself unusable is a
+    // misconfiguration, not a second chance to guess — say so rather than
+    // quietly dropping to general-purpose.
+    const fallbackKey = resolveUnambiguousKeyIn(registry, configured);
+    if (fallbackKey === undefined || registry.get(fallbackKey)?.enabled === false) {
+      return {
+        ok: false,
+        message:
+          `${reason} The configured fallbackSubagent "${configured}" is itself ` +
+          `unknown or disabled. Available: ${available()}.`,
+      };
+    }
+    return { ok: true, type: fallbackKey, fellBackFrom: raw };
+  }
+
+  // Unset: historical behavior, deliberately unchanged. #183 asks for the
+  // fallback to remain the default, so the pre-existing hole it leaves — an
+  // unregistered general-purpose resolving to `getConfig`'s all-tools hardcoded
+  // tier — is what `fallbackSubagent: none` is for, not something to close
+  // under everyone silently.
+  return { ok: true, type: "general-purpose", fellBackFrom: raw };
+}
+
+/** Resolve a caller-supplied agent type against the process-wide registry. */
+export function resolveSpawnType(requested: unknown): SpawnTypeResolution {
+  return resolveSpawnTypeIn(agents, requested);
+}
+
+/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+export function resolveType(name: string): string | undefined {
+  return resolveKey(name);
+}
+
+/** Get the agent config for a type (case-insensitive). */
+export function getAgentConfig(name: string): AgentConfig | undefined {
+  return getAgentConfigIn(agents, name);
+}
+
+/** Get all enabled type names (for spawning and tool descriptions). */
+export function getAvailableTypes(): string[] {
+  return getAvailableTypesIn(agents);
+}
+
+/** Get all type names including disabled (for UI listing). */
+export function getAllTypes(): string[] {
+  return [...agents.keys()];
+}
+
+/** Get names of default agents currently in the registry. */
+export function getDefaultAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault === true)
+    .map(([name]) => name);
+}
+
+/** Get names of user-defined agents (non-defaults) currently in the registry. */
+export function getUserAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault !== true)
+    .map(([name]) => name);
+}
+
+/** Check if a type is valid and enabled (case-insensitive). */
+export function isValidType(type: string): boolean {
+  return isValidTypeIn(agents, type);
+}
+
+/** Tool names required for memory management. */
+const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
+
+/**
+ * Get memory tool names (read/write/edit) not already in the provided set.
+ */
+export function getMemoryToolNames(existingToolNames: Set<string>): string[] {
+  return MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
+}
+
+/** Tool names needed for read-only memory access. */
+const READONLY_MEMORY_TOOL_NAMES = ["read"];
+
+/**
+ * Get read-only memory tool names not already in the provided set.
+ */
+export function getReadOnlyMemoryToolNames(existingToolNames: Set<string>): string[] {
+  return READONLY_MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
+}
+
+/** Get built-in tool names for a type (case-insensitive). */
+export function getToolNamesForType(type: string): string[] {
+  const key = resolveKey(type);
+  const raw = key ? agents.get(key) : undefined;
+  const config = raw?.enabled !== false ? raw : undefined;
+  // `undefined` (definition omitted the field) → all built-ins; an explicit `[]`
+  // (`tools: none` or a `tools:` with only `ext:` entries) → zero built-ins.
+  return config?.builtinToolNames ?? [...BUILTIN_TOOL_NAMES];
+}
+
+/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
+export function getConfig(type: string): {
+  displayName: string;
+  color?: string;
+  description: string;
+  builtinToolNames: string[];
+  extensions: true | string[] | false;
+  excludeExtensions?: string[];
+  skills: true | string[] | false;
+  promptMode: "replace" | "append";
+} {
+  const key = resolveKey(type);
+  const config = key ? agents.get(key) : undefined;
+  if (config && config.enabled !== false) {
+    return {
+      displayName: config.displayName ?? config.name,
+      color: config.color,
+      description: config.description,
+      builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+      extensions: config.extensions,
+      excludeExtensions: config.excludeExtensions,
+      skills: config.skills,
+      promptMode: config.promptMode,
+    };
+  }
+
+  // Fallback for unknown/disabled types — general-purpose config
+  const gp = agents.get("general-purpose");
+  if (gp && gp.enabled !== false) {
+    return {
+      displayName: gp.displayName ?? gp.name,
+      color: gp.color,
+      description: gp.description,
+      builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+      extensions: gp.extensions,
+      excludeExtensions: gp.excludeExtensions,
+      skills: gp.skills,
+      promptMode: gp.promptMode,
+    };
+  }
+
+  // Absolute fallback (should never happen)
+  return {
+    displayName: "Agent",
+    description: "General-purpose agent for complex, multi-step tasks",
+    builtinToolNames: BUILTIN_TOOL_NAMES,
+    extensions: true,
+    skills: true,
+    promptMode: "append",
+  };
+}
+

package/src/child-context.ts

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Marks resource loading/session construction performed for a subagent. This is
+ * async-context-local so concurrent top-level extension work is unaffected.
+ */
+const childSessionContext = new AsyncLocalStorage<boolean>();
+
+export function inChildSessionContext(): boolean {
+  return childSessionContext.getStore() === true;
+}
+
+export function runInChildSessionContext<T>(fn: () => Promise<T>): Promise<T> {
+  return childSessionContext.run(true, fn);
+}

package/src/clock.ts

@@ -0,0 +1,25 @@
+/** A timer owns cancellation, without requiring a Node-specific handle. */
+export interface TimerHandle {
+  cancel(): void;
+  unref?(): void;
+}
+
+/** Scheduling boundary, structurally compatible with pi-session-kit's clock. */
+export interface Clock {
+  now(): number;
+  setTimeout(callback: () => void, ms: number): TimerHandle;
+  setInterval(callback: () => void, ms: number): TimerHandle;
+}
+
+/** Native timers keep their original reference/unref behavior; cancellation uses the native clear functions. */
+export const realClock: Clock = {
+  now: () => Date.now(),
+  setTimeout(callback, ms) {
+    const timer = setTimeout(callback, ms);
+    return { cancel: () => clearTimeout(timer) };
+  },
+  setInterval(callback, ms) {
+    const timer = setInterval(callback, ms);
+    return { cancel: () => clearInterval(timer), unref: () => { timer.unref(); } };
+  },
+};

package/src/completion-outbox.ts

@@ -0,0 +1,125 @@
+/**
+ * completion-outbox.ts — When background completions reach the parent.
+ *
+ * Claude Code queues each completion and, after every tool batch, hands the
+ * model everything that queued up in one go: a busy parent sees what finished
+ * during the batch before its next model call, and nothing waits for a sibling.
+ * pi's steering queue would split those into one model call each under its
+ * default `one-at-a-time` mode, so the outbox holds them and sends ONE message
+ * at the boundary instead.
+ *
+ * - Parent busy: held until `turn_end`, which pi emits after the tool batch and
+ *   before it reads the steering queue.
+ * - Parent idle: sent after a short hold, so near-simultaneous completions
+ *   share a turn and `get_subagent_result` still gets a moment to consume one.
+ * - Parent turn aborted (Esc) or failed: held through it — pi clears its own
+ *   queues on Esc — and sent once the run has ended, starting a turn. Claude
+ *   Code keeps an agent's completion queued through Esc the same way and runs
+ *   it as soon as the interrupted turn stops.
+ */
+
+import { type Clock, realClock, type TimerHandle } from "./clock.js";
+import type { NotificationDetails } from "./types.js";
+
+/** How long an idle parent's notification is held before it is sent. */
+export const NOTIFICATION_HOLD_MS = 200;
+
+export interface OutboxMessage {
+  content: string;
+  details: NotificationDetails;
+}
+
+/**
+ * A notification for one or more agents, built when they finished: a resume
+ * before the send must not rewrite it. Reading an agent's result cancels its
+ * id, and an item left with none is dropped; `build` gets the ids still pending.
+ */
+export interface OutboxItem {
+  ids: string[];
+  build(ids: readonly string[]): OutboxMessage;
+}
+
+export class CompletionOutbox {
+  private items: OutboxItem[] = [];
+  private timer: TimerHandle | undefined;
+
+  constructor(
+    /** Delivers one message as a steer that triggers a turn when the parent is idle. */
+    private send: (message: OutboxMessage) => void,
+    /** Whether the parent has a run in flight, so a `turn_end` is coming. */
+    private parentRunning: () => boolean,
+    /** Shared with the scheduler by hosts that control time in-process. */
+    private clock: Clock = realClock,
+  ) {}
+
+  /** A newer completion of the same agent (a resume) replaces its pending one. */
+  add(item: OutboxItem): void {
+    for (const id of item.ids) this.cancel(id);
+    this.items.push(item);
+    if (!this.parentRunning()) this.arm();
+  }
+
+  /** The parent finished a turn: its tool batch is done, the next model call is not. */
+  onTurnEnd(stopReason: string | undefined): void {
+    // An aborted turn ends its run; a failed one may be retried. Either way
+    // what is held waits for the next boundary or the run's end — sent now,
+    // it would sit in a queue pi is about to clear.
+    if (stopReason !== "aborted" && stopReason !== "error") this.flush();
+  }
+
+  /** The agent's result was read: it must not also be notified. */
+  cancel(id: string): void {
+    for (const item of this.items) item.ids = item.ids.filter(i => i !== id);
+    this.items = this.items.filter(item => item.ids.length > 0);
+  }
+
+  /**
+   * Completions that landed after the run's last `turn_end` would otherwise wait for the next run.
+   * Called at `agent_end` and again at `agent_settled`: one can land while the ending run is still open.
+   */
+  onAgentEnd(): void {
+    if (this.items.length > 0) this.arm();
+  }
+
+  dispose(): void {
+    this.timer?.cancel();
+    this.timer = undefined;
+    this.items = [];
+  }
+
+  /** Not reset by later items: the first completion is never pushed back. */
+  private arm(): void {
+    this.timer ??= this.clock.setTimeout(() => {
+      this.timer = undefined;
+      this.flush();
+    }, NOTIFICATION_HOLD_MS);
+  }
+
+  /** Remove held completions for transfer to their session's detached spool. */
+  takePending(): OutboxMessage | undefined {
+    this.timer?.cancel();
+    this.timer = undefined;
+    const items = this.items;
+    this.items = [];
+    const messages = items.map(item => item.build(item.ids));
+    return messages.length > 0 ? combine(messages) : undefined;
+  }
+
+  private flush(): void {
+    const message = this.takePending();
+    if (!message) return;
+    // A send from a timer can outlive the session it was meant for (pi -p
+    // tearing down): pi throws on the stale context, and nothing is left to tell.
+    try { this.send(message); } catch { /* stale context */ }
+  }
+}
+
+/** One message stays as it was built; several become one message with every agent's details. */
+function combine(messages: OutboxMessage[]): OutboxMessage {
+  if (messages.length === 1) return messages[0];
+  const [first, ...rest] = messages.flatMap(({ details: { others, ...own } }) => [own, ...(others ?? [])]);
+  return {
+    content: `${messages.length} background tasks finished.\n\n${messages.map(m => m.content).join("\n\n")}`,
+    details: { ...first, others: rest },
+  };
+}

package/src/context.ts

@@ -0,0 +1,58 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+  return content
+    .filter((c: any) => c.type === "text")
+    .map((c: any) => c.text ?? "")
+    .join("\n");
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: ExtensionContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  if (!entries || entries.length === 0) return "";
+
+  const parts: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.type === "message") {
+      const msg = entry.message;
+      if (msg.role === "user") {
+        const text = typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+        if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+      } else if (msg.role === "assistant") {
+        const text = extractText(msg.content);
+        if (text.trim()) parts.push(`[Assistant]: ${text.trim()}`);
+      }
+      // Skip toolResult messages — too verbose for context
+    } else if (entry.type === "compaction") {
+      // Include compaction summaries — they're already condensed
+      if (entry.summary) {
+        parts.push(`[Summary]: ${entry.summary}`);
+      }
+    }
+  }
+
+  if (parts.length === 0) return "";
+
+  return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}