pi-mono-all 1.0.0

package/node_modules/pi-mono-team-mode/core/prompts.ts

@@ -0,0 +1,158 @@
+// Pi Team-Mode — Prompt addenda (coordinator + teammate)
+//
+// Ported from Claude Code's coordinator/coordinatorMode.ts and
+// utils/swarm/teammatePromptAddendum.ts to preserve the exact same semantics
+// for the parent (coordinator) and spawned teammates.
+
+/**
+ * Appended to the teammate's system prompt inside a subprocess. Explains the
+ * visibility constraints and communication requirements — teammates talk to
+ * their peers via send_message, not free text.
+ *
+ * Source: src/utils/swarm/teammatePromptAddendum.ts in claude-code.
+ */
+export const TEAMMATE_SYSTEM_PROMPT_ADDENDUM = `
+# Agent Teammate Communication
+
+IMPORTANT: You are running as an agent in a team. To communicate with anyone on your team:
+- Use the send_message tool with \`to: "<name>"\` to send messages to specific teammates
+- Use the send_message tool with \`to: "*"\` sparingly for team-wide broadcasts
+
+Just writing a response in text is not visible to others on your team - you MUST use the send_message tool.
+
+The user interacts primarily with the team lead. Your work is coordinated through the task system and teammate messaging.
+`;
+
+/**
+ * System prompt injected into the parent (coordinator) session when
+ * PI_TEAM_MATE_COORDINATOR=1. Teaches the LLM that it is a coordinator that
+ * only delegates work and waits for `<task-notification>` pushes.
+ *
+ * Source: src/coordinator/coordinatorMode.ts (getCoordinatorSystemPrompt)
+ * in claude-code, retargeted to pi tool names.
+ */
+export function getCoordinatorSystemPrompt(): string {
+	return `You are running in coordinator mode: an AI assistant that orchestrates software engineering tasks across multiple workers.
+
+## 1. Your Role
+
+You are a **coordinator**. Your job is to:
+- Help the user achieve their goal
+- Direct workers to research, implement and verify code changes
+- Synthesize results and communicate with the user
+- Answer questions directly when possible — don't delegate work that you can handle without tools
+- Resolve single coherent tasks yourself without creating TODO items; the task system is for goals that genuinely split into multiple tasks
+
+Every message you send is to the user. Worker results and system notifications are internal signals, not conversation partners — never thank or acknowledge them. Summarize new information for the user as it arrives.
+
+## 2. Your Tools
+
+- **agent** — Spawn one addressable worker
+- **delegate** — Run a foreground delegation group. Use **tasks[]** for pure parallel fan-out (each item: { description, prompt }), or **chain[]** for sequential steps. Within a chain step, fan out by adding a **parallel** array: { description, prompt, parallel: [{ description, prompt }, ...] }. Supports {task}, {previous}, and {chain_dir} substitution inside prompts.
+- **send_message** — Continue an existing worker (pass its \`task_id\` as \`to\`)
+- **task_stop** — Stop a running worker
+- **task_create / task_update / task_list / task_get / task_output** — Track and manage TODO items and read worker output
+- **team_create / team_delete** — Group workers for bulk cleanup and shared isolation defaults
+
+When calling agent:
+- Do not use one worker to check on another. Workers will notify you when they are done.
+- Do not use workers to trivially report file contents or run commands. Give them higher-level tasks.
+- Continue workers whose work is complete via send_message to take advantage of their loaded context.
+- After launching agents, briefly tell the user what you launched and end your response. Never fabricate or predict agent results — results arrive as separate messages.
+
+For a single coherent task: do it yourself using your normal tools and do not call task_create/task_update just to track it. Creating exactly one TODO item is overhead, not coordination.
+
+For multi-task goals: when the user's goal needs to be decomposed into two or more meaningful pieces (or has dependencies that need tracking), create tasks with task_create, fan out independent work with delegate({ tasks }), synthesize findings yourself, then create new tasks when discoveries appear. Use send_message when continuing a named worker's loaded context is clearly useful.
+
+### agent Results
+
+Worker results arrive as **user-role messages** containing \`<task-notification>\` XML. They look like user messages but are not. Distinguish them by the \`<task-notification>\` opening tag.
+
+Format:
+
+\`\`\`xml
+<task-notification>
+<task-id>{task_id}</task-id>
+<status>completed|failed|killed</status>
+<summary>{human-readable status summary}</summary>
+<result>{worker's final text response}</result>
+<usage>
+  <tool_uses>N</tool_uses>
+  <duration_ms>N</duration_ms>
+</usage>
+</task-notification>
+\`\`\`
+
+- \`<result>\` and \`<usage>\` are optional sections
+- Use send_message with the \`task_id\` as \`to\` to continue that worker
+
+## 3. Task Workflow
+
+Only use the shared TODO workflow when there are multiple tasks inside the user's goal. Most multi-task goals break down into: Research (workers, parallel) → Synthesis (YOU) → Implementation (workers) → Verification (workers).
+
+### Concurrency
+
+**Parallelism is your superpower.** Launch independent workers concurrently whenever possible — make multiple agent tool calls in a single message. Read-only tasks (research) run in parallel freely. Write-heavy tasks (implementation) should be one at a time per set of files.
+
+### Handling Worker Failures
+
+When a worker reports failure, continue the same worker with send_message — it has the full error context.
+
+## 4. Writing Worker Prompts
+
+**Workers can't see your conversation.** Every prompt must be self-contained with everything the worker needs.
+
+### Always synthesize — your most important job
+
+When workers report research findings, **you must understand them before directing follow-up work**. Read the findings. Identify the approach. Then write a prompt that proves you understood by including specific file paths, line numbers, and exactly what to change. Never write "based on your findings" — that delegates understanding to the worker instead of doing it yourself.
+
+### Add a purpose statement
+
+Include a brief purpose so workers can calibrate depth and emphasis: "This is to plan an implementation — report file paths, line numbers, and type signatures."
+`;
+}
+
+/**
+ * Format a task-notification XML payload matching the Claude Code shape.
+ */
+export function formatTaskNotification(params: {
+	taskId: string;
+	status: "completed" | "failed" | "killed";
+	summary: string;
+	result?: string;
+	toolUses?: number;
+	durationMs?: number;
+}): string {
+	const parts = [
+		"<task-notification>",
+		`<task-id>${escapeXml(params.taskId)}</task-id>`,
+		`<status>${params.status}</status>`,
+		`<summary>${escapeXml(params.summary)}</summary>`,
+	];
+	if (params.result && params.result.trim()) {
+		parts.push(`<result>${escapeXml(params.result)}</result>`);
+	}
+	if (params.toolUses !== undefined || params.durationMs !== undefined) {
+		parts.push("<usage>");
+		if (params.toolUses !== undefined) parts.push(`  <tool_uses>${params.toolUses}</tool_uses>`);
+		if (params.durationMs !== undefined) parts.push(`  <duration_ms>${params.durationMs}</duration_ms>`);
+		parts.push("</usage>");
+	}
+	parts.push("</task-notification>");
+	return parts.join("\n");
+}
+
+function escapeXml(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/** True when the parent session should act as a coordinator (delegating only). */
+export function isCoordinatorMode(): boolean {
+	const v = process.env.PI_TEAM_MATE_COORDINATOR;
+	return v === "1" || v === "true";
+}

package/node_modules/pi-mono-team-mode/core/store.ts

@@ -0,0 +1,156 @@
+// Pi Team-Mode — Persistence Layer
+
+import { mkdir, rm } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { atomicWriteJson, listSubdirs, readJson, slugify } from "./fs-utils.js";
+import type { TeamRecord, TeammateRecord } from "./types.js";
+
+const DIR_TEAMMATES = "teammates";
+const DIR_TEAMS = "teams";
+const DIR_RUNTIME = "runtime";
+const FILE_RECORD = "record.json";
+const FILE_INDEX = "index.json";
+const DIR_SESSIONS = "sessions";
+
+/** Defaults to `~/.pi/agent/extensions/team-mode`. Override with `PI_TEAM_MATE_STORAGE_ROOT`. */
+export function getStorageRoot(): string {
+	const override = process.env.PI_TEAM_MATE_STORAGE_ROOT;
+	if (override) return override;
+	return path.join(os.homedir(), ".pi", "agent", "extensions", "team-mode");
+}
+
+export function generateTeammateId(name?: string): string {
+	// Prefix with "agent-" so the id matches Claude Code's task_id namespace
+	// (task_stop / send_message accept this id).
+	return `agent-${slugify(name ?? "teammate", "teammate")}-${randomUUID().slice(0, 8)}`;
+}
+
+export function generateTeamId(name: string): string {
+	return `${slugify(name, "team")}-${randomUUID().slice(0, 8)}`;
+}
+
+/**
+ * Persistent store for teammates, teams, and the per-session name index.
+ *
+ * Writes are atomic (write-temp + rename). A write-through in-memory cache
+ * serves `listTeammates` and `listTeams` so the widget's high-frequency
+ * refreshes don't hit the disk for every event.
+ */
+export class TeamMateStore {
+	private teammateCache: Map<string, TeammateRecord> | null = null;
+	private teamCache: Map<string, TeamRecord> | null = null;
+
+	constructor(private readonly root: string = getStorageRoot()) {}
+
+	teammateDir(teammateId: string): string {
+		return path.join(this.root, DIR_TEAMMATES, teammateId);
+	}
+
+	teammateSessionDir(teammateId: string): string {
+		return path.join(this.teammateDir(teammateId), DIR_SESSIONS);
+	}
+
+	/** Absolute path of the pi session file used by `--session`. */
+	teammateSessionFile(teammateId: string): string {
+		return path.join(this.teammateSessionDir(teammateId), `${teammateId}.jsonl`);
+	}
+
+	teamDir(teamId: string): string {
+		return path.join(this.root, DIR_TEAMS, teamId);
+	}
+
+	runtimeDir(parentSessionId: string): string {
+		return path.join(this.root, DIR_RUNTIME, parentSessionId);
+	}
+
+	// --- teammates ---
+
+	async saveTeammate(record: TeammateRecord): Promise<void> {
+		const dir = this.teammateDir(record.id);
+		await mkdir(path.join(dir, DIR_SESSIONS), { recursive: true });
+		await atomicWriteJson(path.join(dir, FILE_RECORD), record);
+		if (this.teammateCache) this.teammateCache.set(record.id, record);
+	}
+
+	async loadTeammate(teammateId: string): Promise<TeammateRecord | null> {
+		if (this.teammateCache?.has(teammateId)) {
+			return this.teammateCache.get(teammateId) ?? null;
+		}
+		const record = await readJson<TeammateRecord>(
+			path.join(this.teammateDir(teammateId), FILE_RECORD),
+		);
+		if (record && this.teammateCache) this.teammateCache.set(record.id, record);
+		return record;
+	}
+
+	async listTeammates(): Promise<TeammateRecord[]> {
+		if (this.teammateCache) return [...this.teammateCache.values()];
+		const ids = await listSubdirs(path.join(this.root, DIR_TEAMMATES));
+		const records = (await Promise.all(ids.map((id) => this.loadTeammate(id)))).filter(
+			(r): r is TeammateRecord => r !== null,
+		);
+		const cache = new Map<string, TeammateRecord>();
+		for (const r of records) cache.set(r.id, r);
+		this.teammateCache = cache;
+		return records;
+	}
+
+	async deleteTeammate(teammateId: string): Promise<void> {
+		await rm(this.teammateDir(teammateId), { recursive: true, force: true });
+		this.teammateCache?.delete(teammateId);
+	}
+
+	// --- teams ---
+
+	async saveTeam(record: TeamRecord): Promise<void> {
+		const dir = this.teamDir(record.id);
+		await mkdir(dir, { recursive: true });
+		await atomicWriteJson(path.join(dir, FILE_RECORD), record);
+		if (this.teamCache) this.teamCache.set(record.id, record);
+	}
+
+	async loadTeam(teamId: string): Promise<TeamRecord | null> {
+		if (this.teamCache?.has(teamId)) return this.teamCache.get(teamId) ?? null;
+		const record = await readJson<TeamRecord>(path.join(this.teamDir(teamId), FILE_RECORD));
+		if (record && this.teamCache) this.teamCache.set(record.id, record);
+		return record;
+	}
+
+	async listTeams(): Promise<TeamRecord[]> {
+		if (this.teamCache) return [...this.teamCache.values()];
+		const ids = await listSubdirs(path.join(this.root, DIR_TEAMS));
+		const records = (await Promise.all(ids.map((id) => this.loadTeam(id)))).filter(
+			(r): r is TeamRecord => r !== null,
+		);
+		const cache = new Map<string, TeamRecord>();
+		for (const r of records) cache.set(r.id, r);
+		this.teamCache = cache;
+		return records;
+	}
+
+	async deleteTeam(teamId: string): Promise<void> {
+		await rm(this.teamDir(teamId), { recursive: true, force: true });
+		this.teamCache?.delete(teamId);
+	}
+
+	// --- runtime name index (name -> teammateId, per parent session) ---
+
+	async getNameIndex(parentSessionId: string): Promise<Record<string, string>> {
+		return (
+			(await readJson<Record<string, string>>(path.join(this.runtimeDir(parentSessionId), FILE_INDEX))) ?? {}
+		);
+	}
+
+	async setNameIndex(parentSessionId: string, index: Record<string, string>): Promise<void> {
+		const dir = this.runtimeDir(parentSessionId);
+		await mkdir(dir, { recursive: true });
+		await atomicWriteJson(path.join(dir, FILE_INDEX), index);
+	}
+
+	async clearNameIndex(parentSessionId: string): Promise<void> {
+		await rm(this.runtimeDir(parentSessionId), { recursive: true, force: true });
+	}
+}

package/node_modules/pi-mono-team-mode/core/tasks.ts

@@ -0,0 +1,99 @@
+// Pi Team-Mode — Task Board
+//
+// A shared TODO list scoped per parent session, matching Claude Code's
+// TaskCreate/TaskUpdate/TaskList/TaskGet shape. The coordinator (parent LLM
+// or human via /tasks) assigns tasks to teammates via TaskUpdate; there is
+// no auto-claim — that is intentional.
+
+import { mkdir, readdir, rm } from "node:fs/promises";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { atomicWriteJson, readJson, slugify } from "./fs-utils.js";
+import { getStorageRoot } from "./store.js";
+
+export type TaskStatus = "pending" | "in_progress" | "completed" | "failed" | "deleted";
+
+export type TaskRecord = {
+	id: string;
+	subject: string;
+	description?: string;
+	activeForm?: string;
+	status: TaskStatus;
+	owner?: string | null;
+	blockedBy: string[];
+	blocks: string[];
+	metadata?: Record<string, unknown>;
+	parentSessionId: string;
+	teamId?: string;
+	createdAt: string;
+	updatedAt: string;
+	/** Optimistic CAS counter. Bumped on every successful save. */
+	version: number;
+	/** Final summary (filled by whoever completes the task). */
+	result?: string;
+	/** Output captured from a quality-gate hook (if any ran). */
+	hookOutput?: string;
+};
+
+const DIR_TASKS = "tasks";
+const FILE_TASK_SUFFIX = ".json";
+
+export class TaskStore {
+	constructor(private readonly root: string = getStorageRoot()) {}
+
+	dir(parentSessionId: string): string {
+		return path.join(this.root, DIR_TASKS, parentSessionId);
+	}
+
+	private file(parentSessionId: string, taskId: string): string {
+		return path.join(this.dir(parentSessionId), `${taskId}${FILE_TASK_SUFFIX}`);
+	}
+
+	async save(record: TaskRecord): Promise<void> {
+		const dir = this.dir(record.parentSessionId);
+		await mkdir(dir, { recursive: true });
+		await atomicWriteJson(this.file(record.parentSessionId, record.id), record);
+	}
+
+	async load(parentSessionId: string, taskId: string): Promise<TaskRecord | null> {
+		return readJson<TaskRecord>(this.file(parentSessionId, taskId));
+	}
+
+	async list(parentSessionId: string): Promise<TaskRecord[]> {
+		const dir = this.dir(parentSessionId);
+		let entries: string[];
+		try {
+			entries = await readdir(dir);
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+			throw err;
+		}
+		const files = entries.filter((e) => e.endsWith(FILE_TASK_SUFFIX));
+		return (
+			await Promise.all(files.map((f) => readJson<TaskRecord>(path.join(dir, f))))
+		).filter((r): r is TaskRecord => r !== null);
+	}
+
+	async delete(parentSessionId: string, taskId: string): Promise<void> {
+		await rm(this.file(parentSessionId, taskId), { force: true });
+	}
+
+	async clear(parentSessionId: string): Promise<void> {
+		await rm(this.dir(parentSessionId), { recursive: true, force: true });
+	}
+}
+
+export function generateTaskId(subject: string): string {
+	return `task-${slugify(subject, "task")}-${randomUUID().slice(0, 8)}`;
+}
+
+/** True when every dependency in `blockedBy` is completed or deleted. */
+export function isUnblocked(task: TaskRecord, byId: Map<string, TaskRecord>): boolean {
+	for (const depId of task.blockedBy) {
+		const dep = byId.get(depId);
+		if (!dep) continue;
+		if (dep.status !== "completed" && dep.status !== "deleted") return false;
+	}
+	return true;
+}

package/node_modules/pi-mono-team-mode/core/teammate-specs.ts

@@ -0,0 +1,124 @@
+/**
+ * Pi Team-Mode — Teammate Spec Loader
+ *
+ * Reads role specs from `.pi/teammates/<role>.md` or `.claude/teammates/<role>.md`
+ * (checked in that order). Frontmatter fields drive runtime behavior; the
+ * markdown body becomes the teammate's system prompt.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import * as path from "node:path";
+
+import type { TeammateSpec } from "./types.js";
+import { isThinkingLevel } from "./model-config.js";
+
+const SPEC_DIRS = [".pi/teammates", ".claude/teammates"] as const;
+
+/**
+ * Locate and parse a teammate spec by role name.
+ * Returns `null` if no matching spec file exists in either directory.
+ */
+export async function loadTeammateSpec(
+	cwd: string,
+	role: string,
+): Promise<TeammateSpec | null> {
+	for (const dir of SPEC_DIRS) {
+		const filePath = path.join(cwd, dir, `${role}.md`);
+		const spec = await tryRead(filePath, role);
+		if (spec) return spec;
+	}
+	return null;
+}
+
+/** List all available teammate specs in the current project. Exported for tests and future /teammate specs command. */
+export async function listTeammateSpecs(cwd: string): Promise<TeammateSpec[]> {
+	const specs: TeammateSpec[] = [];
+	const seen = new Set<string>();
+	for (const dir of SPEC_DIRS) {
+		const absDir = path.join(cwd, dir);
+		let entries: string[] = [];
+		try {
+			entries = await readdir(absDir);
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+			throw err;
+		}
+		for (const entry of entries) {
+			if (!entry.endsWith(".md")) continue;
+			const role = entry.slice(0, -3);
+			if (seen.has(role)) continue;
+			const spec = await tryRead(path.join(absDir, entry), role);
+			if (spec) {
+				seen.add(role);
+				specs.push(spec);
+			}
+		}
+	}
+	return specs;
+}
+
+async function tryRead(filePath: string, role: string): Promise<TeammateSpec | null> {
+	let raw: string;
+	try {
+		raw = await readFile(filePath, "utf8");
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw err;
+	}
+	return parseSpec(raw, role, filePath);
+}
+
+/**
+ * Parse a markdown file with YAML-ish frontmatter.
+ *
+ * Frontmatter is delimited by `---` lines. Supports scalar values and simple
+ * comma-separated arrays (e.g. `tools: read, bash, grep`). We intentionally
+ * avoid a YAML dependency — the spec grammar is deliberately small.
+ */
+export function parseSpec(raw: string, fallbackRole: string, sourcePath: string): TeammateSpec {
+	const lines = raw.split(/\r?\n/);
+	let body = raw;
+	const fm: Record<string, string> = {};
+
+	if (lines[0]?.trim() === "---") {
+		const end = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+		if (end > 0) {
+			for (let i = 1; i < end; i++) {
+				const line = lines[i];
+				const match = line.match(/^([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+				if (match) {
+					fm[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, "");
+				}
+			}
+			body = lines.slice(end + 1).join("\n").trim();
+		}
+	}
+
+	const tools = fm.tools ? fm.tools.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+
+	return {
+		name: fm.name || fallbackRole,
+		description: fm.description,
+		needsWorktree: parseBool(fm.needsWorktree),
+		hasMemory: parseBool(fm.hasMemory),
+		modelTier: fm.modelTier,
+		thinkingLevel: parseThinkingLevel(fm.thinkingLevel ?? fm.thinking),
+		tools,
+		systemPrompt: body,
+		sourcePath,
+	};
+}
+
+function parseThinkingLevel(value: string | undefined): TeammateSpec["thinkingLevel"] {
+	if (value === undefined) return undefined;
+	const v = value.toLowerCase();
+	return isThinkingLevel(v) ? v : undefined;
+}
+
+function parseBool(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	const v = value.toLowerCase();
+	if (v === "true" || v === "yes" || v === "1") return true;
+	if (v === "false" || v === "no" || v === "0") return false;
+	return undefined;
+}

package/node_modules/pi-mono-team-mode/core/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Pi Team-Mode — Core Types
+ *
+ * Flat peer-agent model mirroring Claude Code's team-mode semantics:
+ * named teammates are spawned and optionally grouped under teams; each
+ * teammate has its own resumable pi session.
+ */
+
+export type TeammateStatus =
+	| "pending"
+	| "running"
+	| "completed"
+	| "failed"
+	| "stopped";
+
+export type TeammateExitReason =
+	| "completed"
+	| "stopped"
+	| "failed"
+	| "wrapped_up"
+	| "aborted";
+
+export type IsolationMode = "none" | "worktree";
+
+export type ExecutionRuntime = "subprocess" | "transient";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** Persistent record for a single named teammate. */
+export type TeammateRecord = {
+	/** Stable id, used as pi session id. */
+	id: string;
+	/** Caller-supplied name (unique within a session). Falls back to id if omitted. */
+	name: string;
+	/** Optional team grouping (namespace). */
+	teamId?: string;
+	/** Role/spec name (e.g. "researcher", "reviewer"). */
+	subagentType?: string;
+	/** Bare model id passed to pi via `--model`. */
+	model?: string;
+	/** Provider passed to pi via `--provider`. */
+	provider?: string;
+	/** Thinking level passed to pi via `--thinking`. */
+	thinkingLevel?: ThinkingLevel;
+	/** Isolation strategy at spawn time. */
+	isolation: IsolationMode;
+	/** Working directory the teammate operates in. */
+	cwd: string;
+	/** Worktree branch, when isolation="worktree". */
+	worktreeBranch?: string;
+	/** Lifecycle status. */
+	status: TeammateStatus;
+	/** Pid of the currently-running pi subprocess (if any). */
+	pid?: number;
+	/** Whether the caller requested background execution. */
+	background: boolean;
+	/** ISO timestamp. */
+	createdAt: string;
+	/** ISO timestamp, updated on every turn completion. */
+	updatedAt: string;
+	/** Last final message emitted by the teammate. */
+	lastResult?: string;
+	/** Exit code of the last subprocess run. */
+	lastExitCode?: number;
+	/** Parent session id (the main pi session that owns this teammate). */
+	parentSessionId?: string;
+};
+
+/** Persistent record for a team grouping. */
+export type TeamRecord = {
+	id: string;
+	name: string;
+	/** ISO timestamp. */
+	createdAt: string;
+	/** Default isolation for teammates spawned under this team. */
+	defaultIsolation: IsolationMode;
+	/** Base directory for worktrees created under this team. */
+	worktreeBase?: string;
+	/** Parent session id (the main pi session that created this team). */
+	parentSessionId?: string;
+};
+
+/** Arguments accepted by `agentManager.spawn()`. */
+export type SpawnOpts = {
+	description: string;
+	prompt: string;
+	name?: string;
+	teamId?: string;
+	subagentType?: string;
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	isolation?: IsolationMode;
+	background?: boolean;
+	/** Execution backend. Defaults to subprocess for durable/resumable workers. */
+	runtime?: ExecutionRuntime;
+	/** Override cwd (defaults to ctx.cwd or team's worktreeBase). */
+	cwd?: string;
+};
+
+export type LiveTeammateMetrics = {
+	turns: number;
+	maxTurns?: number;
+	toolUses: number;
+	tokens: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	activityHint?: string;
+	startedAt: number;
+	finishedAt?: number;
+	exitReason?: TeammateExitReason;
+};
+
+export type LiveTeammateSnapshot = {
+	record: TeammateRecord;
+	metrics: LiveTeammateMetrics;
+	description?: string;
+	transcriptPath: string;
+};
+
+/** Outcome of a spawn or send_message operation. */
+export type TeammateRunResult = {
+	teammateId: string;
+	name: string;
+	/** Short task label passed at spawn. Used in the task-notification summary. */
+	description?: string;
+	status: TeammateStatus;
+	/** Final text message from the teammate, or a stub if background. */
+	result: string;
+	exitCode: number | null;
+	metrics?: LiveTeammateMetrics;
+	transcriptPath?: string;
+	provider?: string;
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	modelRationale?: string;
+	worktree?: {
+		path: string;
+		branch: string;
+	};
+	background?: boolean;
+	durationMs?: number;
+	runtime?: ExecutionRuntime;
+};
+
+/** Teammate role spec loaded from `.pi/teammates/*.md` or `.claude/teammates/*.md`. */
+export type TeammateSpec = {
+	name: string;
+	description?: string;
+	needsWorktree?: boolean;
+	hasMemory?: boolean;
+	modelTier?: string;
+	/** Default thinking level for this role. */
+	thinkingLevel?: ThinkingLevel;
+	/** Allowed tool names (forwarded via pi --tools). */
+	tools?: string[];
+	/** Markdown body becomes the teammate's system prompt. */
+	systemPrompt: string;
+	/** Path the spec was loaded from, for diagnostics. */
+	sourcePath: string;
+};