@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/tools/helpers.ts

@@ -0,0 +1,134 @@
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent-state";
+import { getLifetimeTotal, type LifetimeUsage } from "#src/lifecycle/usage";
+import { type AgentDetails, formatTokens } from "#src/ui/display";
+
+/** Parenthetical outcome note for completed agent result text. */
+export function getOutcomeNote(
+  outcome: SubagentOutcome | undefined,
+  stoppedWhileQueued = false,
+): string {
+  if (stoppedWhileQueued && (outcome === "cancelled" || outcome === "queue_timeout")) {
+    return " (stopped before starting)";
+  }
+  switch (outcome) {
+    case "turn_limit":
+      return " (Turn limit reached)";
+    case "timeout":
+      return " (Timed out)";
+    case "queue_timeout":
+      return " (Queue timed out)";
+    case "cancelled":
+      return " (Cancelled)";
+    default:
+      return "";
+  }
+}
+
+/** Build AgentDetails from a base + record-specific fields. */
+export function buildDetails(
+  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
+  record: {
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    phase: SubagentPhase;
+    outcome?: SubagentOutcome;
+    error?: string;
+    id?: string;
+    lifetimeUsage: LifetimeUsage;
+    /** Live-activity counters — exposed as getters on Subagent (Phase 18 Step 2). */
+    invocationTurnCount?: number;
+    lifetimeTurnCount?: number;
+    maxTurns?: number;
+  },
+  overrides?: Partial<AgentDetails>,
+): AgentDetails {
+  return {
+    ...base,
+    toolUses: record.toolUses,
+    tokens: formatLifetimeTokens(record),
+    invocationTurnCount: record.invocationTurnCount,
+    lifetimeTurnCount: record.lifetimeTurnCount,
+    maxTurns: record.maxTurns,
+    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+    phase: record.phase,
+    ...(record.outcome ? { outcome: record.outcome } : {}),
+    agentId: record.id,
+    error: record.error,
+    ...overrides,
+  };
+}
+
+/** Tool execute return value for a text response. */
+export function textResult(msg: string, details?: AgentDetails) {
+  return { content: [{ type: "text" as const, text: msg }], details };
+}
+
+/** Format an agent's lifetime token total, or "" when zero. */
+export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
+  const t = getLifetimeTotal(o.lifetimeUsage);
+  return t > 0 ? formatTokens(t) : "";
+}
+
+/**
+ * Narrow registry interface needed by buildTypeListText.
+ * Extends AgentConfigLookup with the two name-listing methods.
+ */
+export interface TypeListRegistry extends AgentConfigLookup {
+  getDefaultAgentNames(): string[];
+  getUserAgentNames(): string[];
+}
+
+/**
+ * Build the full agent-type list text for the Agent tool description.
+ * Extracted from index.ts so it can be called inside createAgentTool.
+ */
+export function buildTypeListText(registry: TypeListRegistry, agentDir: string): string {
+  const defaultNames = registry.getDefaultAgentNames().filter((name) => isEnabledAgent(registry, name));
+  const userNames = registry.getUserAgentNames().filter((name) => isEnabledAgent(registry, name));
+
+  const defaultDescs = defaultNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+    return `- ${name}: ${cfg.description}${modelSuffix}`;
+  });
+
+  const customDescs = userNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    return `- ${name}: ${cfg.description}`;
+  });
+
+  return [
+    ...(defaultDescs.length > 0 ? ["Default agents:", ...defaultDescs] : []),
+    ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+    "",
+    `Custom agents can be defined in .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
+  ].join("\n");
+}
+
+/** True when an agent config is present and not explicitly disabled. */
+function isEnabledAgent(registry: AgentConfigLookup, name: string): boolean {
+  return registry.resolveAgentConfig(name).enabled !== false;
+}
+
+/**
+ * Collect the per-agent usage guidelines for the subagent tool's Guidelines: block.
+ * Sourced from each enabled default agent's `toolGuideline`, in registry order,
+ * so a disabled built-in drops its guideline automatically.
+ */
+export function buildAgentGuidelines(registry: TypeListRegistry): string[] {
+  return registry
+    .getDefaultAgentNames()
+    .filter((name) => isEnabledAgent(registry, name))
+    .map((name) => registry.resolveAgentConfig(name).toolGuideline)
+    .filter((line): line is string => line !== undefined);
+}
+
+/** Derive a short model label from a model string. */
+export function getModelLabelFromConfig(model: string): string {
+  // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
+  const name = model.includes("/") ? model.split("/").pop()! : model;
+  // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
+  return name.replace(/-\d{8}$/, "");
+}

package/src/tools/result-renderer.ts

@@ -0,0 +1,121 @@
+/**
+ * result-renderer.ts — Pure per-phase/outcome rendering functions for Agent tool results.
+ *
+ * All functions are stateless: they receive AgentDetails and a Theme, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by the renderResult hook in agent-tool.ts.
+ */
+
+import type { AgentDetails, Theme } from "#src/ui/display";
+import { formatMs, formatTurns, getOutcomeLabel } from "#src/ui/display";
+import { GLYPHS, SPINNER } from "#src/ui/glyphs";
+
+// ---- Dispatcher ----
+
+/** Dispatch on details.phase/outcome; isPartial forces the running view. */
+export function renderAgentResult(
+	details: AgentDetails,
+	resultText: string,
+	expanded: boolean,
+	isPartial: boolean,
+	theme: Theme,
+): string {
+	if (isPartial || details.phase === "running" || details.phase === "queued") {
+		return renderRunning(details, theme);
+	}
+	if (details.phase === "background") return renderBackground(details, theme);
+	if (details.phase === "terminal" && details.outcome === "completed") {
+		return renderCompleted(details, resultText, expanded, theme);
+	}
+	return renderFailed(details, theme);
+}
+
+// ---- Per-phase renderers ----
+
+/** Render running/queued/partial status: spinner + stats + activity line. */
+export function renderRunning(details: AgentDetails, theme: Theme): string {
+	const frame = SPINNER[details.spinnerFrame ?? 0];
+	const s = renderStats(details, theme);
+	let line = theme.fg("accent", frame) + (s ? " " + s : "");
+	line += "\n" + theme.fg("dim", `  ${GLYPHS.subLine}  ${details.activity ?? "thinking\u2026"}`);
+	return line;
+}
+
+/** Render background launch status. */
+export function renderBackground(details: AgentDetails, theme: Theme): string {
+	return theme.fg("dim", `  ${GLYPHS.subLine}  Running in background (ID: ${details.agentId})`);
+}
+
+/** Render the completed outcome with optional expanded result text. */
+export function renderCompleted(
+	details: AgentDetails,
+	resultText: string,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const duration = formatMs(details.durationMs);
+	const s = renderStats(details, theme);
+	let line = theme.fg("success", GLYPHS.success) + (s ? " " + s : "");
+	line += " " + theme.fg("dim", "\u00B7") + " " + theme.fg("dim", duration);
+
+	if (expanded) {
+		if (resultText) {
+			const lines = resultText.split("\n").slice(0, 50);
+			for (const l of lines) {
+				line += "\n" + theme.fg("dim", `  ${l}`);
+			}
+			if (resultText.split("\n").length > 50) {
+				line +=
+					"\n" +
+					theme.fg(
+						"muted",
+						"  ... (use get_subagent_result with verbose for full output)",
+					);
+			}
+		}
+	} else {
+		line += "\n" + theme.fg("dim", `  ${GLYPHS.subLine}  Done`);
+	}
+	return line;
+}
+
+/**
+ * Render every non-completed terminal outcome with failure styling.
+ * `error` carries the failure message; the other outcomes show their frozen label.
+ */
+export function renderFailed(details: AgentDetails, theme: Theme): string {
+	const s = renderStats(details, theme);
+	let line = theme.fg("error", GLYPHS.failure) + (s ? " " + s : "");
+
+	if (details.outcome === "error") {
+		line +=
+			"\n" +
+			theme.fg("error", `  ${GLYPHS.subLine}  Error: ${details.error ?? "unknown"}`);
+	} else {
+		line +=
+			"\n" +
+			theme.fg("warning", `  ${GLYPHS.subLine}  ${getOutcomeLabel(details.outcome)}`);
+	}
+	return line;
+}
+
+// ---- Shared helper ----
+
+/**
+ * Build the stats string: "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k token".
+ * Returns an empty string when all fields are absent or zero.
+ */
+export function renderStats(details: AgentDetails, theme: Theme): string {
+	const parts: string[] = [];
+	if (details.modelName) parts.push(details.modelName);
+	if (details.tags) parts.push(...details.tags);
+	if (details.invocationTurnCount != null && details.invocationTurnCount > 0) {
+		parts.push(formatTurns(details.invocationTurnCount, details.maxTurns));
+	}
+	if (details.toolUses > 0)
+		parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+	if (details.tokens) parts.push(details.tokens);
+	return parts
+		.map((p) => theme.fg("dim", p))
+		.join(" " + theme.fg("dim", "\u00B7") + " ");
+}

package/src/tools/spawn-config.ts

@@ -0,0 +1,182 @@
+/**
+ * spawn-config.ts — Pure config resolution for the Agent tool.
+ *
+ * Extracts all config resolution logic from execute: type resolution,
+ * invocation config merge, model resolution, runtime budget merging,
+ * tag building, and detail-base construction.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentTypeRegistry } from "#src/config/agent-types";
+import { resolveAgentInvocationConfig } from "#src/config/invocation-config";
+import { clampWrapUpTurns, minPositive } from "#src/config/resource-limits";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import { resolveInvocationModel } from "#src/session/model-resolver";
+import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
+import {
+  type AgentDetails,
+  buildInvocationTags,
+  getDisplayName,
+  getPromptModeLabel,
+} from "#src/ui/display";
+
+/** Model info extracted from the parent session context. */
+export interface ModelInfo {
+  parentModel: Model<any> | undefined;
+  modelRegistry: ModelRegistry | undefined;
+}
+
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
+  subagentType: string;
+  rawType: SubagentType;
+  fellBack: boolean;
+  displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
+  prompt: string;
+  description: string;
+  model: Model<any> | undefined;
+  /** Effective hard turn budget: minimum over global, profile, and tool call. */
+  effectiveMaxTurns: number;
+  /** Effective wrap-up window in turns, below effectiveMaxTurns. */
+  effectiveWrapUpTurns: number;
+  /** Effective run-duration budget in seconds: minimum over global, profile, and tool call. */
+  effectiveMaxDurationSeconds: number;
+  thinking: ThinkingLevel | undefined;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity and execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
+  agentTags: string[];
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Fully resolved config for spawning an agent — composed of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+
+/** Error result when model resolution fails. */
+export interface SpawnConfigError {
+  error: string;
+}
+
+/** Runtime budgets read from the global settings layer. */
+export interface SpawnSettings {
+  readonly maxTurns: number;
+  readonly wrapUpTurns: number;
+  readonly maxDurationSeconds: number;
+}
+
+/**
+ * Resolve all config for an Agent tool invocation.
+ *
+ * Pure function — no SDK types, no side effects.
+ * Returns either a fully resolved config or an error.
+ */
+export function resolveSpawnConfig(
+  params: Record<string, unknown>,
+  registry: AgentTypeRegistry,
+  modelInfo: ModelInfo,
+  settings: SpawnSettings,
+): ResolvedSpawnConfig | SpawnConfigError {
+  const rawType = params.subagent_type as SubagentType;
+  const resolved = registry.resolveType(rawType);
+
+  let subagentType: string;
+  try {
+    subagentType = registry.resolveSpawnType(rawType);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  const fellBack = resolved === undefined;
+
+  const displayName = getDisplayName(subagentType, registry);
+
+  // Merge agent config defaults with tool-call params
+  const customConfig = registry.resolveAgentConfig(subagentType);
+  const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
+
+  // Resolve model
+  const resolution = resolveInvocationModel(
+    modelInfo.parentModel,
+    resolvedConfig.modelInput,
+    resolvedConfig.modelFromParams,
+    modelInfo.modelRegistry,
+  );
+  if (resolution.error) return { error: resolution.error };
+  const model = resolution.model;
+
+  const thinking = resolvedConfig.thinking;
+  const inheritContext = resolvedConfig.inheritContext;
+  const runInBackground = resolvedConfig.runInBackground;
+
+  // Compute display model name (only shown when different from parent)
+  const parentModelId = modelInfo.parentModel?.id;
+  const effectiveModelId = model?.id;
+  const modelName =
+    effectiveModelId && effectiveModelId !== parentModelId
+      ? model.name.replace(/^Claude\s+/i, "").toLowerCase()
+      : undefined;
+
+  // Budgets: global values always exist; profile and tool-call values may only
+  // tighten them, so the effective value is the minimum of every defined layer.
+  const effectiveMaxTurns = minPositive(settings.maxTurns, resolvedConfig.maxTurns) ?? settings.maxTurns;
+  const effectiveMaxDurationSeconds =
+    minPositive(settings.maxDurationSeconds, resolvedConfig.maxDurationSeconds) ??
+    settings.maxDurationSeconds;
+  // Wrap-up precedence is invocation > profile > global, then clamped below the
+  // effective hard stop so the soft limit always fires before the hard stop.
+  const effectiveWrapUpTurns = clampWrapUpTurns(
+    resolvedConfig.wrapUpTurns ?? settings.wrapUpTurns,
+    effectiveMaxTurns,
+  );
+
+  const agentInvocation: AgentInvocation = {
+    modelName,
+    thinking,
+    maxTurns: resolvedConfig.maxTurns,
+    wrapUpTurns: resolvedConfig.wrapUpTurns,
+    maxDurationSeconds: resolvedConfig.maxDurationSeconds,
+    inheritContext,
+    runInBackground,
+  };
+
+  const modeLabel = getPromptModeLabel(subagentType, registry);
+  const { tags: invocationTags } = buildInvocationTags(agentInvocation);
+  const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
+
+  const detailBase = {
+    displayName,
+    description: params.description as string,
+    subagentType,
+    modelName,
+    tags: agentTags.length > 0 ? agentTags : undefined,
+  };
+
+  return {
+    identity: { subagentType, rawType, fellBack, displayName },
+    execution: {
+      prompt: params.prompt as string,
+      description: params.description as string,
+      model,
+      effectiveMaxTurns,
+      effectiveWrapUpTurns,
+      effectiveMaxDurationSeconds,
+      thinking,
+      inheritContext,
+      runInBackground,
+      agentInvocation,
+    },
+    presentation: { modelName, agentTags, detailBase },
+  };
+}

package/src/tools/steer-tool.ts

@@ -0,0 +1,120 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { buildSteerLifecycleEvent } from "#src/lifecycle/lifecycle-record";
+import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import type { SteerOutcome, Subagent } from "#src/types";
+
+// ---- Deps interfaces ----
+
+export interface SteerToolManager {
+	getRecord(id: string): Subagent | undefined;
+}
+
+export interface SteerToolEvents {
+	emit(name: string, data: unknown): void;
+}
+
+// ---- Class ----
+
+export class SteerTool {
+	constructor(
+		private readonly manager: SteerToolManager,
+		private readonly events: SteerToolEvents,
+	) {}
+
+	async execute(
+		_toolCallId: string,
+		params: { agent_id: string; message: string },
+		_signal: AbortSignal,
+		_onUpdate: unknown,
+		_ctx: unknown,
+	) {
+		const record = this.manager.getRecord(params.agent_id);
+		if (!record) {
+			return textResult(
+				`Agent not found: "${params.agent_id}". Records are cleared at session start/switch, so it may be from a previous session.`,
+			);
+		}
+
+		let outcome: SteerOutcome;
+		try {
+			outcome = await record.steer(params.message);
+		} catch (err) {
+			return textResult(
+				`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+
+		switch (outcome.kind) {
+			case "rejected": {
+				const state = outcome.outcome
+					? `${outcome.phase}/${outcome.outcome}`
+					: outcome.phase;
+				return textResult(
+					`Agent "${params.agent_id}" is not running (state: ${state}). Cannot steer a non-running agent.`,
+				);
+			}
+			case "buffered":
+				this.events.emit(
+					"subagents:steered",
+					buildSteerLifecycleEvent(record, params.message),
+				);
+				return textResult(
+					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+				);
+			case "delivered":
+				this.events.emit(
+					"subagents:steered",
+					buildSteerLifecycleEvent(record, params.message),
+				);
+				return this.renderDelivered(record);
+		}
+	}
+
+	/** Render the success message with live state for a delivered steer. */
+	private renderDelivered(record: Subagent) {
+		const tokens = formatLifetimeTokens(record);
+		const contextPercent = record.getContextPercent();
+		const stateParts: string[] = [];
+		if (tokens) stateParts.push(tokens);
+		stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+		if (contextPercent !== null)
+			stateParts.push(`context ${Math.round(contextPercent)}% full`);
+		if (record.compactionCount)
+			stateParts.push(
+				`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`,
+			);
+		return textResult(
+			`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+				`Current state: ${stateParts.join(" · ")}`,
+		);
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: "steer_subagent" as const,
+			label: "Steer Agent",
+			promptSnippet:
+				"Send a mid-run message to redirect a running background agent.",
+			description:
+				"Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
+				"and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+			parameters: Type.Object({
+				agent_id: Type.String({
+					description: "The agent ID to steer (must be currently running).",
+				}),
+				message: Type.String({
+					description:
+						"The steering message to send. This will appear as a user message in the agent's conversation.",
+				}),
+			}),
+			execute: (
+				toolCallId: string,
+				params: { agent_id: string; message: string },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}

package/src/types.ts

@@ -0,0 +1,145 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+import type { Model, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { AgentSessionEvent, SessionContext as SdkSessionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry } from "#src/session/model-resolver";
+
+
+export type { SteerOutcome } from "#src/lifecycle/subagent";
+export { Subagent } from "#src/lifecycle/subagent";
+export type { AgentSessionEvent, ThinkingLevel };
+
+/**
+ * One message in a child session's history, typed from Pi's `SessionContext`.
+ *
+ * Derived from the barrel-exported `SessionContext` (whose `messages` field is
+ * `AgentMessage[]`) so the package needs no direct dependency on
+ * `@earendil-works/pi-agent-core`, which is not re-exported from the public barrel.
+ */
+export type SessionMessage = SdkSessionContext["messages"][number];
+
+/**
+ * Narrow session interface for event subscription.
+ * Used by record-observer — only the subscribe method is needed.
+ */
+export interface SubscribableSession {
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void;
+}
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+export type SubagentType = string;
+
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
+  name: string;
+  displayName?: string;
+  description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
+  /** The agent's tool allowlist. Entries name built-in or extension-registered tools; omitted means every built-in. */
+  toolNames?: string[];
+  model?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  wrapUpTurns?: number;
+  maxDurationSeconds?: number;
+  /** Default for spawn: fork parent conversation. undefined = caller decides. */
+  inheritContext?: boolean;
+  /** Default for spawn: run in background. undefined = caller decides. */
+  runInBackground?: boolean;
+  /** One-line usage guideline for the subagent tool's Guidelines: block. Omitted — no guideline line. */
+  toolGuideline?: string;
+  /** true = this is an embedded default agent (informational) */
+  isDefault?: boolean;
+  /** Effective runtime state; populated by AgentTypeRegistry, never by frontmatter. */
+  enabled?: boolean;
+  /** Where this agent was loaded from */
+  source?: "default" | "project" | "global";
+  /** Definition path for operator inspection; absent for embedded defaults. */
+  filePath?: string;
+}
+
+export interface AgentInvocation {
+  /** Short display name, e.g. "haiku" — only set when different from parent. */
+  modelName?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  wrapUpTurns?: number;
+  maxDurationSeconds?: number;
+  inheritContext?: boolean;
+  runInBackground?: boolean;
+}
+
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+/**
+ * Narrow interface capturing the ExtensionContext fields SubagentRuntime needs.
+ * Avoids coupling runtime to the full SDK ExtensionContext surface (ISP).
+ */
+export interface SessionContext {
+  readonly cwd: string;
+  readonly model: Model<any> | undefined;
+  readonly modelRegistry: ModelRegistry;
+  getSystemPrompt(): string;
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+    getBranch(): unknown[];
+  };
+}
+
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+export type ShellExec = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+/** Identifies the parent invocation currently driving a subagent turn. */
+export type SubagentInvocationIdentity =
+	| {
+			kind: "fresh" | "resume";
+			source: "tool";
+			toolCallId: string;
+	  }
+	| {
+			kind: "fresh" | "resume";
+			source: "service";
+			toolCallId?: never;
+	  };
+
+/** Stable identity assigned after the child Pi session is created. */
+export interface SubagentSessionIdentity {
+	sessionId: string;
+	outputFile?: string;
+}
+
+/** Parent session identity — grouped fields that travel together from the tool boundary. */
+export interface ParentSessionInfo {
+	/** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+	parentSessionFile?: string;
+	/** Session ID of the parent agent (stored in the child session's parentSession header). */
+	parentSessionId?: string;
+	/** Parent tool call ID for the fresh invocation; lifecycle v2 requires it for tool-driven runs. */
+	toolCallId?: string;
+}
+
+/** Compaction event info passed through lifecycle observers. */
+export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };