@tmustier/pi-agent-teams 0.4.0-beta.3 → 0.5.0

package/extensions/teams/activity-tracker.ts

@@ -1,14 +1,148 @@
 import type { AgentEvent } from "@mariozechner/pi-agent-core";
 
+// ── Helpers ──
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
 // ── Transcript types ──
 
 export type TranscriptEntry =
 	| { kind: "text"; text: string; timestamp: number }
-	| { kind: "tool_start"; toolName: string; timestamp: number }
-	| { kind: "tool_end"; toolName: string; durationMs: number; timestamp: number }
+	| { kind: "tool_start"; toolName: string; content: string | null; summary: string | null; timestamp: number }
+	| { kind: "tool_end"; toolName: string; content: string | null; summary: string | null; isError: boolean; durationMs: number; timestamp: number }
 	| { kind: "turn_end"; turnNumber: number; tokens: number; timestamp: number };
 
 const MAX_TRANSCRIPT = 200;
+const MAX_SUMMARY_LENGTH = 120;
+
+// ── Tool content summarization ──
+
+function truncateSummary(text: string): string {
+	if (text.length <= MAX_SUMMARY_LENGTH) return text;
+	return `${text.slice(0, MAX_SUMMARY_LENGTH - 1)}…`;
+}
+
+function summarizeToolArgs(toolName: string, args: unknown): string {
+	if (!isRecord(args)) return "";
+	const key = toolName.toLowerCase();
+
+	if (key === "read" || key === "write") {
+		const path = typeof args.path === "string" ? args.path : null;
+		if (!path) return "";
+		return truncateSummary(path);
+	}
+
+	if (key === "edit") {
+		const path = typeof args.path === "string" ? args.path : null;
+		if (!path) return "";
+		return truncateSummary(path);
+	}
+
+	if (key === "bash") {
+		const cmd = typeof args.command === "string" ? args.command : null;
+		if (!cmd) return "";
+		return truncateSummary(cmd.replace(/\s+/g, " ").trim());
+	}
+
+	if (key === "grep" || key === "glob") {
+		const pattern = typeof args.pattern === "string" ? args.pattern : null;
+		const path = typeof args.path === "string" ? args.path : null;
+		const parts: string[] = [];
+		if (pattern) parts.push(pattern);
+		if (path) parts.push(`in ${path}`);
+		return truncateSummary(parts.join(" "));
+	}
+
+	if (key === "webfetch" || key === "websearch") {
+		const url = typeof args.url === "string" ? args.url : null;
+		const query = typeof args.query === "string" ? args.query : null;
+		return truncateSummary(url ?? query ?? "");
+	}
+
+	if (key === "team_message") {
+		const recipient = typeof args.recipient === "string" ? args.recipient : null;
+		const message = typeof args.message === "string" ? args.message : null;
+		if (recipient && message) return truncateSummary(`→ ${recipient}: ${message.replace(/\s+/g, " ").trim()}`);
+		if (message) return truncateSummary(message.replace(/\s+/g, " ").trim());
+		return recipient ? truncateSummary(`→ ${recipient}`) : "";
+	}
+
+	if (key === "task" || key === "teams") {
+		const action = typeof args.action === "string" ? args.action : null;
+		return action ? truncateSummary(action) : "";
+	}
+
+	// Fallback: try to find a meaningful first-string arg
+	for (const v of Object.values(args)) {
+		if (typeof v === "string" && v.length > 0) return truncateSummary(v);
+	}
+	return "";
+}
+
+/**
+ * Extract the first text content from a ToolResultMessage-shaped result.
+ * The agent-loop emits `{ content: [{type: "text", text: "..."}], ... }`.
+ */
+function extractContentText(result: Record<string, unknown>): string | null {
+	const content = result.content;
+	if (!Array.isArray(content)) return null;
+	for (const item of content) {
+		if (isRecord(item) && item.type === "text" && typeof item.text === "string") {
+			return item.text;
+		}
+	}
+	return null;
+}
+
+function summarizeToolResult(toolName: string, result: unknown, isError: boolean): string {
+	if (isError) {
+		if (typeof result === "string") return truncateSummary(result.replace(/\s+/g, " ").trim());
+		if (isRecord(result)) {
+			// Try content array first (ToolResultMessage shape)
+			const contentText = extractContentText(result);
+			if (contentText !== null) {
+				const trimmed = contentText.replace(/\s+/g, " ").trim();
+				return trimmed.length > 0 ? truncateSummary(trimmed) : "error";
+			}
+			const msg = typeof result.message === "string"
+				? result.message
+				: typeof result.error === "string"
+					? result.error
+					: null;
+			if (msg) return truncateSummary(msg.replace(/\s+/g, " ").trim());
+		}
+		return "error";
+	}
+
+	if (typeof result === "string") {
+		const compact = result.replace(/\s+/g, " ").trim();
+		if (compact.length === 0) return "(empty)";
+		return truncateSummary(compact);
+	}
+
+	if (isRecord(result)) {
+		// Try content array first (ToolResultMessage shape from agent-loop)
+		const contentText = extractContentText(result);
+		if (contentText !== null) {
+			const compact = contentText.replace(/\s+/g, " ").trim();
+			if (compact.length === 0) return "(empty)";
+			return truncateSummary(compact);
+		}
+		// Fallback: check for common structured result shapes
+		const status = typeof result.status === "string" ? result.status : null;
+		if (status) return truncateSummary(status);
+		const output = typeof result.output === "string" ? result.output : null;
+		if (output) return truncateSummary(output.replace(/\s+/g, " ").trim());
+	}
+
+	if (Array.isArray(result)) {
+		return `${String(result.length)} items`;
+	}
+
+	return "";
+}
 
 export class TranscriptLog {
 	private entries: TranscriptEntry[] = [];
@@ -33,6 +167,160 @@ export class TranscriptLog {
 	}
 }
 
+// ── Tool content extraction ──
+// Extracts a compact, human-readable summary from tool args/results.
+// Budget: ≤120 chars to fit one terminal line minus timestamp prefix.
+
+const MAX_CONTENT_LEN = 120;
+
+function truncateContent(s: string, maxLen: number = MAX_CONTENT_LEN): string {
+	const oneLine = s.replace(/\n/g, " ").replace(/\s+/g, " ").trim();
+	if (oneLine.length <= maxLen) return oneLine;
+	return oneLine.slice(0, maxLen - 1) + "\u2026";
+}
+
+/**
+ * Extract a display-friendly summary from tool start args.
+ *
+ * Known tool shapes:
+ *   read  → { path }
+ *   edit  → { path }
+ *   write → { path }
+ *   bash  → { command }
+ *   grep  → { pattern, path? }
+ *   glob  → { pattern }
+ *
+ * Falls back to the first short string value for unknown tools.
+ */
+function extractStartContent(toolName: string, args: unknown): string | null {
+	if (!isRecord(args)) return null;
+	const key = toolName.toLowerCase();
+
+	if (key === "read" || key === "edit" || key === "write") {
+		const p = args.path;
+		return typeof p === "string" ? truncateContent(p) : null;
+	}
+	if (key === "bash") {
+		const cmd = args.command;
+		return typeof cmd === "string" ? truncateContent(cmd) : null;
+	}
+	if (key === "grep") {
+		const pattern = args.pattern;
+		const path = args.path;
+		if (typeof pattern !== "string") return null;
+		const suffix = typeof path === "string" ? ` in ${path}` : "";
+		return truncateContent(`/${pattern}/${suffix}`);
+	}
+	if (key === "glob" || key === "find") {
+		const pattern = args.pattern;
+		return typeof pattern === "string" ? truncateContent(pattern) : null;
+	}
+
+	// Unknown tool: show the first short string arg value (if any).
+	for (const v of Object.values(args)) {
+		if (typeof v === "string" && v.length > 0 && v.length <= MAX_CONTENT_LEN) {
+			return truncateContent(v);
+		}
+	}
+	return null;
+}
+
+/**
+ * Extract a cleaner summary for display (may differ from content for some tools).
+ *
+ * grep: strips regex slashes → "TODO in /src" instead of "/TODO/ in /src"
+ * team_message: "→ bob: please rebase onto main" instead of just "bob"
+ * bash: normalizes whitespace
+ * Others: same as extractStartContent
+ */
+function extractStartSummary(toolName: string, args: unknown): string | null {
+	if (!isRecord(args)) return null;
+	const key = toolName.toLowerCase();
+
+	if (key === "grep") {
+		const pattern = args.pattern;
+		const path = args.path;
+		if (typeof pattern !== "string") return null;
+		const suffix = typeof path === "string" ? ` in ${path}` : "";
+		return truncateContent(`${pattern}${suffix}`);
+	}
+	if (key === "team_message" || key === "message_dm" || key === "message_broadcast") {
+		const recipient = args.recipient ?? args.to ?? args.name;
+		const message = args.message;
+		if (typeof recipient === "string" && typeof message === "string") {
+			return truncateContent(`→ ${recipient}: ${message}`);
+		}
+	}
+	if (key === "bash") {
+		const cmd = args.command;
+		if (typeof cmd === "string") {
+			return truncateContent(cmd.replace(/\s+/g, " ").trim());
+		}
+	}
+	// Fall through to default extraction
+	return extractStartContent(toolName, args);
+}
+
+/**
+ * Extract a display-friendly summary from tool end result.
+ *
+ * For errors: first line of error text.
+ * For success: null (the tool_end line already shows tool name + duration;
+ * adding full output would be noisy).
+ */
+function extractEndContent(isError: boolean, result: unknown): string | null {
+	if (!isError) return null;
+	if (typeof result === "string") return truncateContent(result);
+	if (isRecord(result)) {
+		const msg = result.error ?? result.message ?? result.stderr ?? result.output;
+		if (typeof msg === "string") return truncateContent(msg);
+	}
+	return null;
+}
+
+/**
+ * Extract a display-friendly summary from tool end result (for both success and error).
+ *
+ * Unlike extractEndContent (which only extracts for errors), this extracts
+ * a compact summary from any result for display in the transcript.
+ */
+function extractEndSummary(isError: boolean, result: unknown): string | null {
+	// For errors, try existing logic first, then fall through to content array extraction
+	if (isError) {
+		const fromContent = extractEndContent(isError, result);
+		if (fromContent !== null) return fromContent;
+		// Fall through to handle { content: [{ type: "text", text: "..." }] } shape
+	}
+
+	// For success: try to extract text from common result shapes
+	if (typeof result === "string") {
+		return result.length === 0 ? "(empty)" : truncateContent(result.replace(/\n/g, " "));
+	}
+	if (isRecord(result)) {
+		// Handle { content: [{ type: "text", text: "..." }] } shape (common in pi tool results)
+		const content = result.content;
+		if (Array.isArray(content)) {
+			const texts: string[] = [];
+			for (const item of content) {
+				if (isRecord(item) && typeof item.text === "string") {
+					texts.push(item.text);
+				}
+			}
+			if (texts.length > 0) {
+				const joined = texts.join(" ").replace(/\n/g, " ");
+				return joined.length === 0 ? "(empty)" : truncateContent(joined);
+			}
+		}
+		// Handle { output: "..." } or { message: "..." }
+		const msg = result.output ?? result.message ?? result.text;
+		if (typeof msg === "string") {
+			return msg.length === 0 ? "(empty)" : truncateContent(msg.replace(/\n/g, " "));
+		}
+	}
+	// No extractable content
+	return null;
+}
+
 export class TranscriptTracker {
 	private logs = new Map<string, TranscriptLog>();
 	private toolStarts = new Map<string, Map<string, number>>(); // name -> toolCallId -> startTimestamp
@@ -61,7 +349,9 @@ export class TranscriptTracker {
 			const starts = this.toolStarts.get(name) ?? new Map<string, number>();
 			starts.set(ev.toolCallId, now);
 			this.toolStarts.set(name, starts);
-			log.push({ kind: "tool_start", toolName: ev.toolName, timestamp: now });
+			const content = extractStartContent(ev.toolName, ev.args);
+			const summary = extractStartSummary(ev.toolName, ev.args);
+			log.push({ kind: "tool_start", toolName: ev.toolName, content, summary, timestamp: now });
 			return;
 		}
 
@@ -70,7 +360,9 @@ export class TranscriptTracker {
 			const startTs = starts?.get(ev.toolCallId);
 			const durationMs = startTs === undefined ? 0 : now - startTs;
 			starts?.delete(ev.toolCallId);
-			log.push({ kind: "tool_end", toolName: ev.toolName, durationMs, timestamp: now });
+			const content = extractEndContent(ev.isError, ev.result);
+			const summary = extractEndSummary(ev.isError, ev.result);
+			log.push({ kind: "tool_end", toolName: ev.toolName, content, summary, isError: ev.isError, durationMs, timestamp: now });
 			return;
 		}
 
@@ -148,10 +440,6 @@ export class TranscriptTracker {
 
 type TrackedEventType = "tool_execution_start" | "tool_execution_end" | "agent_end" | "message_end";
 
-function isRecord(v: unknown): v is Record<string, unknown> {
-	return typeof v === "object" && v !== null;
-}
-
 export interface TeammateActivity {
 	toolUseCount: number;
 	currentToolName: string | null;

package/extensions/teams/cleanup.ts

@@ -1,5 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { cleanupWorktrees, type WorktreeCleanupResult } from "./worktree.js";
+
+export type CleanupResult = {
+	teamDir: string;
+	worktreeResult: WorktreeCleanupResult;
+	warnings: string[];
+};
 
 export function assertTeamDirWithinTeamsRoot(teamsRootDir: string, teamDir: string): {
 	teamsRootAbs: string;
@@ -21,11 +28,217 @@ export function assertTeamDirWithinTeamsRoot(teamsRootDir: string, teamDir: stri
 }
 
 /**
- * Recursively delete the given teamDir, but only if it's safely inside teamsRootDir.
+ * Recursively delete the given teamDir, including proper git worktree + branch removal.
+ *
+ * Steps:
+ * 1. Remove git worktrees and branches via `cleanupWorktrees`
+ * 2. Delete the team directory recursively
  *
- * Uses fs.rm({ recursive: true, force: true }) so it's idempotent.
+ * Idempotent — safe to call multiple times.
  */
-export async function cleanupTeamDir(teamsRootDir: string, teamDir: string): Promise<void> {
+export async function cleanupTeamDir(
+	teamsRootDir: string,
+	teamDir: string,
+	opts?: { teamId?: string; repoCwd?: string },
+): Promise<CleanupResult> {
 	const { teamDirAbs } = assertTeamDirWithinTeamsRoot(teamsRootDir, teamDir);
+	const warnings: string[] = [];
+
+	// Infer teamId from directory name if not provided.
+	const teamId = opts?.teamId ?? path.basename(teamDirAbs);
+
+	// 1. Clean up git worktrees and branches before deleting the directory.
+	let worktreeResult: WorktreeCleanupResult = { removedWorktrees: [], removedBranches: [], warnings: [] };
+	try {
+		worktreeResult = await cleanupWorktrees({ teamDir: teamDirAbs, teamId, repoCwd: opts?.repoCwd });
+		warnings.push(...worktreeResult.warnings);
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		warnings.push(`Worktree cleanup failed (non-fatal): ${msg}`);
+	}
+
+	// 2. Delete the team directory.
 	await fs.promises.rm(teamDirAbs, { recursive: true, force: true });
+
+	return { teamDir: teamDirAbs, worktreeResult, warnings };
+}
+
+/**
+ * Garbage-collect stale team directories that have no active workers and are older
+ * than the given threshold.
+ *
+ * A team directory is considered stale when:
+ * - Its config.json `createdAt` (or directory mtime) is older than `maxAgeMs`
+ * - It has no in_progress tasks
+ * - It has no online members
+ *
+ * Returns a summary of what was cleaned up.
+ */
+export async function gcStaleTeamDirs(opts: {
+	teamsRootDir: string;
+	maxAgeMs: number;
+	repoCwd?: string;
+	dryRun?: boolean;
+}): Promise<{
+	scanned: number;
+	removed: string[];
+	skipped: Array<{ teamId: string; reason: string }>;
+	warnings: string[];
+}> {
+	const { teamsRootDir, maxAgeMs, repoCwd, dryRun } = opts;
+	const teamsRootAbs = path.resolve(teamsRootDir);
+	const removed: string[] = [];
+	const skipped: Array<{ teamId: string; reason: string }> = [];
+	const warnings: string[] = [];
+
+	let entries: string[];
+	try {
+		entries = await fs.promises.readdir(teamsRootAbs);
+	} catch {
+		return { scanned: 0, removed, skipped, warnings: ["teams root directory not found"] };
+	}
+
+	// Filter out non-team entries (like _styles, _hooks).
+	const teamEntries = entries.filter((e) => !e.startsWith("_"));
+	const now = Date.now();
+
+	for (const teamId of teamEntries) {
+		const teamDir = path.join(teamsRootAbs, teamId);
+		let stat: fs.Stats;
+		try {
+			stat = await fs.promises.stat(teamDir);
+		} catch {
+			continue;
+		}
+		if (!stat.isDirectory()) continue;
+
+		// Check age: prefer config.json createdAt, fall back to directory mtime.
+		let ageMs: number;
+		try {
+			const configPath = path.join(teamDir, "config.json");
+			const configRaw = await fs.promises.readFile(configPath, "utf8");
+			const config: unknown = JSON.parse(configRaw);
+			const createdAt = typeof config === "object" && config !== null && "createdAt" in config
+				? (config as Record<string, unknown>).createdAt
+				: undefined;
+			if (typeof createdAt === "string") {
+				const ts = Date.parse(createdAt);
+				ageMs = Number.isFinite(ts) ? now - ts : now - stat.mtimeMs;
+			} else {
+				ageMs = now - stat.mtimeMs;
+			}
+		} catch {
+			ageMs = now - stat.mtimeMs;
+		}
+
+		if (ageMs < maxAgeMs) {
+			skipped.push({ teamId, reason: "too recent" });
+			continue;
+		}
+
+		// Check for active work: in_progress tasks, online workers, or live attach claims.
+		let hasActiveWork = false;
+		try {
+			const configPath = path.join(teamDir, "config.json");
+			const configRaw = await fs.promises.readFile(configPath, "utf8");
+			const config: unknown = JSON.parse(configRaw);
+			if (typeof config === "object" && config !== null) {
+				const members = (config as Record<string, unknown>).members;
+				if (Array.isArray(members)) {
+					for (const m of members) {
+						if (typeof m !== "object" || m === null) continue;
+						const rec = m as Record<string, unknown>;
+						// Ignore the lead — it stays "online" forever and is not a signal of activity.
+						if (rec.role === "lead") continue;
+						if (rec.status === "online") {
+							hasActiveWork = true;
+							break;
+						}
+					}
+				}
+			}
+		} catch {
+			// No config — probably safe to remove.
+		}
+
+		// Check for a live attach claim (another session is using this team).
+		if (!hasActiveWork) {
+			try {
+				const claimPath = path.join(teamDir, ".attach-claim.json");
+				const claimRaw = await fs.promises.readFile(claimPath, "utf8");
+				const claim: unknown = JSON.parse(claimRaw);
+				if (typeof claim === "object" && claim !== null) {
+					const heartbeatAt = (claim as Record<string, unknown>).heartbeatAt;
+					if (typeof heartbeatAt === "string") {
+						const hbTs = Date.parse(heartbeatAt);
+						// Consider claims fresh if heartbeat is within 5 minutes.
+						const claimFreshnessMs = 5 * 60 * 1000;
+						if (Number.isFinite(hbTs) && now - hbTs < claimFreshnessMs) {
+							hasActiveWork = true;
+						}
+					}
+				}
+			} catch {
+				// No claim file or invalid — not actively attached.
+			}
+		}
+
+		if (!hasActiveWork) {
+			// Check task files for in_progress tasks.
+			// Tasks live at tasks/<taskListId>/<id>.json — scan all subdirectories.
+			try {
+				const tasksDir = path.join(teamDir, "tasks");
+				const taskListDirs = await fs.promises.readdir(tasksDir);
+				for (const listDir of taskListDirs) {
+					if (hasActiveWork) break;
+					const listPath = path.join(tasksDir, listDir);
+					let listStat: fs.Stats;
+					try {
+						listStat = await fs.promises.stat(listPath);
+					} catch {
+						continue;
+					}
+					if (!listStat.isDirectory()) continue;
+
+					const taskFiles = await fs.promises.readdir(listPath);
+					for (const tf of taskFiles) {
+						if (!tf.endsWith(".json")) continue;
+						try {
+							const raw = await fs.promises.readFile(path.join(listPath, tf), "utf8");
+							const parsed: unknown = JSON.parse(raw);
+							if (typeof parsed === "object" && parsed !== null && (parsed as Record<string, unknown>).status === "in_progress") {
+								hasActiveWork = true;
+								break;
+							}
+						} catch {
+							// ignore individual task read errors
+						}
+					}
+				}
+			} catch {
+				// No tasks dir — fine.
+			}
+		}
+
+		if (hasActiveWork) {
+			skipped.push({ teamId, reason: "has active work" });
+			continue;
+		}
+
+		if (dryRun) {
+			removed.push(teamId);
+			continue;
+		}
+
+		try {
+			const result = await cleanupTeamDir(teamsRootAbs, teamDir, { teamId, repoCwd });
+			warnings.push(...result.warnings);
+			removed.push(teamId);
+		} catch (err: unknown) {
+			const msg = err instanceof Error ? err.message : String(err);
+			warnings.push(`Failed to remove ${teamId}: ${msg}`);
+		}
+	}
+
+	return { scanned: teamEntries.length, removed, skipped, warnings };
 }

package/extensions/teams/hooks.ts

@@ -4,6 +4,12 @@ import { spawn } from "node:child_process";
 import { getTeamsHooksDir } from "./paths.js";
 import type { TeamTask } from "./task-store.js";
 
+/**
+ * Hook contract version. Increment on breaking changes only.
+ * See docs/hook-contract.md for the full compatibility policy.
+ */
+export const HOOK_CONTRACT_VERSION = 1;
+
 export type TeamsHookEvent = "idle" | "task_completed" | "task_failed";
 
 export type TeamsHookInvocation = {
@@ -17,6 +23,43 @@ export type TeamsHookInvocation = {
 	completedTask?: TeamTask | null;
 };
 
+/**
+ * Structured context payload passed to hooks via PI_TEAMS_HOOK_CONTEXT_JSON.
+ *
+ * `task` is null for "idle" events and may also be null for task_completed /
+ * task_failed events when the task was cleared before the leader processed the
+ * worker's idle notification (race condition). Hook authors must guard access.
+ *
+ * For task_failed events, `task.status` is typically "pending" — the worker
+ * resets the task status before emitting the idle notification.
+ *
+ * See docs/hook-contract.md for the full schema and compatibility policy.
+ */
+export interface HookContextPayload {
+	version: typeof HOOK_CONTRACT_VERSION;
+	event: TeamsHookEvent;
+	team: {
+		id: string;
+		dir: string;
+		taskListId: string;
+		style: string;
+	};
+	member: string | null;
+	timestamp: string | null;
+	task: {
+		id: string;
+		subject: string;
+		description: string;
+		owner: string | null;
+		status: string;
+		blockedBy: string[];
+		blocks: string[];
+		metadata: Record<string, unknown>;
+		createdAt: string;
+		updatedAt: string;
+	} | null;
+}
+
 export type TeamsHookRunResult = {
 	ran: boolean;
 	hookPath?: string;
@@ -27,6 +70,8 @@ export type TeamsHookRunResult = {
 	stdout: string;
 	stderr: string;
 	error?: string;
+	/** The contract version used for this invocation. */
+	contractVersion: typeof HOOK_CONTRACT_VERSION;
 };
 
 function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
@@ -126,10 +171,10 @@ function truncateField(value: string, max: number): string {
 	return `${value.slice(0, Math.max(0, max - 1))}…`;
 }
 
-function getHookContextJson(invocation: TeamsHookInvocation): string {
+export function buildHookContextPayload(invocation: TeamsHookInvocation): HookContextPayload {
 	const task = invocation.completedTask;
-	const payload = {
-		version: 1,
+	return {
+		version: HOOK_CONTRACT_VERSION,
 		event: invocation.event,
 		team: {
 			id: invocation.teamId,
@@ -154,7 +199,10 @@ function getHookContextJson(invocation: TeamsHookInvocation): string {
 			}
 			: null,
 	};
-	return JSON.stringify(payload);
+}
+
+function getHookContextJson(invocation: TeamsHookInvocation): string {
+	return JSON.stringify(buildHookContextPayload(invocation));
 }
 
 export function getHookBaseName(event: TeamsHookEvent): string {
@@ -280,6 +328,7 @@ export async function runTeamsHook(opts: {
 			durationMs: 0,
 			stdout: "",
 			stderr: "",
+			contractVersion: HOOK_CONTRACT_VERSION,
 		};
 	}
 
@@ -293,6 +342,7 @@ export async function runTeamsHook(opts: {
 			durationMs: 0,
 			stdout: "",
 			stderr: "",
+			contractVersion: HOOK_CONTRACT_VERSION,
 		};
 	}
 
@@ -302,7 +352,7 @@ export async function runTeamsHook(opts: {
 	const baseEnv: NodeJS.ProcessEnv = {
 		...env,
 		PI_TEAMS_HOOK_EVENT: opts.invocation.event,
-		PI_TEAMS_HOOK_CONTEXT_VERSION: "1",
+		PI_TEAMS_HOOK_CONTEXT_VERSION: String(HOOK_CONTRACT_VERSION),
 		PI_TEAMS_HOOK_CONTEXT_JSON: getHookContextJson(opts.invocation),
 		PI_TEAMS_TEAM_ID: opts.invocation.teamId,
 		PI_TEAMS_TEAM_DIR: opts.invocation.teamDir,
@@ -336,6 +386,7 @@ export async function runTeamsHook(opts: {
 			stdout: "",
 			stderr: "",
 			error: msg,
+			contractVersion: HOOK_CONTRACT_VERSION,
 		};
 	}
 
@@ -349,6 +400,7 @@ export async function runTeamsHook(opts: {
 		stdout: res.stdout,
 		stderr: res.stderr,
 		error: res.error,
+		contractVersion: HOOK_CONTRACT_VERSION,
 	};
 }