@ryan_nookpi/pi-extension-subagent 0.5.1 → 0.5.3

package/activity.ts

@@ -7,6 +7,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { CommandRunState } from "./types.js";
+import { getUsedContextPercent } from "./utils/format-utils.js";
 
 export const SUBAGENT_ACTIVITY_CUSTOM_TYPE = "subagent-activity";
 export const SUBAGENT_ACTIVITY_SCHEMA_VERSION = 1;
@@ -24,6 +25,7 @@ export interface ActivitySnapshot {
 	toolCallCount: number;
 	lastLine?: string;
 	contextTokens?: number;
+	contextWindow?: number;
 }
 
 export interface ActivityPayload {
@@ -36,12 +38,15 @@ export interface ActivityPayload {
 	toolCallCount: number;
 	lastLine?: string;
 	contextTokens?: number;
+	contextWindow?: number;
+	contextPercent?: number;
 }
 
 export interface ActivityThrottleState {
 	lastEmittedAt: number;
 	lastEmittedToolName?: string;
 	lastEmittedToolCallCount?: number;
+	lastEmittedContextPercent?: number;
 }
 
 export function createActivityThrottleState(): ActivityThrottleState {
@@ -69,8 +74,8 @@ export function normalizeActivityLine(text: string | undefined): string | undefi
 /**
  * Change-driven throttle policy. Returns a payload to emit, or null.
  *
- * Emits only while the run is `running`, only when `lastToolName` or
- * `toolCallCount` changed since the last emission, and at most once per
+ * Emits only while the run is `running`, when tool metadata or the displayed
+ * context percentage changes, and at most once per
  * `ACTIVITY_MIN_INTERVAL_MS` per run. A change suppressed by the interval
  * stays pending and emits on a later evaluation.
  */
@@ -84,14 +89,18 @@ export function evaluateActivityEmission(
 	// on the run state, so a positive count is required regardless of the name.
 	if (snapshot.toolCallCount <= 0) return null;
 
+	const contextPercent = getUsedContextPercent(snapshot.contextTokens, snapshot.contextWindow);
 	const changed =
-		snapshot.lastToolName !== state.lastEmittedToolName || snapshot.toolCallCount !== state.lastEmittedToolCallCount;
+		snapshot.lastToolName !== state.lastEmittedToolName ||
+		snapshot.toolCallCount !== state.lastEmittedToolCallCount ||
+		contextPercent !== state.lastEmittedContextPercent;
 	if (!changed) return null;
 	if (state.lastEmittedAt !== 0 && now - state.lastEmittedAt < ACTIVITY_MIN_INTERVAL_MS) return null;
 
 	state.lastEmittedAt = now;
 	state.lastEmittedToolName = snapshot.lastToolName;
 	state.lastEmittedToolCallCount = snapshot.toolCallCount;
+	state.lastEmittedContextPercent = contextPercent;
 
 	const payload: ActivityPayload = {
 		runId: snapshot.runId,
@@ -105,10 +114,12 @@ export function evaluateActivityEmission(
 	const lastLine = normalizeActivityLine(snapshot.lastLine);
 	if (lastLine) payload.lastLine = lastLine;
 	if (snapshot.contextTokens != null && snapshot.contextTokens > 0) payload.contextTokens = snapshot.contextTokens;
+	if (snapshot.contextWindow != null && snapshot.contextWindow > 0) payload.contextWindow = snapshot.contextWindow;
+	if (contextPercent !== undefined) payload.contextPercent = contextPercent;
 	return payload;
 }
 
-export function snapshotFromRunState(runState: CommandRunState): ActivitySnapshot {
+export function snapshotFromRunState(runState: CommandRunState, contextWindow?: number): ActivitySnapshot {
 	return {
 		status: runState.status,
 		runId: runState.id,
@@ -120,6 +131,7 @@ export function snapshotFromRunState(runState: CommandRunState): ActivitySnapsho
 		toolCallCount: runState.toolCalls,
 		lastLine: runState.lastLine,
 		contextTokens: runState.usage?.contextTokens,
+		contextWindow,
 	};
 }
 
@@ -130,11 +142,16 @@ export function snapshotFromRunState(runState: CommandRunState): ActivitySnapsho
 export function createRunActivityRecorder(
 	pi: Pick<ExtensionAPI, "appendEntry">,
 	runState: CommandRunState,
+	resolveContextWindow?: (model?: string) => number | undefined,
 ): () => void {
 	const throttleState = createActivityThrottleState();
 	return () => {
 		try {
-			const payload = evaluateActivityEmission(throttleState, snapshotFromRunState(runState), Date.now());
+			const payload = evaluateActivityEmission(
+				throttleState,
+				snapshotFromRunState(runState, resolveContextWindow?.(runState.model)),
+				Date.now(),
+			);
 			if (!payload) return;
 			pi.appendEntry(SUBAGENT_ACTIVITY_CUSTOM_TYPE, {
 				schemaVersion: SUBAGENT_ACTIVITY_SCHEMA_VERSION,

package/agents.ts

@@ -21,6 +21,10 @@ export interface AgentConfig {
 	name: string;
 	description: string;
 	tools?: string[];
+	/** Whether the tools field was explicitly present. Explicit [] disables all tools. */
+	toolsConfigured?: boolean;
+	/** Discovery-time validation failure. Invalid higher-priority definitions still mask lower-priority agents. */
+	configurationError?: string;
 	model?: string;
 	thinking?: AgentThinkingLevel;
 	systemPrompt: string;
@@ -145,7 +149,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project", options: Loa
 			if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
 			if (!frontmatter.name || !frontmatter.description) continue;
 
-			const tools = normalizeTools(frontmatter.tools, format);
+			const toolsConfigured = Object.hasOwn(frontmatter, "tools");
+			let tools: string[] | undefined;
+			let configurationError: string | undefined;
+			try {
+				tools = toolsConfigured ? normalizeTools(frontmatter.tools, format) : undefined;
+			} catch (error) {
+				configurationError = `${filePath}: ${error instanceof Error ? error.message : String(error)}`;
+			}
 			const model = normalizeModel(typeof frontmatter.model === "string" ? frontmatter.model : undefined, format);
 			const thinking = normalizeThinkingLevel(
 				typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
@@ -156,6 +167,8 @@ function loadAgentsFromDir(dir: string, source: "user" | "project", options: Loa
 				name: frontmatter.name,
 				description: frontmatter.description,
 				tools,
+				toolsConfigured,
+				configurationError,
 				model,
 				thinking,
 				systemPrompt: attachCommonSubagentRule(body, runtime),

package/claude-args.ts

@@ -5,6 +5,7 @@ import { mapPiToolsToClaude } from "./utils/agent-utils.js";
 export interface ClaudeArgsConfig {
 	prompt: string;
 	tools: string[];
+	toolsConfigured?: boolean;
 	model?: string;
 	thinking?: string;
 	resumeSessionId?: string;
@@ -63,7 +64,7 @@ export function buildClaudeArgs(config: ClaudeArgsConfig): string[] {
 
 	const claudeTools = mapPiToolsToClaude(config.tools);
 
-	if (claudeTools.length > 0) {
+	if (config.toolsConfigured || claudeTools.length > 0) {
 		args.push("--tools", claudeTools.join(","));
 		args.push("--allowedTools", claudeTools.join(","));
 	}

package/claude-sdk-runner.ts

@@ -31,8 +31,12 @@ function normalizeTaskForSubagentPrompt(task: string): string {
 	return task;
 }
 
-function resolveClaudeSdkBuiltInTools(requestedTools?: string[]): string[] | undefined {
-	if (!requestedTools || requestedTools.length === 0) return undefined;
+function resolveClaudeSdkBuiltInTools(
+	requestedTools: string[] | undefined,
+	toolsConfigured: boolean,
+): string[] | undefined {
+	if (!toolsConfigured) return undefined;
+	if (!requestedTools || requestedTools.length === 0) return [];
 	return mapPiToolsToClaude(requestedTools);
 }
 
@@ -74,7 +78,7 @@ export async function runClaudeAgentViaSdk(
 
 	let enabledTools: string[] | undefined;
 	try {
-		enabledTools = resolveClaudeSdkBuiltInTools(agent.tools);
+		enabledTools = resolveClaudeSdkBuiltInTools(agent.tools, agent.toolsConfigured ?? agent.tools !== undefined);
 	} catch (error: any) {
 		return {
 			agent: agent.name,
@@ -140,7 +144,7 @@ export async function runClaudeAgentViaSdk(
 				settingSources: [],
 				includePartialMessages: true,
 				persistSession: true,
-				...(enabledTools ? { tools: enabledTools, allowedTools: enabledTools } : {}),
+				...(enabledTools !== undefined ? { tools: enabledTools, allowedTools: enabledTools } : {}),
 				resume: resumeSessionId,
 				stderr: (data) => {
 					stderrBuf += data;

package/commands.ts

@@ -35,7 +35,14 @@ import {
 	shouldSummarizeSubagentTask,
 	summarizeSubagentDisplayTask,
 } from "./display-task.js";
-import { AGENT_NAME_PALETTE, agentBgIndex, formatUsageStats, truncateLines, truncatePlainToWidth } from "./format.js";
+import {
+	AGENT_NAME_PALETTE,
+	agentBgIndex,
+	formatUsageStats,
+	resolveContextWindow,
+	truncateLines,
+	truncatePlainToWidth,
+} from "./format.js";
 import {
 	clearPendingGroupCompletion,
 	consumePendingGroupCompletionsForSession,
@@ -962,9 +969,15 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			const lines = agents.map((agent) => {
 				const model = agent.model ?? "(inherit current model)";
 				const thinking = agent.thinking ?? "(inherit current thinking)";
-				const tools = agent.tools && agent.tools.length > 0 ? agent.tools.join(",") : "default";
+				const tools =
+					(agent.toolsConfigured ?? agent.tools !== undefined)
+						? agent.tools?.length
+							? agent.tools.join(",")
+							: "none"
+						: "default";
 				const description = agent.description ? ` · ${agent.description}` : "";
-				return `${agent.name} [${agent.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}`;
+				const invalid = agent.configurationError ? ` · INVALID: ${agent.configurationError}` : "";
+				return `${agent.name} [${agent.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}${invalid}`;
 			});
 
 			return {
@@ -1223,6 +1236,15 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 				taskForAgent = taskForDisplay;
 			}
 
+			const selectedConfig = agents.find((agent) => agent.name === selectedAgent);
+			if (selectedConfig?.configurationError) {
+				ctx.ui.notify(
+					`Invalid agent configuration for "${selectedAgent}": ${selectedConfig.configurationError}`,
+					"error",
+				);
+				return;
+			}
+
 			let runId: number;
 			let runState: CommandRunState;
 
@@ -1402,7 +1424,9 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			}, RUN_TICK_INTERVAL_MS);
 
 			let claudeCheckpointSent = !!runState.claudeSessionId;
-			const recordActivity = hiddenFromMain ? () => {} : createRunActivityRecorder(pi, runState);
+			const recordActivity = hiddenFromMain
+				? () => {}
+				: createRunActivityRecorder(pi, runState, (model) => resolveContextWindow(ctx, model));
 			void (async () => {
 				try {
 					const { result, retryCount } = await invokeWithAutoRetry({
@@ -1662,14 +1686,16 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			if (starterPackNotice) ctx.ui.notify(starterPackNotice, "info");
 
 			const lines = agents.map((a) => {
-				const tools = a.tools?.join(",") ?? "default";
+				const tools =
+					(a.toolsConfigured ?? a.tools !== undefined) ? (a.tools?.length ? a.tools.join(",") : "none") : "default";
 				const model = a.model ?? "(inherit current model)";
 				const thinking = a.thinking ?? "(inherit current thinking)";
 				const description = a.description ? ` · ${a.description}` : "";
+				const invalid = a.configurationError ? ` · INVALID: ${a.configurationError}` : "";
 				const colorCode = AGENT_NAME_PALETTE[agentBgIndex(a.name)];
 				const coloredName = `\x1b[38;5;${colorCode}m${a.name}\x1b[39m`;
 				return truncateText(
-					`${coloredName} [${a.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}`,
+					`${coloredName} [${a.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}${invalid}`,
 					220,
 				);
 			});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {

package/runner.ts

@@ -82,6 +82,12 @@ function appendStderrDiagnostic(result: SingleResult, message: string): void {
 	result.stderr = result.stderr ? `${result.stderr.trimEnd()}\n${line}\n` : `${line}\n`;
 }
 
+function normalizeChildExitCode(code: number | null, signal: NodeJS.Signals | null, fallbackCode = 0): number {
+	if (code !== null) return code;
+	if (signal !== null) return 1;
+	return fallbackCode;
+}
+
 /**
  * Prevent tasks starting with `/` from being treated as slash commands
  * inside the spawned pi process.
@@ -225,6 +231,19 @@ export async function runSingleAgent(
 		};
 	}
 
+	if (agent.configurationError) {
+		return {
+			agent: agent.name,
+			agentSource: agent.source,
+			task,
+			exitCode: 1,
+			messages: [],
+			stderr: `Invalid agent configuration: ${agent.configurationError}`,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			step,
+		};
+	}
+
 	if (agent.runtime === "claude") {
 		if (resolveClaudeRuntimeMode(defaultCwd) === "sdk") {
 			const { runClaudeAgentViaSdk } = await import("./claude-sdk-runner.js");
@@ -364,6 +383,7 @@ async function runClaudeAgent(
 		const args = buildClaudeArgs({
 			prompt: normalizeTaskForSubagentPrompt(task),
 			tools: agent.tools ?? [],
+			toolsConfigured: agent.toolsConfigured ?? agent.tools !== undefined,
 			model: agent.model,
 			thinking: agent.thinking,
 			resumeSessionId: resumeId,
@@ -545,7 +565,7 @@ async function runClaudeAgent(
 
 			proc.on("exit", (code, terminationSignal) => {
 				procExited = true;
-				lastExitCode = code ?? 0;
+				lastExitCode = normalizeChildExitCode(code, terminationSignal, lastExitCode);
 				lastProcessSignal = terminationSignal;
 				diagnose({ event: "exit", childPid: proc.pid, code, signal: terminationSignal });
 				if (streamState.resultReceived) {
@@ -553,6 +573,9 @@ async function runClaudeAgent(
 					resolveOnce(0);
 					return;
 				}
+				if (terminationSignal && !settled && !wasAborted) {
+					stderrBuf += `[runner] process terminated by signal ${terminationSignal}\n`;
+				}
 				exitFallbackTimer = setTimeout(() => {
 					settleReason = "exit_fallback_timeout";
 					resolveOnce(lastExitCode);
@@ -565,7 +588,7 @@ async function runClaudeAgent(
 				diagnose({ event: "close", childPid: proc.pid, code, signal: terminationSignal });
 				if (!settled) {
 					settleReason = "close";
-					resolveOnce(streamState.resultReceived ? 0 : (code ?? lastExitCode ?? 0));
+					resolveOnce(streamState.resultReceived ? 0 : normalizeChildExitCode(code, lastProcessSignal, lastExitCode));
 				}
 			});
 
@@ -640,7 +663,8 @@ async function runPiAgent(
 	else args.push("--no-session");
 	if (agent.model) args.push("--model", agent.model);
 	if (agent.thinking) args.push("--thinking", agent.thinking);
-	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+	if ((agent.toolsConfigured ?? agent.tools !== undefined) && agent.tools?.length === 0) args.push("--no-tools");
+	else if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
 
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
@@ -1066,9 +1090,12 @@ async function runPiAgent(
 
 			proc.on("exit", (code, terminationSignal) => {
 				procExited = true;
-				lastExitCode = code ?? 0;
+				lastExitCode = normalizeChildExitCode(code, terminationSignal, lastExitCode);
 				lastProcessSignal = terminationSignal;
 				diagnose({ event: "exit", childPid: proc.pid, code, signal: terminationSignal });
+				if (terminationSignal && !settled && !wasAborted) {
+					appendStderrDiagnostic(currentResult, `process terminated by signal ${terminationSignal}`);
+				}
 				// In rare cases stdout/stderr pipes may stay open after process exit.
 				// Use a short fallback so runs cannot stay "running" forever.
 				exitFallbackTimer = setTimeout(() => {
@@ -1082,7 +1109,7 @@ async function runPiAgent(
 				lastProcessSignal = terminationSignal ?? lastProcessSignal;
 				diagnose({ event: "close", childPid: proc.pid, code, signal: terminationSignal });
 				settleReason = "close";
-				resolveOnce(code ?? lastExitCode ?? 0);
+				resolveOnce(normalizeChildExitCode(code, lastProcessSignal, lastExitCode));
 			});
 
 			proc.on("error", (error) => {

package/tool-execute.ts

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createRunActivityRecorder } from "./activity.js";
-import { discoverAgents } from "./agents.js";
+import { type AgentConfig, discoverAgents } from "./agents.js";
 import { parseSubagentToolCommand, SUBAGENT_CLI_HELP_TEXT } from "./cli.js";
 import {
 	DEFAULT_TURN_COUNT,
@@ -313,8 +313,15 @@ export function diagnoseResultFailure(result: SingleResult): ResultFailureDiagno
 			};
 		}
 	}
-	if (result.exitCode !== 0)
-		return { failed: true, errorClass, reason: `Subagent process exited with code ${result.exitCode}.` };
+	if (result.exitCode !== 0) {
+		const detail = (result.errorMessage || result.stderr || "").trim();
+		const detailPreview = detail ? truncateLines(detail, 4).slice(0, STATUS_OUTPUT_PREVIEW_MAX_CHARS).trimEnd() : "";
+		return {
+			failed: true,
+			errorClass,
+			reason: `Subagent process exited with code ${result.exitCode}.${detailPreview ? ` Cause: ${detailPreview}` : ""}`,
+		};
+	}
 	if (result.stopReason === "error")
 		return { failed: true, errorClass, reason: result.errorMessage || "Subagent reported stopReason=error." };
 	if (result.stopReason === "aborted")
@@ -810,9 +817,15 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 			const lines = agents.map((agent) => {
 				const model = agent.model ?? "(inherit current model)";
 				const thinking = agent.thinking ?? "(inherit current thinking)";
-				const tools = agent.tools && agent.tools.length > 0 ? agent.tools.join(",") : "default";
+				const tools =
+					(agent.toolsConfigured ?? agent.tools !== undefined)
+						? agent.tools?.length
+							? agent.tools.join(",")
+							: "none"
+						: "default";
 				const description = agent.description ? ` · ${agent.description}` : "";
-				return `${agent.name} [${agent.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}`;
+				const invalid = agent.configurationError ? ` · INVALID: ${agent.configurationError}` : "";
+				return `${agent.name} [${agent.source}] · model: ${model} · thinking: ${thinking} · tools: ${tools}${description}${invalid}`;
 			});
 
 			return {
@@ -902,6 +915,24 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 					isError: true,
 				};
 			}
+
+			const invalidAgents = [...new Set(requestedNames)]
+				.map((name) => agents.find((agent) => agent.name === name))
+				.filter((agent): agent is AgentConfig => Boolean(agent?.configurationError));
+			if (invalidAgents.length > 0) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `❌ Invalid agent configuration:\n${invalidAgents
+								.map((agent) => `- ${agent.name}: ${agent.configurationError}`)
+								.join("\n")}`,
+						},
+					],
+					details: makeDetails(),
+					isError: true,
+				};
+			}
 		}
 
 		if (asyncAction === "list") {
@@ -1319,7 +1350,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 
 		function launchRunInBackground(runState: CommandRunState, taskForAgent: string): Promise<FinalizedRun> {
 			let claudeCheckpointSent = !!runState.claudeSessionId;
-			const recordActivity = createRunActivityRecorder(pi, runState);
+			const recordActivity = createRunActivityRecorder(pi, runState, (model) => resolveContextWindow(ctx, model));
 			return enqueueSubagentInvocation(() =>
 				runSingleAgent(
 					ctx.cwd,

package/utils/agent-utils.ts

@@ -89,20 +89,38 @@ export const CLAUDE_MODEL_ALIAS_MAP: Record<string, string> = {
  * For "claude" format, maps Claude tool names to pi equivalents.
  */
 export function normalizeTools(rawTools: unknown, format: "pi" | "claude"): string[] | undefined {
-	const parsed = (Array.isArray(rawTools) ? rawTools : typeof rawTools === "string" ? rawTools.split(",") : [])
-		.filter((tool): tool is string => typeof tool === "string")
-		.map((tool) => tool.trim())
-		.filter(Boolean);
+	if (rawTools === undefined) return undefined;
 
-	if (parsed.length === 0) return undefined;
-	if (format === "pi") return parsed;
+	let parsed: string[];
+	if (Array.isArray(rawTools)) {
+		if (rawTools.some((tool) => typeof tool !== "string" || tool.trim().length === 0)) {
+			throw new Error("Explicit tools must contain only non-empty strings.");
+		}
+		parsed = rawTools.map((tool) => (tool as string).trim());
+	} else if (typeof rawTools === "string") {
+		parsed = rawTools
+			.split(",")
+			.map((tool) => tool.trim())
+			.filter(Boolean);
+		if (parsed.length === 0) throw new Error("Explicit tools must not be an empty string.");
+	} else {
+		throw new Error("Explicit tools must be a comma-separated string or an array of strings.");
+	}
 
-	const mapped = parsed
-		.map((tool) => CLAUDE_TOOL_MAP[tool.toLowerCase()] ?? undefined)
-		.filter((tool): tool is string => Boolean(tool));
+	if (format === "pi") return Array.from(new Set(parsed));
 
-	if (mapped.length === 0) return undefined;
-	return Array.from(new Set(mapped));
+	const unsupported = parsed.filter((tool) => !CLAUDE_TOOL_MAP[tool.toLowerCase()]);
+	if (unsupported.length > 0) {
+		throw new Error(
+			`Unsupported Claude tool${unsupported.length > 1 ? "s" : ""}: ${unsupported.join(", ")}. Supported tools: ${Object.keys(
+				CLAUDE_TOOL_MAP,
+			)
+				.filter((tool) => CLAUDE_TOOL_MAP[tool])
+				.join(", ")}`,
+		);
+	}
+
+	return Array.from(new Set(parsed.map((tool) => CLAUDE_TOOL_MAP[tool.toLowerCase()] as string)));
 }
 
 /**

package/utils/short-label.ts

@@ -8,7 +8,7 @@ type SummaryResult = Awaited<ReturnType<typeof completeSimple>>;
 type AuthResult = {
 	ok: boolean;
 	apiKey?: string;
-	headers?: Record<string, string>;
+	headers?: Record<string, string | null>;
 };
 
 export type ShortLabelContext = {