@tintinweb/pi-subagents 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-03-26
+
+### Fixed
+- **Extension `session_start` handlers now fire in subagent sessions** ([#20](https://github.com/tintinweb/pi-subagents/issues/20)) — `bindExtensions()` was never called on subagent sessions, so extensions that initialize state in `session_start` (e.g. loading credentials, setting up connections) silently failed at runtime. Tools appeared registered but were non-functional. Now calls `session.bindExtensions()` after tool filtering and before prompting, matching the lifecycle used by pi's interactive, print, and RPC modes. Also triggers `extendResourcesFromExtensions("startup")` so extension-provided skills and prompts are discovered.
+
+## [0.5.1] - 2026-03-24
+
+### Changed
+- **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
@@ -329,6 +345,8 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.5.2]: https://github.com/tintinweb/pi-subagents/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/tintinweb/pi-subagents/compare/v0.5.0...v0.5.1
 [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

package/README.md

@@ -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
 

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.
@@ -195,10 +213,22 @@ export async function runAgent(ctx, type, prompt, options) {
         const activeTools = session.getActiveToolNames().filter(t => !disallowedSet.has(t));
         session.setActiveToolsByName(activeTools);
     }
+    // Bind extensions so that session_start fires and extensions can initialize
+    // (e.g. loading credentials, setting up state). Placed after tool filtering
+    // so extension-provided skills/prompts from extendResourcesFromExtensions()
+    // respect the active tool set. All ExtensionBindings fields are optional.
+    await session.bindExtensions({
+        onError: (err) => {
+            options.onToolActivity?.({
+                type: "end",
+                toolName: `extension-error:${err.extensionPath}`,
+            });
+        },
+    });
     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 +279,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 +304,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.

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";
@@ -511,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.",
@@ -548,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) {
@@ -650,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;
@@ -687,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,
@@ -709,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) {
@@ -729,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,
@@ -739,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
@@ -824,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,
@@ -851,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 ----
@@ -898,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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.61.1",
-    "@mariozechner/pi-coding-agent": "^0.61.1",
-    "@mariozechner/pi-tui": "^0.61.1",
+    "@mariozechner/pi-ai": "^0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-tui": "^0.62.0",
     "@sinclair/typebox": "latest"
   },
   "scripts": {

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.
@@ -275,11 +292,24 @@ export async function runAgent(
     session.setActiveToolsByName(activeTools);
   }
 
+  // Bind extensions so that session_start fires and extensions can initialize
+  // (e.g. loading credentials, setting up state). Placed after tool filtering
+  // so extension-provided skills/prompts from extendResourcesFromExtensions()
+  // respect the active tool set. All ExtensionBindings fields are optional.
+  await session.bindExtensions({
+    onError: (err) => {
+      options.onToolActivity?.({
+        type: "end",
+        toolName: `extension-error:${err.extensionPath}`,
+      });
+    },
+  });
+
   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;
 
@@ -333,7 +363,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 +393,7 @@ export async function resumeAgent(
     cleanupAbort();
   }
 
-  return collector.getText();
+  return collector.getText().trim() || getLastAssistantText(session);
 }
 
 /**

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,
@@ -572,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.",
@@ -626,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 ----
@@ -743,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;
@@ -777,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,
@@ -801,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),
         );
       }
@@ -826,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,
@@ -837,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 });
@@ -934,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,
@@ -968,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,
       );
     },
@@ -1027,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 */