@gotgenes/pi-subagents 18.0.2 → 18.0.3

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [18.0.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v18.0.2...pi-subagents-v18.0.3) (2026-07-15)
+
+
+### Bug Fixes
+
+* **pi-subagents:** omit empty Default agents section header ([a29c324](https://github.com/gotgenes/pi-packages/commit/a29c32498caa4e29f0cc3292d5a6be4f4126c5f8)), closes [#594](https://github.com/gotgenes/pi-packages/issues/594)
+* **pi-subagents:** source subagent guideline copy from agent config ([a2b41a6](https://github.com/gotgenes/pi-packages/commit/a2b41a665586a271b6453b89dabec0bd94be394c)), closes [#594](https://github.com/gotgenes/pi-packages/issues/594)
+
 ## [18.0.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v18.0.1...pi-subagents-v18.0.2) (2026-07-14)
 
 

package/docs/architecture/architecture.md

@@ -120,7 +120,7 @@ classDiagram
         +run()
         +resume(prompt, signal)
         +abort(): boolean
-        +steer(message): Promise~boolean~
+        +steer(message): Promise~SteerOutcome~
         +isSessionReady(): boolean
         +getConversation(): string | undefined
         +getContextPercent(): number | null
@@ -977,7 +977,7 @@ Landed: `src/tools/get-result-report.ts` added — `AgentReport` value object pl
 
 `Release: batch "result-delivery"`
 
-#### Step 3 — `Subagent.steer` returns an outcome ([#537])
+#### ✅ Step 3 — `Subagent.steer` returns an outcome ([#537])
 
 Smell: Category C (ask-then-tell) — coordinators pre-check status before telling.
 Target files:
@@ -987,9 +987,13 @@ Target files:
 
 Outcome: zero steer status pre-checks outside `Subagent.steer`; `steer-tool.execute` cyclomatic drops below 10.
 
+Landed: `Subagent.steer` returns a discriminated `SteerOutcome` (`delivered` / `buffered` / `rejected` with the observed status) and owns the non-running rejection as its first guard; `SteerOutcome` is exported from `subagent.ts` and re-exported via `types.ts`.
+`SteerTool.execute` and `SubagentsServiceAdapter.steer` dropped their `status !== "running"` pre-checks and switch on the outcome — the adapter maps `outcome.kind !== "rejected"` to the unchanged public boolean, and the tool's delivered-path stats moved into a private `renderDelivered` helper.
+Zero steer status pre-checks remain outside `Subagent.steer`.
+
 `Release: independent`
 
-#### Step 4 — Type the model boundary ([#538])
+#### ✅ Step 4 — Type the model boundary ([#538])
 
 Smell: Category C (platform type threading) — `ModelRegistry.find/getAll/getAvailable` return `any`, forcing `any`/`unknown` model threading through `model-resolver`, `spawn-config`, `service-adapter`, and `parent-snapshot`.
 Target files:
@@ -1000,6 +1004,11 @@ Target files:
 
 Outcome: `model-resolver.ts` file-level eslint-disable removed; `service-adapter.spawn` off the HIGH CRAP list; `any` model returns eliminated from the resolver.
 
+Landed: `ModelRegistry.find/getAll/getAvailable` and `resolveModel`'s return are typed against `Model<any>` from `@earendil-works/pi-ai`; the file-level eslint-disable headers on `model-resolver.ts` (2 rules) and `spawn-config.ts` (4 rules) are both removed — running disable-header tally 5 → 3 (`agent-tool` 6, `agent-widget` 4, `index` 1 remain, all Step 5 scope).
+`resolveModel`'s fuzzy-scoring loop was extracted to a private `findBestFuzzyMatch` helper, dropping `resolveModel` off the complexity list entirely.
+`service-adapter.spawn`'s model-resolution branch was extracted to a private `resolveModelOption`, dropping `spawn` from 16 cyclomatic / CRAP 71.3 (HIGH) to 13 cyclomatic / CRAP 49.5 (moderate) — off the HIGH-CRAP list; running HIGH-CRAP tally 2 → 1 remaining (the notification renderer arrow, untouched — Step 7 scope).
+`resolveInvocationModel` gained a `registry: ModelRegistry | undefined` guard (typed error instead of a crash when a model override is requested with no registry present); the residual `unknown` thread through `ParentSnapshot.model` / `SessionContext.model` is a separate SDK-boundary gap, deferred.
+
 `Release: independent`
 
 #### Step 5 — Narrow `tui`/`theme` render interfaces ([#539])
@@ -1072,8 +1081,8 @@ Outcome: in-package clone groups 9 → ≤ 5; duplicated lines 81 → ≤ 40.
 flowchart LR
     S1["✅ Step 1 (#535)<br/>Result delivery off Subagent"] --> S2["✅ Step 2 (#536)<br/>Decompose get-result-tool"]
     S1 -.soft.-> S7["Step 7 (#541)<br/>Decompose notification renderer"]
-    S3["Step 3 (#537)<br/>Steer returns an outcome"]
-    S4["Step 4 (#538)<br/>Type the model boundary"]
+    S3["✅ Step 3 (#537)<br/>Steer returns an outcome"]
+    S4["✅ Step 4 (#538)<br/>Type the model boundary"]
     S5["Step 5 (#539)<br/>Narrow tui/theme interfaces"]
     S6["Step 6 (#540)<br/>Table-driven settings handler"]
     S8["Step 8 (#542)<br/>Full-value SubagentStateInit"] --> S9["Step 9 (#543)<br/>Consolidate test clones"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "18.0.2",
+  "version": "18.0.3",
   "type": "module",
   "exports": {
     ".": {
@@ -66,7 +66,7 @@
     "@earendil-works/pi-coding-agent": "0.79.1",
     "@earendil-works/pi-tui": "0.79.1",
     "@types/node": "^22.15.3",
-    "rollup": "^4.61.1",
+    "rollup": "^4.62.2",
     "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",

package/src/config/default-agents.ts

@@ -15,6 +15,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "general-purpose",
       displayName: "Agent",
       description: "General-purpose agent for complex, multi-step tasks",
+      toolGuideline: "- Use general-purpose for complex tasks that need file editing.",
       // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
       // inheritContext / runInBackground omitted — strategy fields, callers decide per-call.
       // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
@@ -29,6 +30,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "Explore",
       displayName: "Explore",
       description: "Fast codebase exploration agent (read-only)",
+      toolGuideline: "- Use Explore for codebase searches and code understanding.",
       builtinToolNames: READ_ONLY_TOOLS,
       model: "anthropic/claude-haiku-4-5-20251001",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
@@ -69,6 +71,7 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
       name: "Plan",
       displayName: "Plan",
       description: "Software architect for implementation planning (read-only)",
+      toolGuideline: "- Use Plan for architecture and implementation planning.",
       builtinToolNames: READ_ONLY_TOOLS,
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a software architect and planning specialist.

package/src/lifecycle/subagent.ts

@@ -35,6 +35,16 @@ export interface SubagentLifecycleObserver {
 
 export type { SubagentStatus } from "#src/lifecycle/subagent-state";
 
+/**
+ * The result of a steer attempt. `Subagent.steer` owns the non-running
+ * rejection rule and reports it here, so coordinators switch on the outcome
+ * instead of pre-checking status (tell by id, with outcomes).
+ */
+export type SteerOutcome =
+	| { kind: "delivered" }
+	| { kind: "buffered" }
+	| { kind: "rejected"; status: SubagentStatus };
+
 /**
  * The execution machinery a Subagent needs to run. A single mandatory
  * collaborator: production (SubagentManager.spawn) always supplies it, so run()
@@ -129,16 +139,21 @@ export class Subagent {
 	}
 
 	/**
-	 * Deliver or buffer a steer message.
-	 * Returns true when delivered immediately; false when buffered for later delivery.
+	 * Steer a running agent, owning the non-running rejection rule.
+	 * Returns a `rejected` outcome (with the observed status) when the agent is
+	 * not running, a `buffered` outcome when the session is not yet ready, or a
+	 * `delivered` outcome once the message reaches the session.
 	 */
-	async steer(message: string): Promise<boolean> {
+	async steer(message: string): Promise<SteerOutcome> {
+		if (this.status !== "running") {
+			return { kind: "rejected", status: this.status };
+		}
 		if (!this.subagentSession) {
 			this.queueSteer(message);
-			return false;
+			return { kind: "buffered" };
 		}
 		await this.subagentSession.steer(message);
-		return true;
+		return { kind: "delivered" };
 	}
 
 	/** Return the session conversation as formatted text, or undefined if no session. */

package/src/runtime.ts

@@ -6,6 +6,7 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
+import type { Model } from "@earendil-works/pi-ai";
 import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { ModelInfo } from "#src/tools/spawn-config";
 import type { SessionContext } from "#src/types";
@@ -54,7 +55,7 @@ export class SubagentRuntime {
   /** Extract model info from the current session context. */
   getModelInfo(): ModelInfo {
     return {
-      parentModel: this.currentCtx?.model as ModelInfo["parentModel"],
+      parentModel: this.currentCtx?.model as Model<any> | undefined,
       modelRegistry: this.currentCtx?.modelRegistry,
     };
   }

package/src/service/service-adapter.ts

@@ -5,6 +5,7 @@
  * (stripping non-serializable fields), and session gating.
  */
 
+import type { Model } from "@earendil-works/pi-ai";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
@@ -35,7 +36,7 @@ export interface ServiceRuntimeLike {
 export class SubagentsServiceAdapter implements SubagentsService {
   constructor(
     private readonly manager: SubagentManagerLike,
-    private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
+    private readonly resolveModel: (input: string, registry: ModelRegistry) => Model<any> | string,
     private readonly runtime: ServiceRuntimeLike,
   ) {}
 
@@ -44,19 +45,7 @@ export class SubagentsServiceAdapter implements SubagentsService {
       throw new Error("No active session — cannot spawn agents outside a session.");
     }
 
-    let model: unknown;
-    if (options?.model) {
-      const registry = this.runtime.currentCtx.modelRegistry;
-      if (!registry) {
-        throw new Error("No model registry available.");
-      }
-      const resolved = this.resolveModel(options.model, registry);
-      if (typeof resolved === "string") {
-        throw new Error(resolved);
-      }
-      model = resolved;
-    }
-
+    const model = this.resolveModelOption(options?.model);
     const description = options?.description ?? prompt.slice(0, 80);
     const isBackground = !(options?.foreground ?? false);
 
@@ -87,11 +76,11 @@ export class SubagentsServiceAdapter implements SubagentsService {
 
   async steer(id: string, message: string): Promise<boolean> {
     const record = this.manager.getRecord(id);
-    if (record?.status !== "running") {
+    if (!record) {
       return false;
     }
-    await record.steer(message);
-    return true;
+    const outcome = await record.steer(message);
+    return outcome.kind !== "rejected";
   }
 
   async waitForAll(): Promise<void> {
@@ -105,6 +94,20 @@ export class SubagentsServiceAdapter implements SubagentsService {
   registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
     return this.manager.registerWorkspaceProvider(provider);
   }
+
+  /** Resolve an optional model-string override against the current session's registry. */
+  private resolveModelOption(modelInput: string | undefined): Model<any> | undefined {
+    if (!modelInput) return undefined;
+    const registry = this.runtime.currentCtx?.modelRegistry;
+    if (!registry) {
+      throw new Error("No model registry available.");
+    }
+    const resolved = this.resolveModel(modelInput, registry);
+    if (typeof resolved === "string") {
+      throw new Error(resolved);
+    }
+    return resolved;
+  }
 }
 
 /**

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/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 */