@tintinweb/pi-subagents 0.4.11 → 0.5.1

package/CHANGELOG.md

@@ -5,22 +5,37 @@ 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).
 
-## [0.4.11] - 2026-03-18
+## [Unreleased]
 
-### Fixed
-- **Stale dist in published package** — added `prepublishOnly` hook to build fresh `dist/` on every `npm publish`.
-
-## [0.4.10] - 2026-03-18
+## [0.5.1] - 2026-03-24
 
 ### Changed
-- **Default max turns is now unlimited** — subagents no longer have a 50-turn default cap. The default is unlimited (no turn limit), matching Claude Code's main loop behavior. Users can still set explicit limits per-agent via `max_turns` frontmatter or the Agent tool parameter, or globally via `/agents` → Settings (`0` = unlimited).
-- **Live turn counter** — all agents now show a live turn count in the widget, inline result, and completion notification. With a turn limit: `⟳5≤30` (5 of 30 turns). Without: `⟳5`. Updates in real time as turns progress.
+- **Agent config is authoritative** — frontmatter values for `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, and `isolation` now take precedence over `Agent` tool-call parameters. Tool-call params only fill fields the agent config leaves unspecified.
+- **`join_mode` is now a global setting only** — removed the per-call `join_mode` parameter from the `Agent` tool. Join behavior is configured via `/agents` → Settings → Join mode.
+- **`max_turns: 0` means unlimited** — agent files can now explicitly set `max_turns: 0` to lock unlimited turns. Previously `0` was silently clamped to `1`.
+
+### Fixed
+- **Final subagent text preserved from non-streaming providers** — agents using providers that return the final message without streaming `text_delta` events no longer return empty results. Falls back to extracting text from the completed session history.
+- **`effectiveMaxTurns` passed to spawn calls** — previously `params.max_turns` was passed raw to both foreground and background spawn, bypassing the agent config entirely.
+
+## [0.5.0] - 2026-03-22
 
 ### Added
+- **RPC stop handler** — new `subagents:rpc:stop` event bus RPC allows other extensions to stop running subagents by agent ID. Returns structured error ("Agent not found") on failure.
+- **`abort` in `SpawnCapable` interface** — cross-extension RPC consumers can now stop agents, not just spawn them.
+- **Live turn counter** — all agents now show a live turn count in the widget, inline result, and completion notification. With a turn limit: `⟳5≤30` (5 of 30 turns). Without: `⟳5`. Updates in real time as turns progress via `onTurnEnd` callback.
 - **Biome linting** — added [Biome](https://biomejs.dev/) for correctness linting (unused imports, suspicious patterns). Style rules disabled. Run `npm run lint` to check, `npm run lint:fix` to auto-fix.
 - **CI workflow** — GitHub Actions runs lint, typecheck, and tests on push to master and PRs.
+- **Auto-trigger parent turn on background completion** — background agent completion notifications now use `triggerTurn: true`, automatically prompting the parent agent to process results instead of waiting for user input.
+
+### Changed
+- **Standardized RPC envelope** — cross-extension RPC handlers (`ping`, `spawn`, `stop`) now use a `handleRpc` wrapper that emits structured envelopes (`{ success: true, data }` / `{ success: false, error }`), matching pi-mono's `RpcResponse` convention.
+- **Protocol versioning via ping** — ping reply now includes `{ version: PROTOCOL_VERSION }` (currently v2). Callers can detect version mismatches and warn users to update.
+- **Default max turns is now unlimited** — subagents no longer have a 50-turn default cap. The default is unlimited (no turn limit), matching Claude Code's main loop behavior. Users can still set explicit limits per-agent via `max_turns` frontmatter or the Agent tool parameter, or globally via `/agents` → Settings (`0` = unlimited).
+- **Stale dist in published package** — added `prepublishOnly` hook to build fresh `dist/` on every `npm publish`.
 
 ### Fixed
+- **Tool name display** — `getAgentConversation` now reads `ToolCall.name` (the correct property) instead of `toolName`, resolving `[Tool: unknown]` in conversation viewer and verbose output.
 - **Env test CI failure** — `detectEnv` test assumed a branch name exists, but CI checks out detached HEAD. Split into separate tests for repo detection and branch detection with a controlled temp repo.
 
 ## [0.4.9] - 2026-03-18
@@ -325,6 +340,7 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.5.0]: https://github.com/tintinweb/pi-subagents/compare/v0.4.9...v0.5.0
 [0.4.9]: https://github.com/tintinweb/pi-subagents/compare/v0.4.8...v0.4.9
 [0.4.8]: https://github.com/tintinweb/pi-subagents/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/tintinweb/pi-subagents/compare/v0.4.6...v0.4.7

package/README.md

@@ -29,7 +29,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
-- **Cross-extension RPC** — other pi extensions can spawn subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`). Emits `subagents:ready` on load
+- **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
 
 ## Install
 
@@ -170,7 +170,7 @@ All fields are optional — sensible defaults for everything.
 | `isolated` | `false` | No extension/MCP tools, only built-in |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
-Frontmatter sets defaults. Explicit `Agent` parameters always override them.
+Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent. `Agent` tool parameters only fill fields the agent config leaves unspecified.
 
 ## Tools
 
@@ -191,7 +191,6 @@ Launch a sub-agent.
 | `isolated` | boolean | no | No extension/MCP tools |
 | `isolation` | `"worktree"` | no | Run in an isolated git worktree |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |
-| `join_mode` | `"async"` \| `"group"` | no | Override join strategy for background completion notifications (default: smart) |
 
 ### `get_subagent_result`
 
@@ -260,7 +259,7 @@ Foreground agents bypass the queue — they block the parent anyway.
 
 ## Join Strategies
 
-When background agents complete, they notify the main agent. The **join mode** controls how these notifications are delivered:
+When background agents complete, they notify the main agent. The **join mode** controls how these notifications are delivered. It applies only to background agents.
 
 | Mode | Behavior |
 |------|----------|
@@ -271,8 +270,7 @@ When background agents complete, they notify the main agent. The **join mode** c
 **Timeout behavior:** When agents are grouped, a 30-second timeout starts after the first agent completes. If not all agents finish in time, a partial notification is sent with completed results and remaining agents continue with a shorter 15-second re-batch window for stragglers.
 
 **Configuration:**
-- Per-call: `Agent({ ..., join_mode: "async" })` overrides for that agent
-- Global default: `/agents` → Settings → Join mode
+- Configure join mode in `/agents` → Settings → Join mode
 
 ## Events
 
@@ -289,7 +287,9 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 
 ## Cross-Extension RPC
 
-Other pi extensions can spawn subagents programmatically via the `pi.events` event bus, without importing this package directly.
+Other pi extensions can spawn and stop subagents programmatically via the `pi.events` event bus, without importing this package directly.
+
+All RPC replies use a standardized envelope: `{ success: true, data?: T }` on success, `{ success: false, error: string }` on failure.
 
 ### Discovery
 
@@ -297,19 +297,19 @@ Listen for `subagents:ready` to know when RPC handlers are available:
 
 ```typescript
 pi.events.on("subagents:ready", () => {
-  // RPC handlers are registered — safe to call ping/spawn
+  // RPC handlers are registered — safe to call ping/spawn/stop
 });
 ```
 
 ### Ping
 
-Check if the subagents extension is loaded:
+Check if the subagents extension is loaded and get the protocol version:
 
 ```typescript
 const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, () => {
+const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
   unsub();
-  // Extension is alive
+  if (reply.success) console.log("Protocol version:", reply.data.version);
 });
 pi.events.emit("subagents:rpc:ping", { requestId });
 ```
@@ -322,10 +322,10 @@ Spawn a subagent and receive its ID:
 const requestId = crypto.randomUUID();
 const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
   unsub();
-  if (reply.error) {
+  if (!reply.success) {
     console.error("Spawn failed:", reply.error);
   } else {
-    console.log("Agent ID:", reply.id);
+    console.log("Agent ID:", reply.data.id);
   }
 });
 pi.events.emit("subagents:rpc:spawn", {
@@ -336,6 +336,19 @@ pi.events.emit("subagents:rpc:spawn", {
 });
 ```
 
+### Stop
+
+Stop a running agent by ID:
+
+```typescript
+const requestId = crypto.randomUUID();
+const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
+  unsub();
+  if (!reply.success) console.error("Stop failed:", reply.error);
+});
+pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
+```
+
 Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
 
 ## Persistent Agent Memory

package/dist/agent-runner.d.ts

@@ -5,9 +5,11 @@ import type { Model } from "@mariozechner/pi-ai";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { type AgentSession, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { SubagentType, ThinkingLevel } from "./types.js";
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export declare function normalizeMaxTurns(n: number | undefined): number | undefined;
 /** Get the default max turns value. undefined = unlimited. */
 export declare function getDefaultMaxTurns(): number | undefined;
-/** Set the default max turns value. undefined = unlimited, otherwise minimum 1. */
+/** Set the default max turns value. undefined or 0 = unlimited, otherwise minimum 1. */
 export declare function setDefaultMaxTurns(n: number | undefined): void;
 /** Get the grace turns value. */
 export declare function getGraceTurns(): number;

package/dist/agent-runner.js

@@ -12,10 +12,16 @@ import { preloadSkills } from "./skill-loader.js";
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns;
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n) {
+    if (n == null || n === 0)
+        return undefined;
+    return Math.max(1, n);
+}
 /** Get the default max turns value. undefined = unlimited. */
 export function getDefaultMaxTurns() { return defaultMaxTurns; }
-/** Set the default max turns value. undefined = unlimited, otherwise minimum 1. */
-export function setDefaultMaxTurns(n) { defaultMaxTurns = n != null ? Math.max(1, n) : undefined; }
+/** Set the default max turns value. undefined or 0 = unlimited, otherwise minimum 1. */
+export function setDefaultMaxTurns(n) { defaultMaxTurns = normalizeMaxTurns(n); }
 /** Additional turns allowed after the soft limit steer message. */
 let graceTurns = 5;
 /** Get the grace turns value. */
@@ -61,6 +67,18 @@ function collectResponseText(session) {
     });
     return { getText: () => text, unsubscribe };
 }
+/** Get the last assistant text from the completed session history. */
+function getLastAssistantText(session) {
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const msg = session.messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        const text = extractText(msg.content).trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
 /**
  * Wire an AbortSignal to abort a session.
  * Returns a cleanup function to remove the listener.
@@ -198,7 +216,7 @@ export async function runAgent(ctx, type, prompt, options) {
     options.onSessionCreated?.(session);
     // Track turns for graceful max_turns enforcement
     let turnCount = 0;
-    const maxTurns = options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns;
+    const maxTurns = normalizeMaxTurns(options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns);
     let softLimitReached = false;
     let aborted = false;
     let currentMessageText = "";
@@ -249,7 +267,8 @@ export async function runAgent(ctx, type, prompt, options) {
         collector.unsubscribe();
         cleanupAbort();
     }
-    return { responseText: collector.getText(), session, aborted, steered: softLimitReached };
+    const responseText = collector.getText().trim() || getLastAssistantText(session);
+    return { responseText, session, aborted, steered: softLimitReached };
 }
 /**
  * Send a new prompt to an existing session (resume).
@@ -273,7 +292,7 @@ export async function resumeAgent(session, prompt, options = {}) {
         unsubToolUse();
         cleanupAbort();
     }
-    return collector.getText();
+    return collector.getText().trim() || getLastAssistantText(session);
 }
 /**
  * Send a steering message to a running subagent.
@@ -302,7 +321,7 @@ export function getAgentConversation(session) {
                 if (c.type === "text" && c.text)
                     textParts.push(c.text);
                 else if (c.type === "toolCall")
-                    toolCalls.push(`  Tool: ${c.toolName ?? "unknown"}`);
+                    toolCalls.push(`  Tool: ${c.name ?? c.toolName ?? "unknown"}`);
             }
             if (textParts.length > 0)
                 parts.push(`[Assistant]: ${textParts.join("\n")}`);

package/dist/cross-extension-rpc.d.ts

@@ -1,17 +1,32 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
     on(event: string, handler: (data: unknown) => void): () => void;
     emit(event: string, data: unknown): void;
 }
-/** Minimal AgentManager interface needed by the spawn RPC. */
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> = {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error: string;
+};
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export declare const PROTOCOL_VERSION = 2;
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
 export interface SpawnCapable {
     spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+    abort(id: string): boolean;
 }
 export interface RpcDeps {
     events: EventBus;
@@ -22,9 +37,10 @@ export interface RpcDeps {
 export interface RpcHandle {
     unsubPing: () => void;
     unsubSpawn: () => void;
+    unsubStop: () => void;
 }
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export declare function registerRpcHandlers(deps: RpcDeps): RpcHandle;

package/dist/cross-extension-rpc.js

@@ -1,33 +1,54 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc(events, channel, fn) {
+    return events.on(channel, async (raw) => {
+        const params = raw;
+        try {
+            const data = await fn(params);
+            const reply = { success: true };
+            if (data !== undefined)
+                reply.data = data;
+            events.emit(`${channel}:reply:${params.requestId}`, reply);
+        }
+        catch (err) {
+            events.emit(`${channel}:reply:${params.requestId}`, {
+                success: false, error: err?.message ?? String(err),
+            });
+        }
+    });
+}
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps) {
     const { events, pi, getCtx, manager } = deps;
-    const unsubPing = events.on("subagents:rpc:ping", (raw) => {
-        const { requestId } = raw;
-        events.emit(`subagents:rpc:ping:reply:${requestId}`, {});
+    const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+        return { version: PROTOCOL_VERSION };
     });
-    const unsubSpawn = events.on("subagents:rpc:spawn", async (raw) => {
-        const { requestId, type, prompt, options } = raw;
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
         const ctx = getCtx();
-        if (!ctx) {
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: "No active session" });
-            return;
-        }
-        try {
-            const id = manager.spawn(pi, ctx, type, prompt, options ?? {});
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { id });
-        }
-        catch (err) {
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: err.message });
-        }
+        if (!ctx)
+            throw new Error("No active session");
+        return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+    });
+    const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
+        if (!manager.abort(agentId))
+            throw new Error("Agent not found");
     });
-    return { unsubPing, unsubSpawn };
+    return { unsubPing, unsubSpawn, unsubStop };
 }

package/dist/custom-agents.js

@@ -54,12 +54,12 @@ function loadFromDir(dir, agents, source) {
             skills: inheritField(fm.skills ?? fm.inherit_skills),
             model: str(fm.model),
             thinking: str(fm.thinking),
-            maxTurns: positiveInt(fm.max_turns),
+            maxTurns: nonNegativeInt(fm.max_turns),
             systemPrompt: body.trim(),
             promptMode: fm.prompt_mode === "append" ? "append" : "replace",
-            inheritContext: fm.inherit_context === true,
-            runInBackground: fm.run_in_background === true,
-            isolated: fm.isolated === true,
+            inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+            runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+            isolated: fm.isolated != null ? fm.isolated === true : undefined,
             memory: parseMemory(fm.memory),
             isolation: fm.isolation === "worktree" ? "worktree" : undefined,
             enabled: fm.enabled !== false, // default true; explicitly false disables
@@ -73,9 +73,9 @@ function loadFromDir(dir, agents, source) {
 function str(val) {
     return typeof val === "string" ? val : undefined;
 }
-/** Extract a positive integer or undefined. */
-function positiveInt(val) {
-    return typeof val === "number" && val >= 1 ? val : undefined;
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val) {
+    return typeof val === "number" && val >= 0 ? val : undefined;
 }
 /**
  * Parse a raw CSV field value into items, or undefined if absent/empty/"none".

package/dist/index.js

@@ -15,11 +15,12 @@ import { join } from "node:path";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { GroupJoinManager } from "./group-join.js";
+import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { AgentWidget, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
@@ -254,7 +255,7 @@ export default function (pi) {
             content: notification + footer,
             display: true,
             details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
-        }, { deliverAs: "followUp" });
+        }, { deliverAs: "followUp", triggerTurn: true });
     }
     function sendIndividualNudge(record) {
         agentActivity.delete(record.id);
@@ -290,7 +291,7 @@ export default function (pi) {
                 content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
                 display: true,
                 details,
-            }, { deliverAs: "followUp" });
+            }, { deliverAs: "followUp", triggerTurn: true });
         });
         widget.update();
     }, 30_000);
@@ -383,7 +384,7 @@ export default function (pi) {
         manager.clearCompleted(); // preserve existing behavior
     });
     pi.on("session_switch", () => { manager.clearCompleted(); });
-    const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+    const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
         events: pi.events,
         pi,
         getCtx: () => currentCtx,
@@ -395,6 +396,7 @@ export default function (pi) {
     // If the session is going down, there's nothing left to consume agent results.
     pi.on("session_shutdown", async () => {
         unsubSpawnRpc();
+        unsubStopRpc();
         unsubPingRpc();
         currentCtx = undefined;
         delete globalThis[MANAGER_KEY];
@@ -510,8 +512,7 @@ Guidelines:
 - 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.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).
-- Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
         parameters: Type.Object({
             prompt: Type.String({
                 description: "The task for the agent to perform.",
@@ -547,10 +548,6 @@ Guidelines:
             isolation: Type.Optional(Type.Literal("worktree", {
                 description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
             })),
-            join_mode: Type.Optional(Type.Union([
-                Type.Literal("async"),
-                Type.Literal("group"),
-            ], { description: "Override join behavior for background agents. async: individual nudge on completion. group: hold and send one consolidated notification when all agents in the group complete. Default: smart (auto-groups 2+ background agents spawned in the same turn)." })),
         }),
         // ---- Custom rendering: Claude Code style ----
         renderCall(args, theme) {
@@ -649,27 +646,25 @@ Guidelines:
             const displayName = getDisplayName(subagentType);
             // Get agent config (if any)
             const customConfig = getAgentConfig(subagentType);
-            // Resolve model if specified (supports exact "provider/modelId" or fuzzy match)
+            const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
+            // Resolve model from agent config first; tool-call params only fill gaps.
             let model = ctx.model;
-            const modelInput = params.model ?? customConfig?.model;
-            if (modelInput) {
-                const resolved = resolveModel(modelInput, ctx.modelRegistry);
+            if (resolvedConfig.modelInput) {
+                const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
                 if (typeof resolved === "string") {
-                    if (params.model)
-                        return textResult(resolved); // user-specified: error
+                    if (resolvedConfig.modelFromParams)
+                        return textResult(resolved);
                     // config-specified: silent fallback to parent
                 }
                 else {
                     model = resolved;
                 }
             }
-            // Resolve thinking: explicit param > custom config > undefined
-            const thinking = (params.thinking ?? customConfig?.thinking);
-            // Resolve spawn-time defaults from custom config (caller overrides)
-            const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
-            const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
-            const isolated = params.isolated ?? customConfig?.isolated ?? false;
-            const isolation = params.isolation ?? customConfig?.isolation;
+            const thinking = resolvedConfig.thinking;
+            const inheritContext = resolvedConfig.inheritContext;
+            const runInBackground = resolvedConfig.runInBackground;
+            const isolated = resolvedConfig.isolated;
+            const isolation = resolvedConfig.isolation;
             // Build display tags for non-default config
             const parentModelId = ctx.model?.id;
             const effectiveModelId = model?.id;
@@ -686,7 +681,7 @@ Guidelines:
                 agentTags.push("isolated");
             if (isolation === "worktree")
                 agentTags.push("worktree");
-            const effectiveMaxTurns = params.max_turns ?? customConfig?.maxTurns ?? getDefaultMaxTurns();
+            const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
             // Shared base fields for all AgentDetails in this call
             const detailBase = {
                 displayName,
@@ -708,7 +703,7 @@ Guidelines:
                 if (!record) {
                     return textResult(`Failed to resume agent "${params.resume}".`);
                 }
-                return textResult(record.result ?? record.error ?? "No output.", buildDetails(detailBase, record));
+                return textResult(record.result?.trim() || record.error?.trim() || "No output.", buildDetails(detailBase, record));
             }
             // Background execution
             if (runInBackground) {
@@ -728,7 +723,7 @@ Guidelines:
                 id = manager.spawn(pi, ctx, subagentType, params.prompt, {
                     description: params.description,
                     model,
-                    maxTurns: params.max_turns,
+                    maxTurns: effectiveMaxTurns,
                     isolated,
                     inheritContext,
                     thinkingLevel: thinking,
@@ -738,16 +733,16 @@ Guidelines:
                 });
                 // Set output file + join mode synchronously after spawn, before the
                 // event loop yields — onSessionCreated is async so this is safe.
-                const joinMode = params.join_mode ?? defaultJoinMode;
+                const joinMode = resolveJoinMode(defaultJoinMode, true);
                 const record = manager.getRecord(id);
-                if (record) {
+                if (record && joinMode) {
                     record.joinMode = joinMode;
                     record.toolCallId = toolCallId;
                     record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
                     writeInitialEntry(record.outputFile, id, params.prompt, ctx.cwd);
                 }
-                if (joinMode === 'async') {
-                    // Explicit async — not part of any batch
+                if (joinMode == null || joinMode === 'async') {
+                    // Foreground/no join mode or explicit async — not part of any batch
                 }
                 else {
                     // smart or group — add to current batch
@@ -823,7 +818,7 @@ Guidelines:
             const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
                 description: params.description,
                 model,
-                maxTurns: params.max_turns,
+                maxTurns: effectiveMaxTurns,
                 isolated,
                 inheritContext,
                 thinkingLevel: thinking,
@@ -850,7 +845,7 @@ Guidelines:
             if (tokenText)
                 statsParts.push(tokenText);
             return textResult(`${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-                (record.result ?? "No output."), details);
+                (record.result?.trim() || "No output."), details);
         },
     });
     // ---- get_subagent_result tool ----
@@ -897,7 +892,7 @@ Guidelines:
                 output += `Error: ${record.error}`;
             }
             else {
-                output += record.result ?? "No output.";
+                output += record.result?.trim() || "No output.";
             }
             // Mark result as consumed — suppresses the completion notification
             if (record.status !== "running" && record.status !== "queued") {

package/dist/invocation-config.d.ts

@@ -0,0 +1,22 @@
+import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+interface AgentInvocationParams {
+    model?: string;
+    thinking?: string;
+    max_turns?: number;
+    run_in_background?: boolean;
+    inherit_context?: boolean;
+    isolated?: boolean;
+    isolation?: IsolationMode;
+}
+export declare function resolveAgentInvocationConfig(agentConfig: AgentConfig | undefined, params: AgentInvocationParams): {
+    modelInput?: string;
+    modelFromParams: boolean;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    inheritContext: boolean;
+    runInBackground: boolean;
+    isolated: boolean;
+    isolation?: IsolationMode;
+};
+export declare function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined;
+export {};

package/dist/invocation-config.js

@@ -0,0 +1,15 @@
+export function resolveAgentInvocationConfig(agentConfig, params) {
+    return {
+        modelInput: agentConfig?.model ?? params.model,
+        modelFromParams: agentConfig?.model == null && params.model != null,
+        thinking: (agentConfig?.thinking ?? params.thinking),
+        maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+        inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+        runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+        isolated: agentConfig?.isolated ?? params.isolated ?? false,
+        isolation: agentConfig?.isolation ?? params.isolation,
+    };
+}
+export function resolveJoinMode(defaultJoinMode, runInBackground) {
+    return runInBackground ? defaultJoinMode : undefined;
+}

package/dist/types.d.ts

@@ -29,12 +29,12 @@ export interface AgentConfig {
     maxTurns?: number;
     systemPrompt: string;
     promptMode: "replace" | "append";
-    /** Default for spawn: fork parent conversation */
-    inheritContext: boolean;
-    /** Default for spawn: run in background */
-    runInBackground: boolean;
-    /** Default for spawn: no extension tools */
-    isolated: boolean;
+    /** Default for spawn: fork parent conversation. undefined = caller decides. */
+    inheritContext?: boolean;
+    /** Default for spawn: run in background. undefined = caller decides. */
+    runInBackground?: boolean;
+    /** Default for spawn: no extension tools. undefined = caller decides. */
+    isolated?: boolean;
     /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
     memory?: MemoryScope;
     /** Isolation mode — "worktree" runs the agent in a temporary git worktree */

package/dist/ui/conversation-viewer.js

@@ -179,7 +179,7 @@ export class ConversationViewer {
                     if (c.type === "text" && c.text)
                         textParts.push(c.text);
                     else if (c.type === "toolCall") {
-                        toolCalls.push(c.toolName ?? "unknown");
+                        toolCalls.push(c.name ?? c.toolName ?? "unknown");
                     }
                 }
                 if (needsSeparator)

package/dist/ui/conversation-viewer.test.js

@@ -159,7 +159,7 @@ describe("ConversationViewer", () => {
                     role: "assistant",
                     content: [
                         { type: "text", text: "Let me check that." },
-                        { type: "toolCall", toolUseId: "t1", toolName: "very_long_tool_name_" + "x".repeat(200), input: {} },
+                        { type: "toolCall", toolUseId: "t1", name: "very_long_tool_name_" + "x".repeat(200), input: {} },
                     ],
                 },
             ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.4.11",
+  "version": "0.5.1",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -21,9 +21,9 @@
     "autonomous"
   ],
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.60.0",
-    "@mariozechner/pi-coding-agent": "^0.60.0",
-    "@mariozechner/pi-tui": "^0.60.0",
+    "@mariozechner/pi-ai": "^0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-tui": "^0.62.0",
     "@sinclair/typebox": "latest"
   },
   "scripts": {
@@ -36,9 +36,9 @@
     "lint:fix": "biome check --fix src/ test/"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
     "@biomejs/biome": "^2.3.5",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.0.0",
     "vitest": "^4.0.18"
   },
   "pi": {

package/src/agent-runner.ts

@@ -27,10 +27,16 @@ const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
 
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n: number | undefined): number | undefined {
+  if (n == null || n === 0) return undefined;
+  return Math.max(1, n);
+}
+
 /** Get the default max turns value. undefined = unlimited. */
 export function getDefaultMaxTurns(): number | undefined { return defaultMaxTurns; }
-/** Set the default max turns value. undefined = unlimited, otherwise minimum 1. */
-export function setDefaultMaxTurns(n: number | undefined): void { defaultMaxTurns = n != null ? Math.max(1, n) : undefined; }
+/** Set the default max turns value. undefined or 0 = unlimited, otherwise minimum 1. */
+export function setDefaultMaxTurns(n: number | undefined): void { defaultMaxTurns = normalizeMaxTurns(n); }
 
 /** Additional turns allowed after the soft limit steer message. */
 let graceTurns = 5;
@@ -123,6 +129,17 @@ function collectResponseText(session: AgentSession) {
   return { getText: () => text, unsubscribe };
 }
 
+/** Get the last assistant text from the completed session history. */
+function getLastAssistantText(session: AgentSession): string {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = extractText(msg.content).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
 /**
  * Wire an AbortSignal to abort a session.
  * Returns a cleanup function to remove the listener.
@@ -279,7 +296,7 @@ export async function runAgent(
 
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
-  const maxTurns = options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns;
+  const maxTurns = normalizeMaxTurns(options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns);
   let softLimitReached = false;
   let aborted = false;
 
@@ -333,7 +350,8 @@ export async function runAgent(
     cleanupAbort();
   }
 
-  return { responseText: collector.getText(), session, aborted, steered: softLimitReached };
+  const responseText = collector.getText().trim() || getLastAssistantText(session);
+  return { responseText, session, aborted, steered: softLimitReached };
 }
 
 /**
@@ -362,7 +380,7 @@ export async function resumeAgent(
     cleanupAbort();
   }
 
-  return collector.getText();
+  return collector.getText().trim() || getLastAssistantText(session);
 }
 
 /**
@@ -393,7 +411,7 @@ export function getAgentConversation(session: AgentSession): string {
       const toolCalls: string[] = [];
       for (const c of msg.content) {
         if (c.type === "text" && c.text) textParts.push(c.text);
-        else if (c.type === "toolCall") toolCalls.push(`  Tool: ${(c as any).toolName ?? "unknown"}`);
+        else if (c.type === "toolCall") toolCalls.push(`  Tool: ${(c as any).name ?? (c as any).toolName ?? "unknown"}`);
       }
       if (textParts.length > 0) parts.push(`[Assistant]: ${textParts.join("\n")}`);
       if (toolCalls.length > 0) parts.push(`[Tool Calls]:\n${toolCalls.join("\n")}`);

package/src/cross-extension-rpc.ts

@@ -1,8 +1,12 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
 
 /** Minimal event bus interface needed by the RPC handlers. */
@@ -11,9 +15,18 @@ export interface EventBus {
   emit(event: string, data: unknown): void;
 }
 
-/** Minimal AgentManager interface needed by the spawn RPC. */
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string };
+
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
 export interface SpawnCapable {
   spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+  abort(id: string): boolean;
 }
 
 export interface RpcDeps {
@@ -26,36 +39,57 @@ export interface RpcDeps {
 export interface RpcHandle {
   unsubPing: () => void;
   unsubSpawn: () => void;
+  unsubStop: () => void;
 }
 
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc<P extends { requestId: string }>(
+  events: EventBus,
+  channel: string,
+  fn: (params: P) => unknown | Promise<unknown>,
+): () => void {
+  return events.on(channel, async (raw: unknown) => {
+    const params = raw as P;
+    try {
+      const data = await fn(params);
+      const reply: { success: true; data?: unknown } = { success: true };
+      if (data !== undefined) reply.data = data;
+      events.emit(`${channel}:reply:${params.requestId}`, reply);
+    } catch (err: any) {
+      events.emit(`${channel}:reply:${params.requestId}`, {
+        success: false, error: err?.message ?? String(err),
+      });
+    }
+  });
+}
+
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   const { events, pi, getCtx, manager } = deps;
 
-  const unsubPing = events.on("subagents:rpc:ping", (raw: unknown) => {
-    const { requestId } = raw as { requestId: string };
-    events.emit(`subagents:rpc:ping:reply:${requestId}`, {});
+  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+    return { version: PROTOCOL_VERSION };
   });
 
-  const unsubSpawn = events.on("subagents:rpc:spawn", async (raw: unknown) => {
-    const { requestId, type, prompt, options } = raw as {
-      requestId: string; type: string; prompt: string; options?: any;
-    };
-    const ctx = getCtx();
-    if (!ctx) {
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: "No active session" });
-      return;
-    }
-    try {
-      const id = manager.spawn(pi, ctx, type, prompt, options ?? {});
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { id });
-    } catch (err: any) {
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: err.message });
-    }
-  });
+  const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
+    events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
+      const ctx = getCtx();
+      if (!ctx) throw new Error("No active session");
+      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+    },
+  );
+
+  const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
+    events, "subagents:rpc:stop", ({ agentId }) => {
+      if (!manager.abort(agentId)) throw new Error("Agent not found");
+    },
+  );
 
-  return { unsubPing, unsubSpawn };
+  return { unsubPing, unsubSpawn, unsubStop };
 }

package/src/custom-agents.ts

@@ -61,12 +61,12 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       model: str(fm.model),
       thinking: str(fm.thinking) as ThinkingLevel | undefined,
-      maxTurns: positiveInt(fm.max_turns),
+      maxTurns: nonNegativeInt(fm.max_turns),
       systemPrompt: body.trim(),
       promptMode: fm.prompt_mode === "append" ? "append" : "replace",
-      inheritContext: fm.inherit_context === true,
-      runInBackground: fm.run_in_background === true,
-      isolated: fm.isolated === true,
+      inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+      runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+      isolated: fm.isolated != null ? fm.isolated === true : undefined,
       memory: parseMemory(fm.memory),
       isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false,  // default true; explicitly false disables
@@ -83,9 +83,9 @@ function str(val: unknown): string | undefined {
   return typeof val === "string" ? val : undefined;
 }
 
-/** Extract a positive integer or undefined. */
-function positiveInt(val: unknown): number | undefined {
-  return typeof val === "number" && val >= 1 ? val : undefined;
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val: unknown): number | undefined {
+  return typeof val === "number" && val >= 0 ? val : undefined;
 }
 
 /**

package/src/index.ts

@@ -17,14 +17,15 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@m
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { GroupJoinManager } from "./group-join.js";
+import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
-import { type AgentConfig, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType, type ThinkingLevel } from "./types.js";
+import { type AgentConfig, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
   type AgentActivity,
   type AgentDetails,
@@ -289,7 +290,7 @@ export default function (pi: ExtensionAPI) {
       content: notification + footer,
       display: true,
       details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
-    }, { deliverAs: "followUp" });
+    }, { deliverAs: "followUp", triggerTurn: true });
   }
 
   function sendIndividualNudge(record: AgentRecord) {
@@ -326,7 +327,7 @@ export default function (pi: ExtensionAPI) {
           content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
           display: true,
           details,
-        }, { deliverAs: "followUp" });
+        }, { deliverAs: "followUp", triggerTurn: true });
       });
       widget.update();
     },
@@ -431,7 +432,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_switch", () => { manager.clearCompleted(); });
 
-  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
     events: pi.events,
     pi,
     getCtx: () => currentCtx,
@@ -445,6 +446,7 @@ export default function (pi: ExtensionAPI) {
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
     unsubSpawnRpc();
+    unsubStopRpc();
     unsubPingRpc();
     currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];
@@ -571,8 +573,7 @@ Guidelines:
 - 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.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).
-- Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
     parameters: Type.Object({
       prompt: Type.String({
         description: "The task for the agent to perform.",
@@ -625,12 +626,6 @@ Guidelines:
           description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
         }),
       ),
-      join_mode: Type.Optional(
-        Type.Union([
-          Type.Literal("async"),
-          Type.Literal("group"),
-        ], { description: "Override join behavior for background agents. async: individual nudge on completion. group: hold and send one consolidated notification when all agents in the group complete. Default: smart (auto-groups 2+ background agents spawned in the same turn)." }),
-      ),
     }),
 
     // ---- Custom rendering: Claude Code style ----
@@ -742,27 +737,25 @@ Guidelines:
       // Get agent config (if any)
       const customConfig = getAgentConfig(subagentType);
 
-      // Resolve model if specified (supports exact "provider/modelId" or fuzzy match)
+      const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
+
+      // Resolve model from agent config first; tool-call params only fill gaps.
       let model = ctx.model;
-      const modelInput = params.model ?? customConfig?.model;
-      if (modelInput) {
-        const resolved = resolveModel(modelInput, ctx.modelRegistry);
+      if (resolvedConfig.modelInput) {
+        const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
         if (typeof resolved === "string") {
-          if (params.model) return textResult(resolved); // user-specified: error
+          if (resolvedConfig.modelFromParams) return textResult(resolved);
           // config-specified: silent fallback to parent
         } else {
           model = resolved;
         }
       }
 
-      // Resolve thinking: explicit param > custom config > undefined
-      const thinking = (params.thinking ?? customConfig?.thinking) as ThinkingLevel | undefined;
-
-      // Resolve spawn-time defaults from custom config (caller overrides)
-      const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
-      const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
-      const isolated = params.isolated ?? customConfig?.isolated ?? false;
-      const isolation = params.isolation ?? customConfig?.isolation;
+      const thinking = resolvedConfig.thinking;
+      const inheritContext = resolvedConfig.inheritContext;
+      const runInBackground = resolvedConfig.runInBackground;
+      const isolated = resolvedConfig.isolated;
+      const isolation = resolvedConfig.isolation;
 
       // Build display tags for non-default config
       const parentModelId = ctx.model?.id;
@@ -776,7 +769,7 @@ Guidelines:
       if (thinking) agentTags.push(`thinking: ${thinking}`);
       if (isolated) agentTags.push("isolated");
       if (isolation === "worktree") agentTags.push("worktree");
-      const effectiveMaxTurns = params.max_turns ?? customConfig?.maxTurns ?? getDefaultMaxTurns();
+      const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
       // Shared base fields for all AgentDetails in this call
       const detailBase = {
         displayName,
@@ -800,7 +793,7 @@ Guidelines:
           return textResult(`Failed to resume agent "${params.resume}".`);
         }
         return textResult(
-          record.result ?? record.error ?? "No output.",
+          record.result?.trim() || record.error?.trim() || "No output.",
           buildDetails(detailBase, record),
         );
       }
@@ -825,7 +818,7 @@ Guidelines:
         id = manager.spawn(pi, ctx, subagentType, params.prompt, {
           description: params.description,
           model,
-          maxTurns: params.max_turns,
+          maxTurns: effectiveMaxTurns,
           isolated,
           inheritContext,
           thinkingLevel: thinking,
@@ -836,17 +829,17 @@ Guidelines:
 
         // Set output file + join mode synchronously after spawn, before the
         // event loop yields — onSessionCreated is async so this is safe.
-        const joinMode: JoinMode = params.join_mode ?? defaultJoinMode;
+        const joinMode = resolveJoinMode(defaultJoinMode, true);
         const record = manager.getRecord(id);
-        if (record) {
+        if (record && joinMode) {
           record.joinMode = joinMode;
           record.toolCallId = toolCallId;
           record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
           writeInitialEntry(record.outputFile, id, params.prompt, ctx.cwd);
         }
 
-        if (joinMode === 'async') {
-          // Explicit async — not part of any batch
+        if (joinMode == null || joinMode === 'async') {
+          // Foreground/no join mode or explicit async — not part of any batch
         } else {
           // smart or group — add to current batch
           currentBatchAgents.push({ id, joinMode });
@@ -933,7 +926,7 @@ Guidelines:
       const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
         description: params.description,
         model,
-        maxTurns: params.max_turns,
+        maxTurns: effectiveMaxTurns,
         isolated,
         inheritContext,
         thinkingLevel: thinking,
@@ -967,7 +960,7 @@ Guidelines:
       if (tokenText) statsParts.push(tokenText);
       return textResult(
         `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-        (record.result ?? "No output."),
+        (record.result?.trim() || "No output."),
         details,
       );
     },
@@ -1026,7 +1019,7 @@ Guidelines:
       } else if (record.status === "error") {
         output += `Error: ${record.error}`;
       } else {
-        output += record.result ?? "No output.";
+        output += record.result?.trim() || "No output.";
       }
 
       // Mark result as consumed — suppresses the completion notification

package/src/invocation-config.ts

@@ -0,0 +1,40 @@
+import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+
+interface AgentInvocationParams {
+  model?: string;
+  thinking?: string;
+  max_turns?: number;
+  run_in_background?: boolean;
+  inherit_context?: boolean;
+  isolated?: boolean;
+  isolation?: IsolationMode;
+}
+
+export function resolveAgentInvocationConfig(
+  agentConfig: AgentConfig | undefined,
+  params: AgentInvocationParams,
+): {
+  modelInput?: string;
+  modelFromParams: boolean;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation?: IsolationMode;
+} {
+  return {
+    modelInput: agentConfig?.model ?? params.model,
+    modelFromParams: agentConfig?.model == null && params.model != null,
+    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+    inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+    runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+    isolated: agentConfig?.isolated ?? params.isolated ?? false,
+    isolation: agentConfig?.isolation ?? params.isolation,
+  };
+}
+
+export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
+  return runInBackground ? defaultJoinMode : undefined;
+}

package/src/types.ts

@@ -36,12 +36,12 @@ export interface AgentConfig {
   maxTurns?: number;
   systemPrompt: string;
   promptMode: "replace" | "append";
-  /** Default for spawn: fork parent conversation */
-  inheritContext: boolean;
-  /** Default for spawn: run in background */
-  runInBackground: boolean;
-  /** Default for spawn: no extension tools */
-  isolated: boolean;
+  /** Default for spawn: fork parent conversation. undefined = caller decides. */
+  inheritContext?: boolean;
+  /** Default for spawn: run in background. undefined = caller decides. */
+  runInBackground?: boolean;
+  /** Default for spawn: no extension tools. undefined = caller decides. */
+  isolated?: boolean;
   /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
   memory?: MemoryScope;
   /** Isolation mode — "worktree" runs the agent in a temporary git worktree */

package/src/ui/conversation-viewer.ts

@@ -191,7 +191,7 @@ export class ConversationViewer implements Component {
         for (const c of msg.content) {
           if (c.type === "text" && c.text) textParts.push(c.text);
           else if (c.type === "toolCall") {
-            toolCalls.push((c as any).toolName ?? "unknown");
+            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
           }
         }
         if (needsSeparator) lines.push(th.fg("dim", "───"));