@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/src/session/model-resolver.ts

@@ -1,24 +1,17 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
  */
-
-export interface ModelEntry {
-  id: string;
-  name: string;
-  provider: string;
-}
+import type { Model } from "@earendil-works/pi-ai";
 
 export interface ModelRegistry {
-  find(provider: string, modelId: string): any;
-  getAll(): any[];
-  getAvailable?(): any[];
+  find(provider: string, modelId: string): Model<any> | undefined;
+  getAll(): Model<any>[];
+  getAvailable?(): Model<any>[];
 }
 
 /** Successful model resolution — `model` is the resolved or inherited model instance. */
 export interface ModelResolutionResult {
-
-  model: any;
+  model: Model<any> | undefined;
   error?: undefined;
 }
 
@@ -42,12 +35,13 @@ export type ModelResolution = ModelResolutionResult | ModelResolutionError;
  *    - `modelFromParams` false → silent fallback to `parentModel`.
  */
 export function resolveInvocationModel(
-  parentModel: unknown,
+  parentModel: Model<any> | undefined,
   modelInput: string | undefined,
   modelFromParams: boolean,
-  registry: ModelRegistry,
+  registry: ModelRegistry | undefined,
 ): ModelResolution {
   if (!modelInput) return { model: parentModel };
+  if (!registry) return { error: "No model registry available." };
   const resolved = resolveModel(modelInput, registry);
   if (typeof resolved !== "string") return { model: resolved };
   if (modelFromParams) return { error: resolved };
@@ -62,9 +56,9 @@ export function resolveInvocationModel(
 export function resolveModel(
   input: string,
   registry: ModelRegistry,
-): any | string {
+): Model<any> | string {
   // Available models (those with auth configured)
-  const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const all = registry.getAvailable?.() ?? registry.getAll();
   const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
 
   // 1. Exact match: "provider/modelId" — only if available (has auth)
@@ -79,10 +73,27 @@ export function resolveModel(
   }
 
   // 2. Fuzzy match against available models
-  const query = input.toLowerCase();
+  const bestMatch = findBestFuzzyMatch(all, input.toLowerCase());
+  if (bestMatch) {
+    const found = registry.find(bestMatch.provider, bestMatch.id);
+    if (found) return found;
+  }
 
-  // Score each model: prefer exact id match > id contains > name contains > provider+id contains
-  let bestMatch: ModelEntry | undefined;
+  // 3. No match — list available models
+  const modelList = all
+    .map(m => `  ${m.provider}/${m.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}
+
+/**
+ * Score each candidate model — prefer exact id match > id contains > name
+ * contains > provider+id contains — and return the best match at or above
+ * the acceptance threshold (20), or undefined if nothing scores high enough.
+ */
+function findBestFuzzyMatch(all: Model<any>[], query: string): Model<any> | undefined {
+  let bestMatch: Model<any> | undefined;
   let bestScore = 0;
 
   for (const m of all) {
@@ -107,15 +118,5 @@ export function resolveModel(
     }
   }
 
-  if (bestMatch && bestScore >= 20) {
-    const found = registry.find(bestMatch.provider, bestMatch.id);
-    if (found) return found;
-  }
-
-  // 3. No match — list available models
-  const modelList = all
-    .map(m => `  ${m.provider}/${m.id}`)
-    .sort()
-    .join("\n");
-  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+  return bestScore >= 20 ? bestMatch : undefined;
 }

package/src/tools/agent-tool.ts

@@ -8,7 +8,7 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
-import { buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
+import { buildAgentGuidelines, buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
 import type { ParentSessionInfo, Subagent } from "#src/types";
@@ -42,6 +42,7 @@ export type AgentToolSettings = {
 export class AgentTool {
 	private readonly typeListText: string;
 	private readonly availableTypesText: string;
+	private readonly agentGuidelines: string[];
 
 	constructor(
 		private readonly manager: AgentToolManager,
@@ -52,6 +53,7 @@ export class AgentTool {
 	) {
 		this.typeListText = buildTypeListText(registry, agentDir);
 		this.availableTypesText = registry.getAvailableTypes().join(", ");
+		this.agentGuidelines = buildAgentGuidelines(registry);
 	}
 
 	async execute(
@@ -128,6 +130,19 @@ export class AgentTool {
 		const agentDir = this.agentDir;
 		const registry = this.registry;
 
+		const guidelines = [
+			"- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.",
+			...this.agentGuidelines,
+			"- Provide clear, detailed prompts so the agent can work autonomously.",
+			"- Subagent results are returned as text — summarize them for the user.",
+			"- Use run_in_background for work you don't need immediately. You will be notified when it completes.",
+			"- Use resume with an agent ID to continue a previous agent's work.",
+			"- Use steer_subagent to send mid-run messages to a running background agent.",
+			'- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").',
+			"- Use thinking to control extended thinking level.",
+			"- Use inherit_context if the agent needs the parent conversation history.",
+		].join("\n");
+
 		return defineTool({
 			name: "subagent" as const,
 			label: "Subagent",
@@ -140,18 +155,7 @@ Available agent types:
 ${typeListText}
 
 Guidelines:
-- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
-- Use Explore for codebase searches and code understanding.
-- Use Plan for architecture and implementation planning.
-- Use general-purpose for complex tasks that need file editing.
-- Provide clear, detailed prompts so the agent can work autonomously.
-- Subagent results are returned as text — summarize them for the user.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes.
-- Use resume with an agent ID to continue a previous agent's work.
-- Use steer_subagent to send mid-run messages to a running background agent.
-- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
-- Use thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.
+${guidelines}
 `,
 			parameters: Type.Object({
 				prompt: Type.String({

package/src/tools/get-result-report.ts

@@ -0,0 +1,60 @@
+/**
+ * get-result-report.ts — Pure report assembly for get_subagent_result.
+ *
+ * All functions are stateless: they receive an AgentReport, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by GetResultTool.execute in get-result-tool.ts. Mirrors the
+ * result-renderer.ts pattern used by the subagent tool's TUI renderer.
+ */
+
+import type { SubagentStatus } from "#src/lifecycle/subagent";
+
+/** The data a get_subagent_result report renders from — only what the formatter reads. */
+export interface AgentReport {
+	id: string;
+	displayName: string;
+	status: SubagentStatus;
+	toolUses: number;
+	/** Pre-formatted lifetime token total; "" when zero. */
+	tokens: string;
+	contextPercent: number | null;
+	compactionCount: number;
+	/** Pre-formatted duration string. */
+	duration: string;
+	description: string;
+	result: string | undefined;
+	error: string | undefined;
+	/** Present only when verbose was requested and a conversation is available. */
+	conversation?: string;
+}
+
+/** Assemble the stats parts: Tool uses / tokens? / Context? / Compactions? / Duration. */
+export function renderStatsParts(report: AgentReport): string[] {
+	const parts = [`Tool uses: ${report.toolUses}`];
+	if (report.tokens) parts.push(report.tokens);
+	if (report.contextPercent !== null) parts.push(`Context: ${Math.round(report.contextPercent)}%`);
+	if (report.compactionCount) parts.push(`Compactions: ${report.compactionCount}`);
+	parts.push(`Duration: ${report.duration}`);
+	return parts;
+}
+
+/** Select the per-status body: running note, error line, or trimmed result. */
+export function renderReportBody(report: AgentReport): string {
+	if (report.status === "running")
+		return "Agent is still running. Use wait: true or check back later.";
+	if (report.status === "error") return `Error: ${report.error}`;
+	return report.result?.trim() ?? "No output.";
+}
+
+/** Assemble the full get_subagent_result report text. */
+export function formatAgentReport(report: AgentReport): string {
+	let output =
+		`Agent: ${report.id}\n` +
+		`Type: ${report.displayName} | Status: ${report.status} | ${renderStatsParts(report).join(" | ")}\n` +
+		`Description: ${report.description}\n\n`;
+	output += renderReportBody(report);
+	if (report.conversation) {
+		output += `\n\n--- Agent Conversation ---\n${report.conversation}`;
+	}
+	return output;
+}

package/src/tools/get-result-tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import { type AgentReport, formatAgentReport } from "#src/tools/get-result-report";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Subagent } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
@@ -12,7 +13,7 @@ export interface GetResultToolManager {
 }
 
 export interface GetResultToolNotifications {
-	cancelNudge(key: string): void;
+	consume(id: string): void;
 }
 
 // ---- Class ----
@@ -37,53 +38,37 @@ export class GetResultTool {
 		}
 
 		// Wait for completion if requested.
-		// Pre-mark resultConsumed BEFORE awaiting: onComplete fires inside .then()
-		// (attached earlier at spawn time) and always runs before this await resumes.
-		// Setting the flag here prevents a redundant follow-up notification.
+		// Consume BEFORE awaiting: onComplete fires inside .then() (attached
+		// earlier at spawn time) and always runs before this await resumes.
+		// Consuming here prevents a redundant follow-up notification.
 		if (params.wait && record.status === "running" && record.promise) {
-			// Pre-mark consumed BEFORE awaiting — onComplete fires inside .then() and
-			// always runs before this await resumes. Prevents a redundant notification.
-			record.notification?.markConsumed();
-			this.notifications.cancelNudge(params.agent_id);
+			this.notifications.consume(params.agent_id);
 			await record.promise;
 		}
 
-		const displayName = getDisplayName(record.type, this.registry);
-		const duration = formatDuration(record.startedAt, record.completedAt);
-		const tokens = formatLifetimeTokens(record);
-		const contextPercent = record.getContextPercent();
-		const statsParts = [`Tool uses: ${record.toolUses}`];
-		if (tokens) statsParts.push(tokens);
-		if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
-		if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
-		statsParts.push(`Duration: ${duration}`);
-
-		let output =
-			`Agent: ${record.id}\n` +
-			`Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
-			`Description: ${record.description}\n\n`;
-
-		if (record.status === "running") {
-			output += "Agent is still running. Use wait: true or check back later.";
-		} else if (record.status === "error") {
-			output += `Error: ${record.error}`;
-		} else {
-			output += record.result?.trim() ?? "No output.";
-		}
-
-		// Mark result as consumed — suppresses the completion notification
+		// Consume the settled result — suppresses the completion notification.
 		if (record.status !== "running" && record.status !== "queued") {
-			record.notification?.markConsumed();
-			this.notifications.cancelNudge(params.agent_id);
+			this.notifications.consume(params.agent_id);
 		}
 
-		// Verbose: include full conversation
-		const conversation = params.verbose ? record.getConversation() : undefined;
-		if (conversation) {
-			output += `\n\n--- Agent Conversation ---\n${conversation}`;
-		}
+		return textResult(formatAgentReport(this.buildReport(record, params.verbose)));
+	}
 
-		return textResult(output);
+	private buildReport(record: Subagent, verbose?: boolean): AgentReport {
+		return {
+			id: record.id,
+			displayName: getDisplayName(record.type, this.registry),
+			status: record.status,
+			toolUses: record.toolUses,
+			tokens: formatLifetimeTokens(record),
+			contextPercent: record.getContextPercent(),
+			compactionCount: record.compactionCount,
+			duration: formatDuration(record.startedAt, record.completedAt),
+			description: record.description,
+			result: record.result,
+			error: record.error,
+			conversation: verbose ? record.getConversation() : undefined,
+		};
 	}
 
 	toToolDefinition() {

package/src/tools/helpers.ts

@@ -72,9 +72,8 @@ export interface TypeListRegistry extends AgentConfigLookup {
  * Extracted from index.ts so it can be called inside createAgentTool.
  */
 export function buildTypeListText(registry: TypeListRegistry, agentDir: string): string {
-  const isEnabled = (name: string) => registry.resolveAgentConfig(name).enabled !== false;
-  const defaultNames = registry.getDefaultAgentNames().filter(isEnabled);
-  const userNames = registry.getUserAgentNames().filter(isEnabled);
+  const defaultNames = registry.getDefaultAgentNames().filter((name) => isEnabledAgent(registry, name));
+  const userNames = registry.getUserAgentNames().filter((name) => isEnabledAgent(registry, name));
 
   const defaultDescs = defaultNames.map((name) => {
     const cfg = registry.resolveAgentConfig(name);
@@ -88,14 +87,31 @@ export function buildTypeListText(registry: TypeListRegistry, agentDir: string):
   });
 
   return [
-    "Default agents:",
-    ...defaultDescs,
+    ...(defaultDescs.length > 0 ? ["Default agents:", ...defaultDescs] : []),
     ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
     "",
     `Custom agents can be defined in .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
   ].join("\n");
 }
 
+/** True when an agent config is present and not explicitly disabled. */
+function isEnabledAgent(registry: AgentConfigLookup, name: string): boolean {
+  return registry.resolveAgentConfig(name).enabled !== false;
+}
+
+/**
+ * Collect the per-agent usage guidelines for the subagent tool's Guidelines: block.
+ * Sourced from each enabled default agent's `toolGuideline`, in registry order,
+ * so a disabled built-in drops its guideline automatically.
+ */
+export function buildAgentGuidelines(registry: TypeListRegistry): string[] {
+  return registry
+    .getDefaultAgentNames()
+    .filter((name) => isEnabledAgent(registry, name))
+    .map((name) => registry.resolveAgentConfig(name).toolGuideline)
+    .filter((line): line is string => line !== undefined);
+}
+
 /** Derive a short model label from a model string. */
 export function getModelLabelFromConfig(model: string): string {
   // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")

package/src/tools/spawn-config.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * spawn-config.ts — Pure config resolution for the Agent tool.
  *
@@ -11,6 +10,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentTypeRegistry } from "#src/config/agent-types";
 import { resolveAgentInvocationConfig } from "#src/config/invocation-config";
 import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
+import type { ModelRegistry } from "#src/session/model-resolver";
 import { resolveInvocationModel } from "#src/session/model-resolver";
 import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 import {
@@ -22,8 +22,8 @@ import {
 
 /** Model info extracted from the parent session context. */
 export interface ModelInfo {
-  parentModel: { id: string; name?: string } | undefined;
-  modelRegistry: unknown;
+  parentModel: Model<any> | undefined;
+  modelRegistry: ModelRegistry | undefined;
 }
 
 /** Identity: who is being spawned. */
@@ -99,7 +99,7 @@ export function resolveSpawnConfig(
     modelInfo.parentModel,
     resolvedConfig.modelInput,
     resolvedConfig.modelFromParams,
-    modelInfo.modelRegistry as any,
+    modelInfo.modelRegistry,
   );
   if (resolution.error) return { error: resolution.error };
   const model = resolution.model;
@@ -113,7 +113,7 @@ export function resolveSpawnConfig(
   const effectiveModelId = model?.id;
   const modelName =
     effectiveModelId && effectiveModelId !== parentModelId
-      ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
+      ? model.name.replace(/^Claude\s+/i, "").toLowerCase()
       : undefined;
 
   const effectiveMaxTurns = normalizeMaxTurns(

package/src/tools/steer-tool.ts

@@ -1,7 +1,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
-import type { Subagent } from "#src/types";
+import type { SteerOutcome, Subagent } from "#src/types";
 
 // ---- Deps interfaces ----
 
@@ -34,41 +34,51 @@ export class SteerTool {
 				`Agent not found: "${params.agent_id}". It may have been cleaned up.`,
 			);
 		}
-		if (record.status !== "running") {
+
+		let outcome: SteerOutcome;
+		try {
+			outcome = await record.steer(params.message);
+		} catch (err) {
 			return textResult(
-				`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
+				`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`,
 			);
 		}
-		try {
-			const delivered = await record.steer(params.message);
-			this.events.emit("subagents:steered", { id: record.id, message: params.message });
-			if (!delivered) {
+
+		switch (outcome.kind) {
+			case "rejected":
 				return textResult(
-					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+					`Agent "${params.agent_id}" is not running (status: ${outcome.status}). Cannot steer a non-running agent.`,
 				);
-			}
-			const tokens = formatLifetimeTokens(record);
-			const contextPercent = record.getContextPercent();
-			const stateParts: string[] = [];
-			if (tokens) stateParts.push(tokens);
-			stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
-			if (contextPercent !== null)
-				stateParts.push(`context ${Math.round(contextPercent)}% full`);
-			if (record.compactionCount)
-				stateParts.push(
-					`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`,
+			case "buffered":
+				this.events.emit("subagents:steered", { id: record.id, message: params.message });
+				return textResult(
+					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
 				);
-			return textResult(
-				`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
-					`Current state: ${stateParts.join(" · ")}`,
-			);
-		} catch (err) {
-			return textResult(
-				`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`,
-			);
+			case "delivered":
+				this.events.emit("subagents:steered", { id: record.id, message: params.message });
+				return this.renderDelivered(record);
 		}
 	}
 
+	/** Render the success message with live state for a delivered steer. */
+	private renderDelivered(record: Subagent) {
+		const tokens = formatLifetimeTokens(record);
+		const contextPercent = record.getContextPercent();
+		const stateParts: string[] = [];
+		if (tokens) stateParts.push(tokens);
+		stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+		if (contextPercent !== null)
+			stateParts.push(`context ${Math.round(contextPercent)}% full`);
+		if (record.compactionCount)
+			stateParts.push(
+				`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`,
+			);
+		return textResult(
+			`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+				`Current state: ${stateParts.join(" · ")}`,
+		);
+	}
+
 	toToolDefinition() {
 		return defineTool({
 			name: "steer_subagent" as const,

package/src/types.ts

@@ -7,6 +7,7 @@ import type { AgentSessionEvent, SessionContext as SdkSessionContext } from "@ea
 import type { ModelRegistry } from "#src/session/model-resolver";
 
 
+export type { SteerOutcome } from "#src/lifecycle/subagent";
 export { Subagent } from "#src/lifecycle/subagent";
 export type { AgentSessionEvent, ThinkingLevel };
 
@@ -55,6 +56,8 @@ export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   inheritContext?: boolean;
   /** Default for spawn: run in background. undefined = caller decides. */
   runInBackground?: boolean;
+  /** One-line usage guideline for the subagent tool's Guidelines: block. Omitted — no guideline line. */
+  toolGuideline?: string;
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean;
   /** false = agent is hidden from the registry */
@@ -108,7 +111,7 @@ export interface ParentSessionInfo {
 	parentSessionFile?: string;
 	/** Session ID of the parent agent (stored in the child session's parentSession header). */
 	parentSessionId?: string;
-	/** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
+	/** Tool call ID for background notification wiring. Exposed on the record via Subagent.toolCallId. */
 	toolCallId?: string;
 }
 

package/src/ui/session-navigator.ts

@@ -167,7 +167,6 @@ export class TranscriptOverlay implements Component {
     });
   }
 
-  // fallow-ignore-next-line unused-class-member
   handleInput(data: string): void {
     if (matchesKey(data, "escape") || matchesKey(data, "q")) {
       this.closed = true;
@@ -244,7 +243,6 @@ export class TranscriptOverlay implements Component {
     this.content.invalidate();
   }
 
-  // fallow-ignore-next-line unused-class-member
   dispose(): void {
     this.closed = true;
     if (this.unsubscribe) {

package/.prettierignore

@@ -1,5 +0,0 @@
-# This fork does not use Prettier — formatting is handled by Biome
-# (see biome.json and the sibling Pi-package conventions). Ignore all
-# files to prevent Prettier from being run accidentally (e.g. by an
-# agent harness with project-level write-time Prettier formatting).
-*

package/AGENTS.md

@@ -1,7 +0,0 @@
-# AGENTS.md
-
-⚠️ It looks like the agent was started from a package subdirectory.
-
-Advise the user to launch Pi from the **repository root** (`pi-packages/`) instead.
-The root provides `.pi/settings.json`, `.pi/prompts/`, and the full skill set.
-Package-specific context for this package is available via the `package-pi-subagents` skill.