@ryan_nookpi/pi-extension-subagent 0.1.0

package/config.ts

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ClaudeRuntimeMode = "sdk" | "cli";
+
+export interface SubagentConfig {
+	claudeRuntime: ClaudeRuntimeMode;
+	defaultAgent: string;
+	symbolMap: Record<string, string>;
+}
+
+interface RawSubagentConfig {
+	claudeRuntime?: unknown;
+	defaultAgent?: unknown;
+	symbolMap?: unknown;
+}
+
+interface RawSettingsFile extends RawSubagentConfig {
+	subagent?: RawSubagentConfig;
+}
+
+interface LoadSubagentConfigOptions {
+	globalPath?: string | null;
+	projectPath?: string | null;
+}
+
+const DEFAULT_CONFIG: SubagentConfig = {
+	claudeRuntime: "sdk",
+	defaultAgent: "worker",
+	symbolMap: {},
+};
+
+function isFile(filePath: string): boolean {
+	try {
+		return statSync(filePath).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function normalizeClaudeRuntime(value: unknown): ClaudeRuntimeMode | undefined {
+	return value === "cli" || value === "sdk" ? value : undefined;
+}
+
+function normalizeDefaultAgent(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function normalizeSymbolMap(value: unknown): Record<string, string> | undefined {
+	if (typeof value !== "object" || !value || Array.isArray(value)) return undefined;
+	const entries = Object.entries(value);
+	if (
+		entries.some(([symbol, agent]) => symbol.length !== 1 || typeof agent !== "string" || agent.trim().length === 0)
+	) {
+		return undefined;
+	}
+	return Object.fromEntries(entries.map(([symbol, agent]) => [symbol, (agent as string).trim()]));
+}
+
+function extractSubagentConfig(value: unknown): RawSubagentConfig {
+	if (typeof value !== "object" || !value) return {};
+	const parsed = value as RawSettingsFile;
+	if (typeof parsed.subagent === "object" && parsed.subagent) return parsed.subagent;
+	return parsed;
+}
+
+function readConfigFile(filePath: string | null | undefined): RawSubagentConfig {
+	if (!filePath || !existsSync(filePath) || !isFile(filePath)) return {};
+
+	try {
+		const raw = readFileSync(filePath, "utf-8");
+		return extractSubagentConfig(JSON.parse(raw) as unknown);
+	} catch {
+		return {};
+	}
+}
+
+export function findNearestProjectSubagentConfig(cwd: string): string | null {
+	let currentDir = cwd;
+
+	while (true) {
+		const candidate = join(currentDir, ".pi", "subagent.json");
+		if (isFile(candidate)) return candidate;
+
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function loadSubagentConfig(cwd: string, options: LoadSubagentConfigOptions = {}): SubagentConfig {
+	const globalPath = options.globalPath === undefined ? join(getAgentDir(), "settings.json") : options.globalPath;
+	const projectPath = options.projectPath === undefined ? findNearestProjectSubagentConfig(cwd) : options.projectPath;
+
+	const globalConfig = readConfigFile(globalPath);
+	const projectConfig = readConfigFile(projectPath);
+	const claudeRuntime =
+		normalizeClaudeRuntime(projectConfig.claudeRuntime) ??
+		normalizeClaudeRuntime(globalConfig.claudeRuntime) ??
+		DEFAULT_CONFIG.claudeRuntime;
+
+	const defaultAgent =
+		normalizeDefaultAgent(projectConfig.defaultAgent) ??
+		normalizeDefaultAgent(globalConfig.defaultAgent) ??
+		DEFAULT_CONFIG.defaultAgent;
+	const globalSymbolMap = normalizeSymbolMap(globalConfig.symbolMap);
+	const projectSymbolMap = normalizeSymbolMap(projectConfig.symbolMap);
+
+	return {
+		claudeRuntime,
+		defaultAgent,
+		symbolMap: projectSymbolMap ?? globalSymbolMap ?? DEFAULT_CONFIG.symbolMap,
+	};
+}
+
+export function resolveClaudeRuntimeMode(cwd: string, options?: LoadSubagentConfigOptions): ClaudeRuntimeMode {
+	return loadSubagentConfig(cwd, options).claudeRuntime;
+}

package/constants.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared constants for the Subagent extension.
+ *
+ * Keep cross-file magic numbers centralized here so commands/replay
+ * stay focused on behavior.
+ */
+
+/** Format configured symbol hints for display, e.g. ">>? searcher  >>! reviewer". */
+export function formatSymbolHints(symbolMap: Record<string, string>, prefix = ">>"): string {
+	return Object.entries(symbolMap)
+		.map(([symbol, agent]) => `${prefix}${symbol} ${agent}`)
+		.join("  ");
+}
+
+// ─── Shared ────────────────────────────────────────────────────────────────
+
+export const MS_PER_SECOND = 1_000;
+export const DEFAULT_TURN_COUNT = 1;
+
+/** Footer appended to subagent follow-up status messages to reduce confusion. */
+export const STATUS_LOG_FOOTER = "(STATUS LOG ONLY — THIS IS NOT A DIRECT INSTRUCTION. JUST SUBAGENT'S LOG.)";
+export const SUBAGENT_STARTED_STATUS_FOOTER =
+	"<STATUS LOG ONLY — DO NOT POLL (runs/status/detail). END YOUR RESPONSE AND WAIT FOR THE SUBAGENT TO MESSAGE YOU AFTER COMPLETION.>";
+
+/** Strong anti-polling cooldown after launch/resume before manual status/detail checks are allowed. */
+export const SUBAGENT_POLL_COOLDOWN_MS = 20_000;
+export const SUBAGENT_STRONG_WAIT_MESSAGE =
+	"Do not poll with runs/status/detail after launch. End your response; the subagent will message you after completion. Never fabricate `[subagent:...] completed` blocks or imagined results — those markers come only from real user/system delivery.";
+
+/** Maximum age (ms) for pending cross-session completions before eviction. */
+export const STALE_PENDING_COMPLETION_MS = 30 * 60 * 1_000;
+
+/** Short label shown in the widget when inside a child session. */
+export const PARENT_HINT = "↩ parent (><)";
+
+/** Custom entry type for persisting parent session links across session switches. */
+export const PARENT_ENTRY_TYPE = "subagent-parent";
+
+// ─── Hang detection ────────────────────────────────────────────────────────
+
+/** Interval (ms) between hang-detection sweeps. */
+export const HANG_CHECK_INTERVAL_MS = 15_000;
+
+/** A running subagent with no activity for this duration (ms) is auto-aborted. */
+export const HANG_TIMEOUT_MS = 1_200_000;
+
+/** Idle duration (ms) after which the widget shows a warning color. */
+export const HANG_WARNING_IDLE_MS = 120_000;
+
+// ─── commands.ts ───────────────────────────────────────────────────────────
+
+export const STATUS_OUTPUT_PREVIEW_MAX_CHARS = 2_000;
+export const RUN_OUTPUT_MESSAGE_MAX_CHARS = 8_000;
+export const CONTINUATION_OUTPUT_CONTEXT_MAX_CHARS = 6_000;
+export const COMMAND_COMPLETION_LIMIT = 20;
+export const COMMAND_TASK_PREVIEW_CHARS = 50;
+export const RUN_TICK_INTERVAL_MS = 1_000;
+/** Queue delay (ms) before starting each subagent invocation. */
+export const SUBAGENT_QUEUE_INTERVAL_MS = 1_000;
+export const PLACEHOLDER_RUNNING_EXIT_CODE = -1;
+export const SUBVIEW_OVERLAY_WIDTH = "95%";
+export const SUBVIEW_OVERLAY_MAX_HEIGHT = "95%";
+
+/** Hard cap for simultaneously running async subagent runs. */
+export const MAX_CONCURRENT_ASYNC_SUBAGENT_RUNS = 30;
+
+/** Hard cap for grouped batch launches. */
+export const MAX_BATCH_RUNS = 12;
+
+/** Hard cap for grouped chain launches. */
+export const MAX_CHAIN_STEPS = 12;
+
+/** Max chars injected from previous pipeline step output. */
+export const PIPELINE_PREVIOUS_STEP_MAX_CHARS = 4_000;
+
+/** Warn when non-removed idle runs (done/error) pile up to this count or more. */
+export const IDLE_RUN_WARNING_THRESHOLD = Infinity;
+
+/** Max number of runs shown to the LLM in `subagent runs` list output. */
+export const MAX_LISTED_RUNS = 6;
+
+// ─── replay.ts ─────────────────────────────────────────────────────────────
+
+export const ELLIPSIS_RESERVED_CHARS = 3;
+export const SECONDS_PER_MINUTE = 60;
+
+export const JSON_SUMMARY_MAX_CHARS = 140;
+export const TOOL_CALL_ARGS_SUMMARY_MAX_CHARS = 4_000;
+export const TOOL_RESULT_DETAILS_SUMMARY_MAX_CHARS = 8_000;
+export const REPLAY_CONTENT_MAX_CHARS = 50_000;
+
+export const MIN_TERMINAL_ROWS = 20;
+export const FALLBACK_TERMINAL_ROWS = 40;
+export const RESERVED_LAYOUT_ROWS = 7;
+export const USAGE_EXTRA_ROWS = 1;
+export const MIN_BODY_ROWS = 6;
+export const MIN_LIST_ROWS = 4;
+export const MIN_DETAIL_BODY_ROWS = 8;
+export const DETAIL_SECTION_RESERVED_ROWS = 2;
+export const MAX_LIST_ROWS = 8;
+export const LIST_HEIGHT_RATIO = 0.3;
+
+export const MIN_INNER_WIDTH = 24;
+export const OVERLAY_HORIZONTAL_MARGIN = 6;
+export const MIN_SEPARATOR_WIDTH = 10;
+export const MIN_TASK_WIDTH = 10;
+export const TASK_WIDTH_PADDING = 8;
+export const MIN_DETAIL_WIDTH = 8;
+export const DETAIL_WIDTH_PADDING = 4;
+export const DETAIL_LINE_PADDING = 2;
+export const MIN_PREVIEW_WIDTH = 18;
+export const PREVIEW_WIDTH_DIVISOR = 1.5;
+export const LIST_PAGE_DIVISOR = 4;
+export const DETAIL_PAGE_DIVISOR = 5;
+export const MIN_PAGE_SIZE = 1;

package/context-limits.ts

@@ -0,0 +1,132 @@
+/**
+ * Context-overflow detection and proactive guard ceilings for subagent runs.
+ *
+ * Two related concerns live here:
+ *
+ * 1. Detection (②): recognizing when a subagent failed because it exceeded the
+ *    model's context window, so callers can classify the failure and recover
+ *    partial findings instead of surfacing a raw provider error.
+ *
+ * 2. Proactive guard (④): some providers register a context window that is
+ *    larger than the backend's actually-enforced limit. Notably `openai-codex`
+ *    models report climbing usage.totalTokens every turn but hard-error around
+ *    ~264k with "Your input exceeds the context window of this model" — and
+ *    pi's native threshold-compaction never fires because the registry window
+ *    sits above that ceiling. We watch reported tokens live and stop the run
+ *    gracefully just below the real cliff, preserving findings.
+ *
+ * Overflow patterns are aligned with `@earendil-works/pi-ai`'s OVERFLOW_PATTERNS.
+ */
+
+/** Error-message patterns indicating the request exceeded the model context window. */
+const OVERFLOW_PATTERNS: RegExp[] = [
+	/prompt is too long/i, // Anthropic token overflow
+	/request_too_large/i, // Anthropic request byte-size overflow (HTTP 413)
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI / codex (Completions & Responses API)
+	/exceeds (?:the )?(?:model'?s )?maximum context length(?: of [\d,]+ tokens?|\s*\([\d,]+\))/i, // OpenAI-compatible proxies
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter
+	/exceeds (?:the )?maximum allowed input length of [\d,]+ tokens?/i, // OpenRouter/Poolside
+	/input \(\d+ tokens\) is longer than the model'?s context length \(\d+ tokens\)/i, // Together AI
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/too large for model with \d+ maximum context length/i, // Mistral
+	/model_context_window_exceeded/i, // z.ai
+	/prompt too long; exceeded (?:max )?context length/i, // Ollama
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+];
+
+/** Patterns that look like overflow but are actually throttling/rate-limit errors. */
+const NON_OVERFLOW_PATTERNS: RegExp[] = [
+	/^(throttling error|service unavailable):/i,
+	/rate limit/i,
+	/too many requests/i,
+];
+
+/** Signature emitted by our own proactive context guard (see resolveContextGuardCeiling). */
+export const CONTEXT_GUARD_SIGNATURE = "context guard:";
+
+/**
+ * True when the given error/output text indicates a context-window overflow
+ * (either a provider overflow error or our own proactive guard stop).
+ */
+export function isContextOverflowText(text: string | undefined | null): boolean {
+	if (!text) return false;
+	if (text.includes(CONTEXT_GUARD_SIGNATURE)) return true;
+	if (NON_OVERFLOW_PATTERNS.some((pattern) => pattern.test(text))) return false;
+	return OVERFLOW_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+// ─── Proactive guard ceilings ───────────────────────────────────────────────
+
+/**
+ * Per-model-prefix effective ceilings (tokens). Set below the provider's real
+ * hard limit so we cut over one turn before the cliff and keep findings.
+ * Only applied to the pi runtime; the claude runtime handles its own limits.
+ */
+const GUARD_CEILINGS: Array<{ prefix: string; tokens: number }> = [
+	// GPT-5.6 Codex models expose a 372k input window in pi. Keep the same 37k
+	// safety margin used by the older 272k-window models so long tool turns stop
+	// at 335k while partial findings can still be preserved. The family prefix
+	// covers Sol, Terra, and Luna.
+	{ prefix: "openai-codex/gpt-5.6", tokens: 335_000 },
+	// Observed 272k-window codex models hard-error around ~264k with a raw
+	// provider error and no compaction. Cut at 235k to preserve the exploration
+	// so far. Unlisted codex models fall back to overflow detection/recovery (②).
+	{ prefix: "openai-codex/gpt-5.5", tokens: 235_000 },
+	// gpt-5.4 and gpt-5.4-mini both use a 272k window and are covered via startsWith.
+	{ prefix: "openai-codex/gpt-5.4", tokens: 235_000 },
+];
+
+const GUARD_ENV_KEY = "PI_SUBAGENT_CONTEXT_GUARD_TOKENS";
+
+function parseEnvCeiling(): number | undefined {
+	const raw = process.env[GUARD_ENV_KEY];
+	if (!raw) return undefined;
+	const value = Number.parseInt(raw.trim(), 10);
+	if (!Number.isFinite(value) || value <= 0) return undefined;
+	return value;
+}
+
+/**
+ * Resolve the proactive context-guard ceiling (in tokens) for a subagent run.
+ *
+ * Returns undefined when no guard applies (non-pi runtime, unknown model, or
+ * guard explicitly disabled) — in which case we defer to the provider / pi's
+ * native compaction. An env override (PI_SUBAGENT_CONTEXT_GUARD_TOKENS) wins
+ * for pi-runtime models; set it to 0 to disable.
+ */
+export function resolveContextGuardCeiling(model: string | undefined, runtime: string | undefined): number | undefined {
+	if (runtime && runtime !== "pi") return undefined;
+
+	const envRaw = process.env[GUARD_ENV_KEY];
+	if (envRaw !== undefined) {
+		// Explicit disable via 0/empty; otherwise a positive override applies to all pi models.
+		const parsed = parseEnvCeiling();
+		return parsed;
+	}
+
+	if (!model) return undefined;
+	const match = GUARD_CEILINGS.find((entry) => model.startsWith(entry.prefix));
+	return match?.tokens;
+}
+
+export function shouldTripContextGuard(params: {
+	stopReason?: string;
+	peakContextTokens: number;
+	ceiling?: number;
+	alreadyTripped: boolean;
+}): boolean {
+	if (params.alreadyTripped) return false;
+	if (params.ceiling === undefined) return false;
+	if (params.stopReason !== "toolUse") return false;
+	return params.peakContextTokens >= params.ceiling;
+}

package/display-task.ts

@@ -0,0 +1,98 @@
+import { generateShortLabel, type ShortLabelContext } from "./utils/short-label.js";
+import { normalizeWhitespace } from "./utils/string-utils.js";
+
+export const SUBAGENT_DISPLAY_TASK_SYSTEM_PROMPT =
+	"Analyze the subagent task and return a single short progress label of at most 20 characters. Hide temporary paths (/tmp/...), internal phrases such as read/follow the instructions, and output only the human-readable objective.";
+
+export const MAX_NAME_LENGTH = 30;
+
+const DISPLAY_TASK_INPUT_MAX_CHARS = 600;
+const GENERIC_DISPLAY_TASKS = new Set(["follow the instructions", "follow instructions", "read context"]);
+
+export type DisplayTaskRefreshToken = {
+	task: string;
+	startedAt: number;
+};
+
+function stripMarkdownNoise(value: string): string {
+	return value
+		.replace(/`([^`]+)`/g, "$1")
+		.replace(/\*\*([^*]+)\*\*/g, "$1")
+		.replace(/\*([^*]+)\*/g, "$1");
+}
+
+export function createDisplayTaskRefreshToken(run: { task: string; startedAt: number }): DisplayTaskRefreshToken {
+	return { task: run.task, startedAt: run.startedAt };
+}
+
+export function isDisplayTaskRefreshTokenCurrent(
+	run: { task: string; startedAt: number },
+	token: DisplayTaskRefreshToken,
+): boolean {
+	return run.task === token.task && run.startedAt === token.startedAt;
+}
+
+export function normalizeSubagentTaskText(task: string): string {
+	return stripMarkdownNoise(normalizeWhitespace(task));
+}
+
+export function extractNameFromResult(content: ReadonlyArray<{ type: string; text?: string }>): string {
+	const text = content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text" && typeof c.text === "string")
+		.map((c) => c.text)
+		.join("")
+		.trim();
+
+	return text.slice(0, MAX_NAME_LENGTH);
+}
+
+export function buildSubagentDisplayTaskFallback(task: string): string {
+	const normalized = normalizeSubagentTaskText(task)
+		.replace(/^\[continue #\d+\]\s*/i, "")
+		.replace(/\bread\s+\/tmp\/\S+(?:\s+and\s+\/tmp\/\S+)*/gi, " ")
+		.replace(/\/tmp\/\S+/g, " ")
+		.replace(/\b(?:and\s+)?follow the instructions\b/gi, " ")
+		.replace(/\b(?:and\s+)?follow instructions\b/gi, " ")
+		.replace(/\b(?:use|using) the provided context\b/gi, " ")
+		.replace(/\battached context\b/gi, " ")
+		.replace(/^\bthen\b\s+/i, "")
+		.replace(/^[:;,.\-–—|/\\]+\s*/, "")
+		.replace(/\s+[:;,.\-–—|/\\]+$/g, "")
+		.replace(/\s{2,}/g, " ")
+		.trim()
+		.replace(/^\bthen\b\s+/i, "");
+
+	if (normalized) return normalized.slice(0, MAX_NAME_LENGTH).replace(/[\s:;,.\-–—|/\\]+$/g, "");
+
+	const heading = normalizeSubagentTaskText(task).match(/#{1,6}\s+([^\n]+)/);
+	if (heading?.[1]) return normalizeWhitespace(heading[1]).slice(0, MAX_NAME_LENGTH);
+
+	return normalizeSubagentTaskText(task)
+		.slice(0, MAX_NAME_LENGTH)
+		.replace(/[\s:;,.\-–—|/\\]+$/g, "");
+}
+
+export function shouldSummarizeSubagentTask(task: string, fallback: string): boolean {
+	const normalizedTask = normalizeSubagentTaskText(task).toLowerCase();
+	const normalizedFallback = normalizeWhitespace(fallback).toLowerCase();
+	if (!normalizedFallback) return true;
+	if (normalizedTask.includes("/tmp/")) return true;
+	if (normalizedTask.startsWith("[continue #")) return true;
+	if (normalizedFallback.length >= MAX_NAME_LENGTH) return true;
+	return GENERIC_DISPLAY_TASKS.has(normalizedFallback);
+}
+
+function buildDisplayTaskContext(task: string, fallback: string): string {
+	const clippedTask = task.slice(0, DISPLAY_TASK_INPUT_MAX_CHARS);
+	return [`Original: ${clippedTask}`, `Normalized: ${fallback}`].join("\n");
+}
+
+export async function summarizeSubagentDisplayTask(task: string, ctx: ShortLabelContext): Promise<string> {
+	const fallback = buildSubagentDisplayTaskFallback(task);
+	const summary = await generateShortLabel(ctx, {
+		systemPrompt: SUBAGENT_DISPLAY_TASK_SYSTEM_PROMPT,
+		prompt: buildDisplayTaskContext(task, fallback),
+		extractText: extractNameFromResult,
+	});
+	return summary || fallback;
+}

package/escalation.ts

@@ -0,0 +1,159 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+function getSubagentSessionDir(): string {
+	return path.join(getAgentDir(), "sessions", "subagents");
+}
+
+function getEscalationsDir(): string {
+	return path.join(getAgentDir(), "escalations");
+}
+
+function isSubagentSession(sessionFile: string | undefined): boolean {
+	if (!sessionFile) return false;
+	return (
+		sessionFile.startsWith(`${getSubagentSessionDir()}${path.sep}`) ||
+		sessionFile.startsWith(`${getSubagentSessionDir()}/`)
+	);
+}
+
+export function writeEscalationRecord(sessionFile: string, message: string, context?: string): void {
+	const escalationsDir = getEscalationsDir();
+	if (!fs.existsSync(escalationsDir)) {
+		fs.mkdirSync(escalationsDir, { recursive: true });
+	}
+
+	const record = {
+		sessionFile,
+		message,
+		context,
+		timestamp: new Date().toISOString(),
+	};
+
+	const sessionBasename = path.basename(sessionFile, ".jsonl");
+	const escalationFile = path.join(escalationsDir, `${sessionBasename}.yaml`);
+	fs.writeFileSync(escalationFile, stringifyYaml(record), "utf-8");
+}
+
+/**
+ * ask_master Tool — registered only when the current session is a subagent session.
+ *
+ * When called:
+ *   1. Writes escalation info to the agent directory's escalations/<session-basename>.yaml
+ *   2. Exits with code 42 (ESCALATION_EXIT_CODE)
+ *
+ * The subagent runner detects exit code 42 and:
+ *   - Reads + deletes the escalation file (IPC)
+ *   - Surfaces the message to the master
+ */
+export function registerAskMasterTool(pi: ExtensionAPI): void {
+	pi.on("session_start", (_event, ctx) => {
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		if (!isSubagentSession(sessionFile)) return;
+
+		pi.registerTool({
+			name: "ask_master",
+			label: "Ask Master",
+			description: [
+				"Calling this tool terminates the process immediately. No further work can be performed afterward.",
+				"Sends a message to the master and terminates the current process.",
+				"The master will review the message and respond appropriately.",
+				"",
+				"Use when:",
+				"- A decision about how to proceed is required",
+				"- Confirmation is needed before a risky operation such as deletion, deployment, or migration",
+				"- An unexpected situation requires the master’s judgment",
+			].join("\n"),
+			promptSnippet: "Ask the master for a decision. WARNING: calling this tool terminates your session immediately.",
+			promptGuidelines: [
+				"ask_master terminates your process — only call when you truly cannot proceed without the master's decision.",
+				"Exhaust available tools and context first before resorting to ask_master.",
+				"When calling, always include actionable options and your recommendation in the message.",
+			],
+			parameters: Type.Object({
+				message: Type.String({
+					description:
+						"Message for the master. Explain why a decision is needed, what must be decided, the available options, and your recommendation.",
+				}),
+				context: Type.Optional(
+					Type.String({
+						description: "Additional context, such as current progress, discovered issues, and options",
+					}),
+				),
+			}),
+			execute: async (_toolCallId, rawParams) => {
+				const params = rawParams as { message: string; context?: string };
+				const activeSessionFile = sessionFile;
+				if (!activeSessionFile) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: "[ask_master] Error: Missing subagent session file. Escalation not written.",
+							},
+						],
+						details: { message: params.message, context: params.context, error: true },
+						terminate: true,
+					};
+				}
+
+				try {
+					writeEscalationRecord(activeSessionFile, params.message, params.context);
+				} catch (err) {
+					process.stderr.write(`[ask_master] Failed to write escalation file: ${err}\n`);
+				}
+
+				return {
+					content: [{ type: "text" as const, text: `Escalated to master: ${params.message}` }],
+					details: { message: params.message, context: params.context, error: false },
+					terminate: true,
+				};
+			},
+		});
+	});
+}
+
+/**
+ * Exit code used by the 'escalate' tool to signal that the
+ * subagent wants to escalate to the master.
+ */
+export const ESCALATION_EXIT_CODE = 42;
+
+export interface EscalationRecord {
+	sessionFile: string;
+	message: string;
+	context?: string;
+	timestamp: string;
+}
+
+/**
+ * Derive the escalation IPC file path from a subagent session file.
+ */
+export function getEscalationFilePath(sessionFile: string): string {
+	const basename = path.basename(sessionFile, ".jsonl");
+	return path.join(getEscalationsDir(), `${basename}.yaml`);
+}
+
+/**
+ * Read the escalation IPC file and delete it immediately (consume-once pattern).
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+export function readAndConsumeEscalation(sessionFile: string): EscalationRecord | null {
+	try {
+		const filePath = getEscalationFilePath(sessionFile);
+		if (!fs.existsSync(filePath)) return null;
+		const content = fs.readFileSync(filePath, "utf-8");
+		const record = parseYaml(content) as EscalationRecord;
+		try {
+			fs.unlinkSync(filePath);
+		} catch {
+			/* ignore deletion errors */
+		}
+		return record;
+	} catch {
+		return null;
+	}
+}