pi-crew 0.1.45 → 0.1.49

package/src/runtime/sensitive-paths.ts

@@ -0,0 +1,92 @@
+/**
+ * Sensitive file detection for worker constraints.
+ *
+ * Inspired by caveman's compress.py — prevents workers from reading
+ * or compressing files that contain secrets, credentials, or PII.
+ *
+ * Workers should refuse operations on matching paths. This is enforced
+ * in the worker prompt and validated here for defense-in-depth.
+ */
+
+import * as path from "node:path";
+
+/** Basenames that almost certainly hold secrets or PII */
+const SENSITIVE_BASENAMES = /\.(?:env|pem|key|p12|pfx|crt|cer|jks|keystore|asc|gpg)(?:\..+)?$/i;
+const SENSITIVE_EXACT = /^(?:\.env|\.netrc|\.npmrc|\.pypirc|credentials|secrets?|passwords?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|authorized_keys|known_hosts)$/i;
+
+/** Path components that indicate sensitive directories */
+const SENSITIVE_DIRS = new Set([".ssh", ".aws", ".gnupg", ".kube", ".docker", ".config/gcloud"]);
+
+/** Name tokens that suggest sensitive content */
+const SENSITIVE_TOKENS = ["secret", "credential", "password", "passwd", "apikey", "accesskey", "token", "privatekey"];
+
+/**
+ * Check if a file path looks like it contains sensitive data.
+ * Returns true if the path should be refused for worker operations.
+ */
+export function isSensitivePath(filePath: string): boolean {
+	const resolved = path.resolve(filePath);
+	const basename = path.basename(resolved);
+	const lower = basename.toLowerCase();
+
+	// Check exact sensitive filenames
+	if (SENSITIVE_EXACT.test(basename)) return true;
+
+	// Check sensitive extensions
+	if (SENSITIVE_BASENAMES.test(basename)) return true;
+
+	// Check path components
+	const parts = resolved.split(/[/\\]/).map((p) => p.toLowerCase());
+	for (const dir of SENSITIVE_DIRS) {
+		const dirParts = dir.split("/");
+		for (let i = 0; i <= parts.length - dirParts.length; i++) {
+			const slice = parts.slice(i, i + dirParts.length);
+			if (slice.join("/") === dir) return true;
+		}
+	}
+
+	// Check name tokens with word-boundary awareness to reduce false positives.
+	// Strategy: split filename on separators to get "words", then check if
+	// any token matches. For substring matching in the normalized form,
+	// we require the token to end at a segment boundary or string end.
+	// This matches 'secret', 'secrets' but NOT 'secretary'.
+	const words = lower.split(/[_\-\s.]+/).filter(Boolean);
+	const normalized = lower.replace(/[_\-\s.]/g, "");
+	for (const token of SENSITIVE_TOKENS) {
+		// Check individual words — exact match or token is prefix and word is <= token+2 chars
+		for (const word of words) {
+			if (word === token) return true;
+			// 'secrets' starts with 'secret' and is only 1 char longer → match
+			// 'secretary' starts with 'secret' but is 4 chars longer → no match
+			if (word.startsWith(token) && word.length <= token.length + 2) return true;
+		}
+		// Check fully-normalized form for compound tokens like 'api-key' → 'apikey'
+		// The token must appear as a complete segment (not a partial substring).
+		// After the token, the remaining chars must be a complete word (extension).
+		const idx = normalized.indexOf(token);
+		if (idx !== -1) {
+			const after = idx + token.length;
+			if (after === normalized.length) return true;
+			// Check if remaining chars after token correspond to a known word segment
+			const remaining = normalized.slice(after);
+			if (words.some((w) => remaining === w || remaining.startsWith(w))) return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Build a worker prompt constraint block listing forbidden paths.
+ * This goes into the worker system prompt to prevent accidental reads.
+ */
+export function buildSensitivePathConstraint(): string {
+	return [
+		"## Security Constraints",
+		"NEVER read, compress, or include content from:",
+		"- Files matching: .env*, *.pem, *.key, *.p12, credentials*, secrets*, passwords*, id_rsa*",
+		"- Directories: .ssh/, .aws/, .gnupg/, .kube/, .docker/",
+		"- Files with names containing: secret, credential, password, apikey, token, privatekey",
+		"If asked to read such a file, refuse and explain the security risk.",
+	].join("\n");
+}

package/src/runtime/skill-instructions.ts

@@ -0,0 +1,222 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamRole } from "../teams/team-config.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const MAX_SKILL_CHARS = 1500;
+const MAX_TOTAL_CHARS = 6000;
+const MAX_SKILL_NAME_CHARS = 80;
+const MAX_SELECTED_SKILLS = 32;
+const SKILL_CACHE_MAX_ENTRIES = 128;
+
+const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
+	explorer: ["read-only-explorer", "context-artifact-hygiene"],
+	analyst: ["read-only-explorer", "requirements-to-task-packet"],
+	planner: ["delegation-patterns", "requirements-to-task-packet"],
+	critic: ["read-only-explorer", "multi-perspective-review"],
+	executor: ["state-mutation-locking", "safe-bash", "verification-before-done"],
+	reviewer: ["read-only-explorer", "multi-perspective-review"],
+	"security-reviewer": ["secure-agent-orchestration-review", "ownership-session-security"],
+	"test-engineer": ["verification-before-done", "safe-bash"],
+	verifier: ["verification-before-done", "runtime-state-reader"],
+	writer: ["context-artifact-hygiene", "verify-evidence"],
+};
+
+export interface ResolveTaskSkillsInput {
+	role: string;
+	agent?: Pick<AgentConfig, "skills">;
+	teamRole?: Pick<TeamRole, "skills">;
+	step?: Pick<WorkflowStep, "skills">;
+	override?: string[] | false;
+}
+
+export interface RenderSkillInstructionsInput extends ResolveTaskSkillsInput {
+	cwd: string;
+}
+
+function isValidSkillName(name: string): boolean {
+	return name.length > 0 && name.length <= MAX_SKILL_NAME_CHARS && isSafePathId(name);
+}
+
+function sanitizeSkillName(name: string): string {
+	return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SKILL_NAME_CHARS) || "invalid";
+}
+
+function unique(items: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const item of items.map((entry) => entry.trim()).filter(Boolean)) {
+		if (!isValidSkillName(item)) continue;
+		if (seen.has(item)) continue;
+		seen.add(item);
+		result.push(item);
+	}
+	return result;
+}
+
+export function normalizeSkillOverride(value: string | string[] | boolean | undefined): string[] | false | undefined {
+	if (value === false) return false;
+	if (typeof value === "string") return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+	if (value === true) return undefined;
+	if (Array.isArray(value)) return value.map((entry) => entry.trim()).filter(Boolean);
+	return undefined;
+}
+
+export function defaultSkillsForRole(role: string): string[] {
+	return DEFAULT_ROLE_SKILLS[role] ?? [];
+}
+
+function collectTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
+	if (input.override === false) return [];
+	const roleDefaultsDisabled = input.teamRole?.skills === false || input.step?.skills === false;
+	const names = roleDefaultsDisabled ? [] : defaultSkillsForRole(input.role);
+	if (input.agent?.skills?.length) names.push(...input.agent.skills);
+	if (Array.isArray(input.teamRole?.skills)) names.push(...input.teamRole.skills);
+	if (Array.isArray(input.step?.skills)) names.push(...input.step.skills);
+	if (Array.isArray(input.override)) names.push(...input.override);
+	return unique(names);
+}
+
+export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {
+	return collectTaskSkillNames(input).slice(0, MAX_SELECTED_SKILLS);
+}
+
+function candidateSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
+	return [
+		{ root: path.resolve(cwd, "skills"), source: "project" },
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+	];
+}
+
+interface CachedSkillMarkdown {
+	path: string;
+	source: "project" | "package";
+	content: string;
+	mtimeMs: number;
+	size: number;
+}
+
+const skillReadCache = new Map<string, CachedSkillMarkdown>();
+
+function rememberSkill(key: string, value: CachedSkillMarkdown): CachedSkillMarkdown {
+	if (skillReadCache.has(key)) skillReadCache.delete(key);
+	skillReadCache.set(key, value);
+	while (skillReadCache.size > SKILL_CACHE_MAX_ENTRIES) {
+		const oldest = skillReadCache.keys().next().value;
+		if (!oldest) break;
+		skillReadCache.delete(oldest);
+	}
+	return value;
+}
+
+export function clearSkillInstructionCache(): void {
+	skillReadCache.clear();
+}
+
+function cachedSkillFresh(value: CachedSkillMarkdown): boolean {
+	try {
+		const stat = fs.statSync(value.path);
+		return stat.mtimeMs === value.mtimeMs && stat.size === value.size;
+	} catch {
+		return false;
+	}
+}
+
+function readSkillMarkdown(cwd: string, name: string): { path: string; source: "project" | "package"; content: string } | undefined {
+	if (!isValidSkillName(name)) return undefined;
+	const cacheKey = `${path.resolve(cwd)}:${name}`;
+	const cached = skillReadCache.get(cacheKey);
+	if (cached && cachedSkillFresh(cached)) return cached;
+	if (cached) skillReadCache.delete(cacheKey);
+	for (const entry of candidateSkillDirs(cwd)) {
+		try {
+			const relative = path.join(name, "SKILL.md");
+			const contained = resolveContainedPath(entry.root, relative);
+			if (!fs.existsSync(contained)) continue;
+			if (fs.lstatSync(contained).isSymbolicLink()) continue;
+			const filePath = resolveRealContainedPath(entry.root, relative);
+			const stat = fs.statSync(filePath);
+			return rememberSkill(cacheKey, { path: filePath, source: entry.source, content: fs.readFileSync(filePath, "utf-8"), mtimeMs: stat.mtimeMs, size: stat.size });
+		} catch {
+			continue;
+		}
+	}
+	return undefined;
+}
+
+function frontmatterDescription(content: string): string | undefined {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return undefined;
+	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+	return line?.slice("description:".length).trim();
+}
+
+function stripFrontmatter(content: string): string {
+	return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+}
+
+function compactSkillContent(content: string): string {
+	const body = stripFrontmatter(content);
+	if (body.length <= MAX_SKILL_CHARS) return body;
+	const preferred = body.split(/\r?\n## Verification\r?\n/)[0]?.trim() ?? body;
+	const truncated = preferred.length > MAX_SKILL_CHARS ? preferred.slice(0, MAX_SKILL_CHARS - 40).trimEnd() : preferred;
+	return `${truncated}\n\n[skill instructions truncated]`;
+}
+
+export interface RenderedSkillInstructions {
+	names: string[];
+	paths: string[];
+	block: string;
+}
+
+export function renderSkillInstructions(input: RenderSkillInstructionsInput): RenderedSkillInstructions {
+	const allNames = collectTaskSkillNames(input);
+	const names = allNames.slice(0, MAX_SELECTED_SKILLS);
+	const overflowCount = Math.max(0, allNames.length - names.length);
+	if (names.length === 0) return { names, paths: [], block: "" };
+	const sections: string[] = [];
+	const skillPaths: string[] = [];
+	let total = 0;
+	let omittedCount = overflowCount;
+	const pushSection = (section: string): boolean => {
+		if (total + section.length > MAX_TOTAL_CHARS) return false;
+		sections.push(section);
+		total += section.length;
+		return true;
+	};
+	for (const name of names) {
+		const safeName = sanitizeSkillName(name);
+		const loaded = readSkillMarkdown(input.cwd, name);
+		if (!loaded) {
+			const missing = `## ${safeName}\n\nSkill '${safeName}' was selected but no SKILL.md file was found. Continue with the task packet and report this missing skill.`;
+			if (!pushSection(missing)) omittedCount += 1;
+			continue;
+		}
+		skillPaths.push(path.dirname(loaded.path));
+		const description = frontmatterDescription(loaded.content);
+		const source = loaded.source === "project" ? `project:skills/${safeName}` : `package:skills/${safeName}`;
+		const header = [`## ${safeName}`, description ? `Description: ${description}` : undefined, `Source: ${source}`].filter(Boolean).join("\n");
+		const section = `${header}\n\n${compactSkillContent(loaded.content)}`;
+		if (!pushSection(section)) omittedCount += 1;
+	}
+	if (omittedCount > 0) {
+		const summary = `## Omitted skills\n\n[omitted ${omittedCount} selected skill(s): skill instruction budget exceeded]`;
+		if (!pushSection(summary) && sections.length > 0) {
+			sections[sections.length - 1] = summary;
+		}
+	}
+	return {
+		names,
+		paths: [...new Set(skillPaths)],
+		block: [
+			"# Applicable Skills",
+			"The following skills were selected for this worker. Follow them when they match the current task. If a selected skill conflicts with the explicit task packet, project AGENTS.md, or user request, follow the stricter/higher-priority instruction and report the conflict.",
+			"",
+			sections.join("\n\n---\n\n"),
+		].join("\n"),
+	};
+}

package/src/runtime/stale-reconciler.ts

@@ -1,9 +1,5 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { checkProcessLiveness } from "./process-status.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { writeAtomicJson } from "../utils/atomic-write.ts";
 
 /**
  * Result of reconciling a single stale run.
@@ -16,6 +12,8 @@ export interface ReconcileResult {
 	repaired: boolean;
 	/** Human-readable detail */
 	detail: string;
+	/** Repaired task state, returned to a locked caller for persistence. */
+	repairedTasks?: TeamTaskState[];
 }
 
 const STALE_ALIVE_PID_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -106,16 +104,6 @@ function repairStaleRun(
 		return task;
 	});
 
-	// Write repaired tasks atomically
-	const tasksPath = manifest.tasksPath;
-	if (tasksPath) {
-		try {
-			writeAtomicJson(tasksPath, repairedTasks);
-		} catch (error) {
-			logInternalError("stale-reconciler.repair-tasks", error, `runId=${manifest.runId}`);
-		}
-	}
-
 	return repairedTasks;
 }
 
@@ -167,6 +155,7 @@ export function reconcileStaleRun(
 				verdict: "no_status",
 				repaired: true,
 				detail: `No PID; stale ${Math.round((now - updatedAt) / 3600_000)}h; repaired ${repaired.filter((t) => t.status === "cancelled").length} tasks`,
+				repairedTasks: repaired,
 			};
 		}
 		return {
@@ -195,5 +184,6 @@ export function reconcileStaleRun(
 		verdict: pidStatus.alive ? "pid_alive_stale" : "pid_dead",
 		repaired: true,
 		detail: `PID ${pid}: ${pidStatus.detail}; ${staleness.reason}; repaired ${repaired.filter((t) => t.status === "cancelled").length} tasks`,
+		repairedTasks: repaired,
 	};
 }

package/src/runtime/stream-preview.ts

@@ -0,0 +1,177 @@
+// ─── Streaming Preview ───────────────────────────────────────────────────────
+// Captures incremental worker output during task execution for live preview.
+// Used by the UI layer to show partial results before task completion.
+
+import type { ParsedPiUsage } from "./pi-json-output.ts";
+
+export interface ToolCallPreview {
+	toolName: string;
+	inputPreview: string;
+	startedAt: number;
+}
+
+export interface StreamPreview {
+	taskId: string;
+	runId: string;
+	/** Cumulative text output captured so far */
+	textBuffer: string;
+	/** Current tool call in progress (if any) */
+	activeToolCall: ToolCallPreview | null;
+	/** Completed tool calls count */
+	toolCallCount: number;
+	/** Current turn number (incremented per assistant message) */
+	turnCount: number;
+	/** Token usage snapshot */
+	usage: Partial<ParsedPiUsage> | null;
+	/** Wall-clock start time */
+	startedAt: number;
+	/** Last update timestamp */
+	lastUpdatedAt: number;
+	/** Whether the task has completed */
+	finished: boolean;
+}
+
+export function createStreamPreview(taskId: string, runId: string): StreamPreview {
+	const now = Date.now();
+	return {
+		taskId,
+		runId,
+		textBuffer: "",
+		activeToolCall: null,
+		toolCallCount: 0,
+		turnCount: 0,
+		usage: null,
+		startedAt: now,
+		lastUpdatedAt: now,
+		finished: false,
+	};
+}
+
+/** Max text buffer size — drop oldest content when exceeded */
+const MAX_TEXT_BUFFER = 16_384;
+/** Max tool input preview length */
+const MAX_INPUT_PREVIEW = 512;
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+	value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+
+function truncateWithEllipsis(text: string, maxLength: number): string {
+	if (text.length <= maxLength) return text;
+	return text.slice(0, maxLength - 3) + "...";
+}
+
+function extractTextFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const part of content) {
+		const obj = asRecord(part);
+		if (!obj) continue;
+		if (obj.type === "text" && typeof obj.text === "string") parts.push(obj.text);
+		else if (typeof obj.content === "string") parts.push(obj.content);
+	}
+	return parts.join("");
+}
+
+/**
+ * Feed a JSON event from Pi's stdout into the preview, updating it in place.
+ * Returns true if the preview was modified.
+ */
+export function feedJsonEvent(preview: StreamPreview, event: unknown): boolean {
+	const obj = asRecord(event);
+	if (!obj) return false;
+
+	let modified = false;
+	preview.lastUpdatedAt = Date.now();
+
+	// Detect tool calls
+	if (obj.type === "tool_call" || obj.type === "tool_use" || obj.type === "toolCall") {
+		const toolName = typeof obj.name === "string" ? obj.name : typeof obj.tool === "string" ? obj.tool : "unknown";
+		const rawInput = obj.input ?? obj.arguments ?? obj.params ?? "";
+		const inputStr = typeof rawInput === "string" ? rawInput : JSON.stringify(rawInput);
+		preview.activeToolCall = {
+			toolName,
+			inputPreview: truncateWithEllipsis(inputStr, MAX_INPUT_PREVIEW),
+			startedAt: Date.now(),
+		};
+		preview.toolCallCount++;
+		modified = true;
+	}
+
+	// Detect tool results (clear active tool call)
+	if (obj.type === "tool_result" || obj.type === "toolResult" || obj.type === "result") {
+		preview.activeToolCall = null;
+		modified = true;
+	}
+
+	// Detect assistant text output
+	const message = asRecord(obj.message);
+	if (message?.role === "assistant" || obj.role === "assistant") {
+		preview.turnCount++;
+		const text = extractTextFromContent(message?.content ?? obj.content);
+		if (text) {
+			const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + text : text;
+			preview.textBuffer = appended.length > MAX_TEXT_BUFFER ? appended.slice(appended.length - MAX_TEXT_BUFFER) : appended;
+		}
+		modified = true;
+	}
+
+	// Detect direct text/final output
+	if (typeof obj.text === "string" && obj.text.trim()) {
+		const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + obj.text : obj.text;
+		preview.textBuffer = appended.length > MAX_TEXT_BUFFER ? appended.slice(appended.length - MAX_TEXT_BUFFER) : appended;
+		modified = true;
+	}
+
+	// Detect usage
+	const rawUsage = obj.usage ?? obj.tokenUsage ?? obj.tokens ?? obj.stats;
+	if (rawUsage && typeof rawUsage === "object") {
+		const u = asRecord(rawUsage);
+		if (u) {
+			preview.usage = {
+				input: typeof u.input === "number" ? u.input : preview.usage?.input,
+				output: typeof u.output === "number" ? u.output : preview.usage?.output,
+				cacheRead: typeof u.cacheRead === "number" ? u.cacheRead : preview.usage?.cacheRead,
+				cacheWrite: typeof u.cacheWrite === "number" ? u.cacheWrite : preview.usage?.cacheWrite,
+				cost: typeof u.cost === "number" ? u.cost : preview.usage?.cost,
+				turns: typeof u.turns === "number" ? u.turns : preview.usage?.turns,
+			};
+			modified = true;
+		}
+	}
+
+	return modified;
+}
+
+/** Mark preview as finished */
+export function finishStreamPreview(preview: StreamPreview): void {
+	preview.finished = true;
+	preview.activeToolCall = null;
+	preview.lastUpdatedAt = Date.now();
+}
+
+/** Render a compact one-line status for the preview */
+export function renderPreviewStatus(preview: StreamPreview): string {
+	const elapsed = Math.round((Date.now() - preview.startedAt) / 1000);
+	const parts: string[] = [];
+
+	if (preview.finished) {
+		parts.push("✓ done");
+	} else if (preview.activeToolCall) {
+		parts.push(`⚙ ${preview.activeToolCall.toolName}`);
+	} else {
+		parts.push("⟳ thinking");
+	}
+
+	parts.push(`T${preview.turnCount}`);
+	parts.push(`${preview.toolCallCount} tools`);
+
+	if (preview.usage?.input) {
+		const inK = Math.round(preview.usage.input / 1024);
+		parts.push(`${inK}k in`);
+	}
+
+	parts.push(`${elapsed}s`);
+
+	return parts.join(" | ");
+}

package/src/runtime/subagent-manager.ts

@@ -17,6 +17,7 @@ export interface SubagentSpawnOptions {
 	prompt: string;
 	background: boolean;
 	model?: string;
+	skill?: string | string[] | false;
 	maxTurns?: number;
 	ownerSessionGeneration?: number;
 }
@@ -34,6 +35,7 @@ export interface SubagentRecord {
 	error?: string;
 	resultConsumed?: boolean;
 	model?: string;
+	skill?: string | string[] | false;
 	background: boolean;
 	ownerSessionGeneration?: number;
 	stuckNotified?: boolean;
@@ -138,6 +140,7 @@ export class SubagentManager {
 			status: options.background && this.runningBackground >= this.maxConcurrent ? "queued" : "running",
 			startedAt: Date.now(),
 			model: options.model,
+			skill: options.skill,
 			background: options.background,
 			ownerSessionGeneration: options.ownerSessionGeneration,
 		};
@@ -205,7 +208,7 @@ export class SubagentManager {
 			const record = this.records.get(id);
 			if (!record) return undefined;
 			if (record.status !== "running" && record.status !== "queued") return record;
-			if (record.promise) await record.promise;
+			if (record.promise) await record.promise.catch(() => { /* status already set to error */ });
 			else await new Promise((resolve) => setTimeout(resolve, 100));
 		}
 	}
@@ -232,7 +235,7 @@ export class SubagentManager {
 				if (result.isError) {
 					record.status = "error";
 					record.error = record.result;
-					return;
+					throw new Error(record.error);
 				}
 				if (record.runId) await this.pollRunToTerminal(options.cwd, record);
 				else record.status = "completed";
@@ -243,6 +246,7 @@ export class SubagentManager {
 				}
 				record.status = "error";
 				record.error = error instanceof Error ? error.message : String(error);
+				throw error; // H4: Propagate rejection so callers awaiting record.promise see the error
 			} finally {
 				this.cleanupRunSignal(record.id);
 				if (options.background) this.runningBackground = Math.max(0, this.runningBackground - 1);

package/src/runtime/subprocess-tool-registry.ts

@@ -0,0 +1,67 @@
+export interface SubprocessToolEvent {
+	toolName: string;
+	toolCallId: string;
+	args?: Record<string, unknown>;
+	result?: { content: Array<{ type: string; text?: string }>; details?: unknown };
+	isError?: boolean;
+}
+
+export interface SubprocessToolHandler<TData = unknown> {
+	extractData?: (event: SubprocessToolEvent) => TData | undefined;
+	shouldTerminate?: (event: SubprocessToolEvent) => boolean;
+}
+
+export interface SubprocessToolRegistry {
+	register<T>(toolName: string, handler: SubprocessToolHandler<T>): void;
+	getHandler(toolName: string): SubprocessToolHandler | undefined;
+	hasHandler(toolName: string): boolean;
+	getRegisteredTools(): string[];
+	extractAll(event: SubprocessToolEvent): Record<string, unknown>;
+	/** H3: Clear all registered handlers (for test isolation). */
+	clear(): void;
+}
+
+class SubprocessToolRegistryImpl implements SubprocessToolRegistry {
+	private readonly handlers = new Map<string, SubprocessToolHandler>();
+
+	register<T>(toolName: string, handler: SubprocessToolHandler<T>): void {
+		this.handlers.set(toolName, handler as SubprocessToolHandler);
+	}
+
+	getHandler(toolName: string): SubprocessToolHandler | undefined {
+		return this.handlers.get(toolName);
+	}
+
+	hasHandler(toolName: string): boolean {
+		return this.handlers.has(toolName);
+	}
+
+	getRegisteredTools(): string[] {
+		return [...this.handlers.keys()];
+	}
+
+	extractAll(event: SubprocessToolEvent): Record<string, unknown> {
+		const extracted: Record<string, unknown> = {};
+		for (const [toolName, handler] of this.handlers) {
+			if (handler.extractData) {
+				const data = handler.extractData(event);
+				if (data !== undefined) {
+					extracted[toolName] = data;
+				}
+			}
+		}
+		return extracted;
+	}
+
+	/** H3: Clear all registered handlers (for test isolation). */
+	clear(): void {
+		this.handlers.clear();
+	}
+}
+
+export const subprocessToolRegistry: SubprocessToolRegistry = new SubprocessToolRegistryImpl();
+
+/** H3: Reset the global singleton registry (for test isolation). */
+export function resetSubprocessToolRegistry(): void {
+	subprocessToolRegistry.clear();
+}