@clanker-code/pi-subagents 0.10.6 → 0.10.8

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.8] - 2026-06-23
+
+### Changed
+- **`get_subagent_result` wait:true now detects queued user messages** — when the parent session has user messages waiting (e.g. the user typed while waiting), the tool returns early with a `pending_message` outcome instead of blocking for the full wait timeout. The queued message is delivered to the parent LLM immediately. Uses `ctx.hasPendingMessages()` polling during the wait. The subagent continues running undisturbed.
+
+## [0.10.7] - 2026-06-23
+
+### Fixed
+- **`get_subagent_result` output is now bounded** — normal result previews, `verbose: true` conversation previews, and `peek` responses are capped so a large subagent transcript cannot flood the parent context. Truncated responses include the omitted size, continuation guidance, and the agent output file path for full-log inspection. Output files are now attached to background records before the agent can complete, avoiding a fast-completion race where retrieval guidance could miss the transcript path.
+- **Agent-runner e2e no longer waits on an unnecessary prompt turn** — the real-runtime tool-gating test now stops after capturing active tools at session construction, avoiding intermittent 30s timeouts under full-suite load.
+
 ## [0.10.6] - 2026-06-22
 
 ### Changed
@@ -28,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Fork metadata applied** — package author, repository, homepage, bugs, and media URLs now point to the `clankercode/pi-subagents` fork.
 
 ### Fixed
-- **Subagent completion notifications now include final output and explicit retrieval guidance** — both the machine-readable XML payload and the visible custom renderer include a `get_subagent_result <id>` instruction plus the transcript file path, so the parent can read the full output/log from the notification itself.
+- **Subagent completion notifications now include final output previews and explicit retrieval guidance** — both the machine-readable XML payload and the visible custom renderer include a `get_subagent_result <id>` bounded-preview instruction plus the transcript file path for full-log inspection when available.
 
 ## [0.10.3] - 2026-06-12
 

package/README.md

@@ -19,7 +19,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 ### Fork-specific differences
 
 - **Packaging under `@clanker-code`** — published from this fork, not the upstream namespace.
-- **Completion notifications include full-output guidance** — every notification carries final output preview plus an explicit `get_subagent_result <id>` instruction and transcript path, so the parent can retrieve the full log directly from the notification.
+- **Completion notifications include bounded-output guidance** — every notification carries a final output preview plus an explicit `get_subagent_result <id>` bounded-preview instruction and transcript path for full-log inspection when available.
 - Additional fork-specific changes are listed in the [CHANGELOG](./CHANGELOG.md).
 
 Upstream changes are reviewed for cherry-picking when practical; otherwise they are reimplemented to fit this fork.
@@ -41,7 +41,7 @@ Upstream changes are reviewed for cherry-picking when practical; otherwise they
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
 - **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **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
+- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show a bounded preview and transcript path. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
 - **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
 - **Schedule subagents** — pass `schedule` to the `Agent` tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same steering-style `subagent-notification` path as manual background completions; manage via `/agents → Scheduled jobs`
@@ -279,17 +279,18 @@ Launch a sub-agent.
 | `isolation` | `"worktree"` | no | Run in an isolated git worktree |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |
 
-All `Agent` calls run in the background. Completion notifications are delivered automatically; use `get_subagent_result` only when you explicitly need to check status or fetch a full result.
+All `Agent` calls run in the background. Completion notifications are delivered automatically; use `get_subagent_result` only when you explicitly need to check status or inspect a bounded result preview. Full transcripts are written to the agent output file shown in the `Agent` response and `get_subagent_result` output.
 
 ### `get_subagent_result`
 
-Check status and retrieve results from a background agent.
+Check status and retrieve bounded output from a background agent. The tool is safe-by-default for LLM context: normal results, verbose conversation output, and `peek` responses are capped. If output is truncated, the response includes the output file path and continuation guidance.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `agent_id` | string | yes | Agent ID to check |
 | `wait` | boolean | no | Wait for completion |
-| `verbose` | boolean | no | Include full conversation log |
+| `verbose` | boolean | no | Include a bounded conversation preview |
+| `peek` | object | no | Return a bounded tail/filter view with line numbers. Supports `lines`, `regex`, and `after` for incremental reads. |
 
 ### `steer_subagent`
 

package/dist/agent-manager.d.ts

@@ -53,6 +53,10 @@ interface SpawnOptions {
     onToolActivity?: (activity: ToolActivity) => void;
     /** Called on streaming text deltas from the assistant response. */
     onTextDelta?: (delta: string, fullText: string) => void;
+    /** Build a per-agent output file path before the agent can complete. */
+    outputFileForAgent?: (agentId: string) => string;
+    /** Called after the output file path is attached to the record. */
+    onOutputFileCreated?: (path: string, agentId: string) => void;
     /** Called when the agent session is created (for accessing session stats). */
     onSessionCreated?: (session: AgentSession) => void;
     /** Called at the end of each agentic turn with the cumulative count. */

package/dist/agent-manager.js

@@ -98,6 +98,10 @@ export class AgentManager {
             depth,
             parentAgentId: options.parentAgentId,
         };
+        if (options.outputFileForAgent) {
+            record.outputFile = options.outputFileForAgent(id);
+            options.onOutputFileCreated?.(record.outputFile, id);
+        }
         this.agents.set(id, record);
         const args = { pi, ctx, type, prompt, options };
         if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {

package/dist/bounded-output.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared caps for tool responses that may otherwise flood the parent context.
+ * Full subagent logs remain available via the per-agent output file.
+ */
+export declare const MAX_RESULT_CHARS = 20000;
+export declare const MAX_VERBOSE_CHARS = 20000;
+export declare const MAX_PEEK_CHARS = 20000;
+export declare const MAX_PEEK_LINES = 200;
+export interface LimitedText {
+    text: string;
+    truncated: boolean;
+    omittedChars: number;
+}
+export declare function limitText(text: string, maxChars: number): LimitedText;
+export declare function clampPeekLines(lines: number | undefined): number;
+export declare function formatOutputFileHint(outputFile?: string): string;

package/dist/bounded-output.js

@@ -0,0 +1,26 @@
+/**
+ * Shared caps for tool responses that may otherwise flood the parent context.
+ * Full subagent logs remain available via the per-agent output file.
+ */
+export const MAX_RESULT_CHARS = 20_000;
+export const MAX_VERBOSE_CHARS = 20_000;
+export const MAX_PEEK_CHARS = 20_000;
+export const MAX_PEEK_LINES = 200;
+export function limitText(text, maxChars) {
+    if (text.length <= maxChars) {
+        return { text, truncated: false, omittedChars: 0 };
+    }
+    return {
+        text: text.slice(0, maxChars),
+        truncated: true,
+        omittedChars: text.length - maxChars,
+    };
+}
+export function clampPeekLines(lines) {
+    if (typeof lines !== "number" || !Number.isFinite(lines) || lines < 1)
+        return 20;
+    return Math.min(Math.floor(lines), MAX_PEEK_LINES);
+}
+export function formatOutputFileHint(outputFile) {
+    return outputFile ? ` Full output/log: ${outputFile}` : "";
+}

package/dist/index.js

@@ -22,6 +22,7 @@ import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getCurrentExtensionAgentId, getCurrentExtensionDepth, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { buildAgentToolDescription, getModelLabelFromConfig } from "./agent-tool-description.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
+import { formatOutputFileHint, limitText, MAX_RESULT_CHARS, MAX_VERBOSE_CHARS } from "./bounded-output.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
@@ -41,7 +42,7 @@ import { AgentWidget, buildInvocationTags, describeActivity, formatContextWindow
 import { menuSelect } from "./ui/menu-select.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
-import { formatWaitTimeout, raceWait, waitTimeoutMessage } from "./wait.js";
+import { formatWaitTimeout, pollPendingMessages, raceWait, waitTimeoutMessage } from "./wait.js";
 // ---- Shared helpers ----
 /** Tool execute return value for a text response. */
 function textResult(msg, details) {
@@ -236,7 +237,7 @@ export default function (pi) {
             }
             pi.sendMessage({
                 customType: "subagent-notification",
-                content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+                content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for a bounded preview; inspect the transcript file path for full output when needed.`,
                 display: true,
                 details,
             }, { deliverAs: "steer", triggerTurn: true });
@@ -823,7 +824,7 @@ export default function (pi) {
                 widget.update();
                 const resumeDetails = { displayName: getDisplayName(record.type), description: record.description, subagentType: record.type, modelName: record.invocation?.modelName };
                 return textResult(`Agent resumed in background.\nAgent ID: ${record.id}\nType: ${resumeDetails.displayName}\nDescription: ${record.description}\n\n` +
-                    `You will be notified when this agent completes.\nUse get_subagent_result to retrieve full results, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`, buildDetails(resumeDetails, record, state, { status: "background" }));
+                    `You will be notified when this agent completes.\nUse get_subagent_result to inspect bounded result previews, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`, buildDetails(resumeDetails, record, state, { status: "background" }));
             }
             // Background execution
             const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
@@ -852,6 +853,8 @@ export default function (pi) {
                     invocation: agentInvocation,
                     depth: nextSubagentDepth,
                     parentAgentId: extensionAgentId,
+                    outputFileForAgent: (agentId) => createOutputFilePath(ctx.cwd, agentId, ctx.sessionManager.getSessionId()),
+                    onOutputFileCreated: (outputFile, agentId) => writeInitialEntry(outputFile, agentId, P.prompt, ctx.cwd),
                     ...bgCallbacks,
                 });
             }
@@ -862,15 +865,13 @@ export default function (pi) {
                 const h = stashInvocation(P, retryHandle, ["isolation"]);
                 return retryableResult(h, err instanceof Error ? err.message : String(err), "isolation");
             }
-            // Set output file + join mode synchronously after spawn, before the
-            // event loop yields — onSessionCreated is async so this is safe.
+            // Set join mode synchronously after spawn. The output file path is
+            // attached inside AgentManager.spawn(), before the agent can complete.
             const joinMode = resolveJoinMode(defaultJoinMode);
             const record = manager.getRecord(id);
             if (record) {
                 record.joinMode = joinMode;
                 record.toolCallId = toolCallId;
-                record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
-                writeInitialEntry(record.outputFile, id, P.prompt, ctx.cwd);
             }
             if (joinMode === 'async') {
                 // No join mode or explicit async — not part of any batch
@@ -900,7 +901,7 @@ export default function (pi) {
             return textResult(`Agent ${isQueued ? "queued" : "started"} in background.\nAgent ID: ${id}\nType: ${displayName}\nDescription: ${P.description}\n` +
                 (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
                 (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
-                `\nYou will be notified when this agent completes.\nUse get_subagent_result to retrieve full results, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`, { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background", agentId: id });
+                `\nYou will be notified when this agent completes.\nUse get_subagent_result to inspect bounded result previews, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`, { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background", agentId: id });
         },
     }));
     // ---- get_subagent_result tool ----
@@ -917,7 +918,7 @@ export default function (pi) {
                 description: `If true, block until the agent completes before returning. Blocks up to the configured wait timeout (${formatWaitTimeout(getWaitTimeoutSeconds())} by default); if the agent is still running when the timeout is reached, returns its current status — call again with wait: true to keep waiting. Interruptible by the parent turn. Default: false.`,
             })),
             verbose: Type.Optional(Type.Boolean({
-                description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+                description: "If true, include a bounded preview of the agent's conversation (messages + tool calls). Default: false.",
             })),
             peek: Type.Optional(Type.Object({
                 lines: Type.Optional(Type.Number({ minimum: 1, description: "Number of trailing lines to return. Default: 20." })),
@@ -927,7 +928,7 @@ export default function (pi) {
                 description: "Return a lightweight tail/filter view of the agent's result or live output file, with line numbers. Ignored when verbose is true.",
             })),
         }),
-        execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
+        execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
             const record = manager.getRecord(params.agent_id);
             if (!record) {
                 return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
@@ -936,7 +937,7 @@ export default function (pi) {
             if (params.peek && !params.verbose) {
                 const peek = peekAgentOutput(record, params.peek);
                 return textResult(peek
-                    ? `${peek.text}\n\n---\nUse verbose: true for the full conversation, or omit peek for the complete result.`
+                    ? `${peek.text}\n\n---\nUse verbose: true for a bounded conversation preview, or omit peek for a bounded result preview.`
                     : "No output yet for this agent.");
             }
             // WAIT — race the agent's completion against the configured timeout and
@@ -945,7 +946,18 @@ export default function (pi) {
             let waitOutcome = "completed";
             if (params.wait && record.status === "running" && record.promise) {
                 cancelNudge(params.agent_id);
-                waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds());
+                // Poll for queued user messages so we can return early and let the
+                // parent LLM process them immediately instead of blocking for the
+                // full wait timeout.
+                const pending = typeof ctx?.hasPendingMessages === "function"
+                    ? pollPendingMessages(() => ctx.hasPendingMessages())
+                    : undefined;
+                try {
+                    waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds(), pending?.promise);
+                }
+                finally {
+                    pending?.cancel();
+                }
                 if (waitOutcome === "completed") {
                     record.resultConsumed = true;
                 }
@@ -964,27 +976,42 @@ export default function (pi) {
             statsParts.push(`Duration: ${duration}`);
             let output = `Agent: ${record.id}\n` +
                 `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
-                `Description: ${record.description}\n\n`;
+                `Description: ${record.description}\n` +
+                (record.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+                `\n`;
             if (record.status === "running") {
                 // The wait returned while the agent was still running (timeout or abort).
                 output += waitTimeoutMessage(waitOutcome, getWaitTimeoutSeconds());
             }
             else if (record.status === "error") {
-                output += `Error: ${record.error}`;
+                const limited = limitText(record.error ?? "unknown", MAX_RESULT_CHARS);
+                output += `Error: ${limited.text}`;
+                if (limited.truncated) {
+                    output += `\n\n---\nError truncated: omitted ${limited.omittedChars} chars. Inspect the output file for the full error when available.${formatOutputFileHint(record.outputFile)}`;
+                }
             }
             else {
-                output += record.result?.trim() || "No output.";
+                const resultText = record.result?.trim() || "No output.";
+                const limited = limitText(resultText, MAX_RESULT_CHARS);
+                output += limited.text;
+                if (limited.truncated) {
+                    output += `\n\n---\nResult truncated: omitted ${limited.omittedChars} chars. Use peek for targeted retrieval, or inspect the output file for the full log.${formatOutputFileHint(record.outputFile)}`;
+                }
             }
             // Mark result as consumed — suppresses the completion notification
             if (record.status !== "running" && record.status !== "queued") {
                 record.resultConsumed = true;
                 cancelNudge(params.agent_id);
             }
-            // Verbose: include full conversation
+            // Verbose: include a bounded conversation preview
             if (params.verbose && record.session) {
                 const conversation = getAgentConversation(record.session);
                 if (conversation) {
-                    output += `\n\n--- Agent Conversation ---\n${conversation}`;
+                    const limited = limitText(conversation, MAX_VERBOSE_CHARS);
+                    output += `\n\n--- Agent Conversation ---\n${limited.text}`;
+                    if (limited.truncated) {
+                        output += `\n\n---\nAgent conversation truncated: omitted ${limited.omittedChars} chars. Use peek for targeted retrieval, or inspect the output file for the full log.${formatOutputFileHint(record.outputFile)}`;
+                    }
                 }
             }
             return textResult(output);

package/dist/notifications.js

@@ -23,12 +23,14 @@ export function formatTaskNotification(record, resultMaxLen) {
     const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
     const resultPreview = record.result
         ? record.result.length > resultMaxLen
-            ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+            ? record.result.slice(0, resultMaxLen) + (record.outputFile
+                ? "\n...(truncated, use get_subagent_result for a bounded preview or inspect the transcript file)"
+                : "\n...(truncated, use get_subagent_result for a bounded preview)")
             : record.result
         : "No output.";
     const fullOutputInstruction = record.outputFile
-        ? `Read the full output/log with get_subagent_result for agent ${record.id}, or inspect the transcript file: ${record.outputFile}`
-        : `Read the full output/log with get_subagent_result for agent ${record.id}.`;
+        ? `Read a bounded preview with get_subagent_result for agent ${record.id}, or inspect the full transcript file: ${record.outputFile}`
+        : `Read a bounded preview with get_subagent_result for agent ${record.id}.`;
     return [
         `<task-notification>`,
         `<task-id>${record.id}</task-id>`,
@@ -96,8 +98,8 @@ export function registerSubagentNotificationRenderer(pi) {
                 line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
             }
             const fullOutputHint = d.outputFile
-                ? `full output: get_subagent_result ${d.id} or transcript: ${d.outputFile}`
-                : `full output: get_subagent_result ${d.id}`;
+                ? `bounded preview: get_subagent_result ${d.id}; full transcript: ${d.outputFile}`
+                : `bounded preview: get_subagent_result ${d.id}`;
             line += "\n  " + theme.fg("muted", fullOutputHint);
             return line;
         }

package/dist/peek.js

@@ -14,8 +14,7 @@
  *   `after` for incremental updates without missing anything.
  */
 import { existsSync, readFileSync } from "node:fs";
-/** Default number of tail lines when neither `after` nor `lines` is given. */
-const DEFAULT_LINES = 20;
+import { clampPeekLines, formatOutputFileHint, limitText, MAX_PEEK_CHARS, MAX_PEEK_LINES } from "./bounded-output.js";
 /**
  * Produce a peek view of an agent's output. Returns null when there is no
  * source content at all (the caller renders a "no output yet" message).
@@ -26,20 +25,33 @@ export function peekAgentOutput(record, opts = {}) {
         return null;
     const regex = opts.regex ? compileRegex(opts.regex) : undefined;
     const after = typeof opts.after === "number" ? opts.after : -1;
-    const tail = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+    const tail = clampPeekLines(opts.lines);
     // Index each source line with its original position (1-based for display).
     const indexed = lines.map((text, i) => ({ no: i + 1, text }));
     // Filter-then-select.
     const filtered = regex ? indexed.filter((l) => regex.test(l.text)) : indexed;
-    const selected = after >= 0
-        ? filtered.filter((l) => l.no > after)
-        : filtered.slice(-tail);
+    const matching = after >= 0 ? filtered.filter((l) => l.no > after) : filtered;
+    const selected = after >= 0 ? matching.slice(0, MAX_PEEK_LINES) : matching.slice(-tail);
+    const lineLimited = matching.length > selected.length;
     const totalLines = lines.length;
     const isRunning = record.status === "running" || record.status === "queued";
     const source = isRunning && record.outputFile && existsSync(record.outputFile) ? "outputFile" : "result";
-    const header = buildHeader(opts, selected.length, totalLines, source);
+    const header = buildHeader(opts, selected.length, totalLines, source, tail, lineLimited, matching.length);
     const body = selected.map((l) => `[${l.no}] ${l.text}`).join("\n");
-    return { text: `${header}\n\n${body}`, totalLines, source };
+    const limited = limitText(body, MAX_PEEK_CHARS);
+    const lastLine = selected.at(-1)?.no;
+    const notices = [];
+    if (lineLimited && lastLine !== undefined) {
+        notices.push(`Peek limited to ${MAX_PEEK_LINES} lines from ${matching.length} matching lines. Use peek.after: ${lastLine} to continue.`);
+    }
+    if (limited.truncated) {
+        notices.push(`Peek output truncated by ${limited.omittedChars} chars. Use a smaller lines value or regex filter.${formatOutputFileHint(record.outputFile)}`);
+    }
+    return {
+        text: `${header}\n\n${limited.text}${notices.length ? `\n\n---\n${notices.join("\n")}` : ""}`,
+        totalLines,
+        source,
+    };
 }
 /** Read the most useful text lines from the agent's output. */
 function readSourceLines(record) {
@@ -105,14 +117,15 @@ function compileRegex(pattern) {
         return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
     }
 }
-function buildHeader(opts, shown, total, source) {
+function buildHeader(opts, shown, total, source, tail, lineLimited, matching) {
     const parts = [];
     if (typeof opts.after === "number") {
         parts.push(`after line number ${opts.after}`);
+        if (lineLimited)
+            parts.push(`limited to ${MAX_PEEK_LINES} lines from ${matching} matching lines`);
     }
     else {
-        const n = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
-        parts.push(`last ${n} lines`);
+        parts.push(`last ${tail} lines`);
     }
     if (opts.regex)
         parts.push(`filtered by regex /${opts.regex}/`);

package/dist/wait.d.ts

@@ -1,10 +1,24 @@
-export type WaitOutcome = "completed" | "timeout" | "aborted";
+export type WaitOutcome = "completed" | "timeout" | "aborted" | "pending_message";
 /** Human-readable "Xm Ys" for a duration in seconds. */
 export declare function formatWaitTimeout(seconds: number): string;
 /**
- * Race an agent completion promise against the configured wait timeout and the
- * parent abort signal. The subagent is never aborted here.
+ * Race an agent completion promise against the configured wait timeout, the
+ * parent abort signal, and an optional pending-message check. The subagent is
+ * never aborted here.
+ *
+ * @param pendingCheck - Optional promise that resolves when the parent session
+ *   has queued user messages waiting to be delivered. When it resolves, the
+ *   wait ends early so the parent turn can process the incoming message.
  */
-export declare function raceWait(promise: Promise<string>, signal: AbortSignal | undefined, timeoutSeconds: number): Promise<WaitOutcome>;
+export declare function raceWait(promise: Promise<string>, signal: AbortSignal | undefined, timeoutSeconds: number, pendingCheck?: Promise<void>): Promise<WaitOutcome>;
 /** Message returned when a wait ends with the agent still running. */
 export declare function waitTimeoutMessage(outcome: WaitOutcome, timeoutSeconds: number): string;
+/**
+ * Create a promise that resolves when the parent session has queued user
+ * messages. Polls at the given interval until `hasPendingMessages()` returns
+ * true. The caller should race this against the agent completion / timeout.
+ */
+export declare function pollPendingMessages(hasPendingMessages: () => boolean, intervalMs?: number): {
+    promise: Promise<void>;
+    cancel: () => void;
+};

package/dist/wait.js

@@ -5,10 +5,15 @@ export function formatWaitTimeout(seconds) {
     return m > 0 ? `${m}m${s > 0 ? ` ${s}s` : ""}` : `${s}s`;
 }
 /**
- * Race an agent completion promise against the configured wait timeout and the
- * parent abort signal. The subagent is never aborted here.
+ * Race an agent completion promise against the configured wait timeout, the
+ * parent abort signal, and an optional pending-message check. The subagent is
+ * never aborted here.
+ *
+ * @param pendingCheck - Optional promise that resolves when the parent session
+ *   has queued user messages waiting to be delivered. When it resolves, the
+ *   wait ends early so the parent turn can process the incoming message.
  */
-export function raceWait(promise, signal, timeoutSeconds) {
+export function raceWait(promise, signal, timeoutSeconds, pendingCheck) {
     return new Promise((resolve) => {
         let settled = false;
         const finish = (outcome) => {
@@ -23,6 +28,7 @@ export function raceWait(promise, signal, timeoutSeconds) {
         const onAbort = () => finish("aborted");
         signal?.addEventListener("abort", onAbort, { once: true });
         promise.then(() => finish("completed"));
+        pendingCheck?.then(() => finish("pending_message"));
     });
 }
 /** Message returned when a wait ends with the agent still running. */
@@ -33,5 +39,44 @@ export function waitTimeoutMessage(outcome, timeoutSeconds) {
     if (outcome === "aborted") {
         return `Agent is still running. The wait was cancelled by the user (parent turn aborted). The subagent was NOT stopped — it continues in the background.\nCall get_subagent_result with wait: true again to keep waiting, use peek to check progress, or omit wait to check status.`;
     }
+    if (outcome === "pending_message") {
+        return `Agent is still running. The wait was interrupted by an incoming user message. The subagent was NOT stopped — it continues in the background.\nThe queued message will be delivered after this tool returns.\nCall get_subagent_result with wait: true again to keep waiting, use peek to check progress, or omit wait to check status.`;
+    }
     return "Agent is still running. Use peek to check recent progress, wait: true to block until it finishes, or check back later.";
 }
+/**
+ * Create a promise that resolves when the parent session has queued user
+ * messages. Polls at the given interval until `hasPendingMessages()` returns
+ * true. The caller should race this against the agent completion / timeout.
+ */
+export function pollPendingMessages(hasPendingMessages, intervalMs = 1000) {
+    let settled = false;
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    // Check immediately in case a message arrived between the tool call
+    // start and this poll setup.
+    if (hasPendingMessages()) {
+        settled = true;
+        resolve();
+        return { promise, cancel: () => { } };
+    }
+    const timer = setInterval(() => {
+        if (settled)
+            return;
+        if (hasPendingMessages()) {
+            settled = true;
+            clearInterval(timer);
+            resolve();
+        }
+    }, intervalMs);
+    return {
+        promise,
+        cancel: () => {
+            if (!settled) {
+                settled = true;
+                clearInterval(timer);
+                resolve();
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-code/pi-subagents",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "clankercode",
   "license": "MIT",

package/src/agent-manager.ts

@@ -90,6 +90,10 @@ interface SpawnOptions {
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
   onTextDelta?: (delta: string, fullText: string) => void;
+  /** Build a per-agent output file path before the agent can complete. */
+  outputFileForAgent?: (agentId: string) => string;
+  /** Called after the output file path is attached to the record. */
+  onOutputFileCreated?: (path: string, agentId: string) => void;
   /** Called when the agent session is created (for accessing session stats). */
   onSessionCreated?: (session: AgentSession) => void;
   /** Called at the end of each agentic turn with the cumulative count. */
@@ -185,6 +189,10 @@ export class AgentManager {
       depth,
       parentAgentId: options.parentAgentId,
     };
+    if (options.outputFileForAgent) {
+      record.outputFile = options.outputFileForAgent(id);
+      options.onOutputFileCreated?.(record.outputFile, id);
+    }
     this.agents.set(id, record);
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };

package/src/bounded-output.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared caps for tool responses that may otherwise flood the parent context.
+ * Full subagent logs remain available via the per-agent output file.
+ */
+
+export const MAX_RESULT_CHARS = 20_000;
+export const MAX_VERBOSE_CHARS = 20_000;
+export const MAX_PEEK_CHARS = 20_000;
+export const MAX_PEEK_LINES = 200;
+
+export interface LimitedText {
+  text: string;
+  truncated: boolean;
+  omittedChars: number;
+}
+
+export function limitText(text: string, maxChars: number): LimitedText {
+  if (text.length <= maxChars) {
+    return { text, truncated: false, omittedChars: 0 };
+  }
+  return {
+    text: text.slice(0, maxChars),
+    truncated: true,
+    omittedChars: text.length - maxChars,
+  };
+}
+
+export function clampPeekLines(lines: number | undefined): number {
+  if (typeof lines !== "number" || !Number.isFinite(lines) || lines < 1) return 20;
+  return Math.min(Math.floor(lines), MAX_PEEK_LINES);
+}
+
+export function formatOutputFileHint(outputFile?: string): string {
+  return outputFile ? ` Full output/log: ${outputFile}` : "";
+}

package/src/index.ts

@@ -23,6 +23,7 @@ import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getCurrentExtensionAgentId, getCurrentExtensionDepth, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { buildAgentToolDescription, getModelLabelFromConfig } from "./agent-tool-description.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
+import { formatOutputFileHint, limitText, MAX_RESULT_CHARS, MAX_VERBOSE_CHARS } from "./bounded-output.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
@@ -54,7 +55,7 @@ import type { WidgetAgentSnapshot, WidgetDisplayMode } from "./ui/agent-widget-t
 import { menuSelect } from "./ui/menu-select.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
-import { formatWaitTimeout, raceWait, type WaitOutcome, waitTimeoutMessage } from "./wait.js";
+import { formatWaitTimeout, pollPendingMessages, raceWait, type WaitOutcome, waitTimeoutMessage } from "./wait.js";
 
 // ---- Shared helpers ----
 
@@ -280,7 +281,7 @@ export default function (pi: ExtensionAPI) {
 
         pi.sendMessage<NotificationDetails>({
           customType: "subagent-notification",
-          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for a bounded preview; inspect the transcript file path for full output when needed.`,
           display: true,
           details,
         }, { deliverAs: "steer", triggerTurn: true });
@@ -953,7 +954,7 @@ export default function (pi: ExtensionAPI) {
         const resumeDetails = { displayName: getDisplayName(record.type), description: record.description, subagentType: record.type, modelName: record.invocation?.modelName };
         return textResult(
           `Agent resumed in background.\nAgent ID: ${record.id}\nType: ${resumeDetails.displayName}\nDescription: ${record.description}\n\n` +
-          `You will be notified when this agent completes.\nUse get_subagent_result to retrieve full results, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`,
+          `You will be notified when this agent completes.\nUse get_subagent_result to inspect bounded result previews, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`,
           buildDetails(resumeDetails, record, state, { status: "background" }),
         );
       }
@@ -987,6 +988,8 @@ export default function (pi: ExtensionAPI) {
           invocation: agentInvocation,
           depth: nextSubagentDepth,
           parentAgentId: extensionAgentId,
+          outputFileForAgent: (agentId) => createOutputFilePath(ctx.cwd, agentId, ctx.sessionManager.getSessionId()),
+          onOutputFileCreated: (outputFile, agentId) => writeInitialEntry(outputFile, agentId, P.prompt!, ctx.cwd),
           ...bgCallbacks,
         });
       } catch (err) {
@@ -997,15 +1000,13 @@ export default function (pi: ExtensionAPI) {
         return retryableResult(h, err instanceof Error ? err.message : String(err), "isolation");
       }
 
-      // Set output file + join mode synchronously after spawn, before the
-      // event loop yields — onSessionCreated is async so this is safe.
+      // Set join mode synchronously after spawn. The output file path is
+      // attached inside AgentManager.spawn(), before the agent can complete.
       const joinMode = resolveJoinMode(defaultJoinMode);
       const record = manager.getRecord(id);
       if (record) {
         record.joinMode = joinMode;
         record.toolCallId = toolCallId;
-        record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
-        writeInitialEntry(record.outputFile, id, P.prompt!, ctx.cwd);
       }
 
       if (joinMode === 'async') {
@@ -1038,7 +1039,7 @@ export default function (pi: ExtensionAPI) {
         `Agent ${isQueued ? "queued" : "started"} in background.\nAgent ID: ${id}\nType: ${displayName}\nDescription: ${P.description}\n` +
         (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
         (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
-        `\nYou will be notified when this agent completes.\nUse get_subagent_result to retrieve full results, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`,
+        `\nYou will be notified when this agent completes.\nUse get_subagent_result to inspect bounded result previews, or steer_subagent to send it messages.\nDo not duplicate this agent's work.`,
         { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
       );
     },
@@ -1063,7 +1064,7 @@ export default function (pi: ExtensionAPI) {
       ),
       verbose: Type.Optional(
         Type.Boolean({
-          description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+          description: "If true, include a bounded preview of the agent's conversation (messages + tool calls). Default: false.",
         }),
       ),
       peek: Type.Optional(
@@ -1076,7 +1077,7 @@ export default function (pi: ExtensionAPI) {
         }),
       ),
     }),
-    execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
+    execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
       const record = manager.getRecord(params.agent_id);
       if (!record) {
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
@@ -1087,7 +1088,7 @@ export default function (pi: ExtensionAPI) {
         const peek = peekAgentOutput(record, params.peek as PeekOptions);
         return textResult(
           peek
-            ? `${peek.text}\n\n---\nUse verbose: true for the full conversation, or omit peek for the complete result.`
+            ? `${peek.text}\n\n---\nUse verbose: true for a bounded conversation preview, or omit peek for a bounded result preview.`
             : "No output yet for this agent.",
         );
       }
@@ -1098,7 +1099,17 @@ export default function (pi: ExtensionAPI) {
       let waitOutcome: WaitOutcome = "completed";
       if (params.wait && record.status === "running" && record.promise) {
         cancelNudge(params.agent_id);
-        waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds());
+        // Poll for queued user messages so we can return early and let the
+        // parent LLM process them immediately instead of blocking for the
+        // full wait timeout.
+        const pending = typeof ctx?.hasPendingMessages === "function"
+          ? pollPendingMessages(() => ctx.hasPendingMessages())
+          : undefined;
+        try {
+          waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds(), pending?.promise);
+        } finally {
+          pending?.cancel();
+        }
         if (waitOutcome === "completed") {
           record.resultConsumed = true;
         }
@@ -1117,15 +1128,26 @@ export default function (pi: ExtensionAPI) {
       let output =
         `Agent: ${record.id}\n` +
         `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
-        `Description: ${record.description}\n\n`;
+        `Description: ${record.description}\n` +
+        (record.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+        `\n`;
 
       if (record.status === "running") {
         // The wait returned while the agent was still running (timeout or abort).
         output += waitTimeoutMessage(waitOutcome, getWaitTimeoutSeconds());
       } else if (record.status === "error") {
-        output += `Error: ${record.error}`;
+        const limited = limitText(record.error ?? "unknown", MAX_RESULT_CHARS);
+        output += `Error: ${limited.text}`;
+        if (limited.truncated) {
+          output += `\n\n---\nError truncated: omitted ${limited.omittedChars} chars. Inspect the output file for the full error when available.${formatOutputFileHint(record.outputFile)}`;
+        }
       } else {
-        output += record.result?.trim() || "No output.";
+        const resultText = record.result?.trim() || "No output.";
+        const limited = limitText(resultText, MAX_RESULT_CHARS);
+        output += limited.text;
+        if (limited.truncated) {
+          output += `\n\n---\nResult truncated: omitted ${limited.omittedChars} chars. Use peek for targeted retrieval, or inspect the output file for the full log.${formatOutputFileHint(record.outputFile)}`;
+        }
       }
 
       // Mark result as consumed — suppresses the completion notification
@@ -1134,11 +1156,15 @@ export default function (pi: ExtensionAPI) {
         cancelNudge(params.agent_id);
       }
 
-      // Verbose: include full conversation
+      // Verbose: include a bounded conversation preview
       if (params.verbose && record.session) {
         const conversation = getAgentConversation(record.session);
         if (conversation) {
-          output += `\n\n--- Agent Conversation ---\n${conversation}`;
+          const limited = limitText(conversation, MAX_VERBOSE_CHARS);
+          output += `\n\n--- Agent Conversation ---\n${limited.text}`;
+          if (limited.truncated) {
+            output += `\n\n---\nAgent conversation truncated: omitted ${limited.omittedChars} chars. Use peek for targeted retrieval, or inspect the output file for the full log.${formatOutputFileHint(record.outputFile)}`;
+          }
         }
       }
 

package/src/notifications.ts

@@ -30,12 +30,14 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 
   const resultPreview = record.result
     ? record.result.length > resultMaxLen
-      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      ? record.result.slice(0, resultMaxLen) + (record.outputFile
+        ? "\n...(truncated, use get_subagent_result for a bounded preview or inspect the transcript file)"
+        : "\n...(truncated, use get_subagent_result for a bounded preview)")
       : record.result
     : "No output.";
   const fullOutputInstruction = record.outputFile
-    ? `Read the full output/log with get_subagent_result for agent ${record.id}, or inspect the transcript file: ${record.outputFile}`
-    : `Read the full output/log with get_subagent_result for agent ${record.id}.`;
+    ? `Read a bounded preview with get_subagent_result for agent ${record.id}, or inspect the full transcript file: ${record.outputFile}`
+    : `Read a bounded preview with get_subagent_result for agent ${record.id}.`;
 
   return [
     `<task-notification>`,
@@ -106,8 +108,8 @@ export function registerSubagentNotificationRenderer(pi: ExtensionAPI): void {
         }
 
         const fullOutputHint = d.outputFile
-          ? `full output: get_subagent_result ${d.id} or transcript: ${d.outputFile}`
-          : `full output: get_subagent_result ${d.id}`;
+          ? `bounded preview: get_subagent_result ${d.id}; full transcript: ${d.outputFile}`
+          : `bounded preview: get_subagent_result ${d.id}`;
         line += "\n  " + theme.fg("muted", fullOutputHint);
 
         return line;

package/src/peek.ts

@@ -15,6 +15,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { clampPeekLines, formatOutputFileHint, limitText, MAX_PEEK_CHARS, MAX_PEEK_LINES } from "./bounded-output.js";
 import type { AgentRecord } from "./types.js";
 
 export interface PeekOptions {
@@ -35,9 +36,6 @@ export interface PeekResult {
   source: "outputFile" | "result";
 }
 
-/** Default number of tail lines when neither `after` nor `lines` is given. */
-const DEFAULT_LINES = 20;
-
 /**
  * Produce a peek view of an agent's output. Returns null when there is no
  * source content at all (the caller renders a "no output yet" message).
@@ -48,27 +46,39 @@ export function peekAgentOutput(record: AgentRecord, opts: PeekOptions = {}): Pe
 
   const regex = opts.regex ? compileRegex(opts.regex) : undefined;
   const after = typeof opts.after === "number" ? opts.after : -1;
-  const tail = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+  const tail = clampPeekLines(opts.lines);
 
   // Index each source line with its original position (1-based for display).
   const indexed = lines.map((text, i) => ({ no: i + 1, text }));
 
   // Filter-then-select.
   const filtered = regex ? indexed.filter((l) => regex.test(l.text)) : indexed;
-  const selected =
-    after >= 0
-      ? filtered.filter((l) => l.no > after)
-      : filtered.slice(-tail);
+  const matching = after >= 0 ? filtered.filter((l) => l.no > after) : filtered;
+  const selected = after >= 0 ? matching.slice(0, MAX_PEEK_LINES) : matching.slice(-tail);
+  const lineLimited = matching.length > selected.length;
 
   const totalLines = lines.length;
   const isRunning = record.status === "running" || record.status === "queued";
   const source: PeekResult["source"] =
     isRunning && record.outputFile && existsSync(record.outputFile) ? "outputFile" : "result";
 
-  const header = buildHeader(opts, selected.length, totalLines, source);
+  const header = buildHeader(opts, selected.length, totalLines, source, tail, lineLimited, matching.length);
   const body = selected.map((l) => `[${l.no}] ${l.text}`).join("\n");
+  const limited = limitText(body, MAX_PEEK_CHARS);
+  const lastLine = selected.at(-1)?.no;
+  const notices: string[] = [];
+  if (lineLimited && lastLine !== undefined) {
+    notices.push(`Peek limited to ${MAX_PEEK_LINES} lines from ${matching.length} matching lines. Use peek.after: ${lastLine} to continue.`);
+  }
+  if (limited.truncated) {
+    notices.push(`Peek output truncated by ${limited.omittedChars} chars. Use a smaller lines value or regex filter.${formatOutputFileHint(record.outputFile)}`);
+  }
 
-  return { text: `${header}\n\n${body}`, totalLines, source };
+  return {
+    text: `${header}\n\n${limited.text}${notices.length ? `\n\n---\n${notices.join("\n")}` : ""}`,
+    totalLines,
+    source,
+  };
 }
 
 /** Read the most useful text lines from the agent's output. */
@@ -141,13 +151,16 @@ function buildHeader(
   shown: number,
   total: number,
   source: PeekResult["source"],
+  tail: number,
+  lineLimited: boolean,
+  matching: number,
 ): string {
   const parts: string[] = [];
   if (typeof opts.after === "number") {
     parts.push(`after line number ${opts.after}`);
+    if (lineLimited) parts.push(`limited to ${MAX_PEEK_LINES} lines from ${matching} matching lines`);
   } else {
-    const n = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
-    parts.push(`last ${n} lines`);
+    parts.push(`last ${tail} lines`);
   }
   if (opts.regex) parts.push(`filtered by regex /${opts.regex}/`);
   parts.push(`of ${total} total (${source === "outputFile" ? "live output file" : "result"})`);

package/src/wait.ts

@@ -1,4 +1,4 @@
-export type WaitOutcome = "completed" | "timeout" | "aborted";
+export type WaitOutcome = "completed" | "timeout" | "aborted" | "pending_message";
 
 /** Human-readable "Xm Ys" for a duration in seconds. */
 export function formatWaitTimeout(seconds: number): string {
@@ -8,13 +8,19 @@ export function formatWaitTimeout(seconds: number): string {
 }
 
 /**
- * Race an agent completion promise against the configured wait timeout and the
- * parent abort signal. The subagent is never aborted here.
+ * Race an agent completion promise against the configured wait timeout, the
+ * parent abort signal, and an optional pending-message check. The subagent is
+ * never aborted here.
+ *
+ * @param pendingCheck - Optional promise that resolves when the parent session
+ *   has queued user messages waiting to be delivered. When it resolves, the
+ *   wait ends early so the parent turn can process the incoming message.
  */
 export function raceWait(
   promise: Promise<string>,
   signal: AbortSignal | undefined,
   timeoutSeconds: number,
+  pendingCheck?: Promise<void>,
 ): Promise<WaitOutcome> {
   return new Promise((resolve) => {
     let settled = false;
@@ -29,6 +35,7 @@ export function raceWait(
     const onAbort = () => finish("aborted");
     signal?.addEventListener("abort", onAbort, { once: true });
     promise.then(() => finish("completed"));
+    pendingCheck?.then(() => finish("pending_message"));
   });
 }
 
@@ -40,5 +47,50 @@ export function waitTimeoutMessage(outcome: WaitOutcome, timeoutSeconds: number)
   if (outcome === "aborted") {
     return `Agent is still running. The wait was cancelled by the user (parent turn aborted). The subagent was NOT stopped — it continues in the background.\nCall get_subagent_result with wait: true again to keep waiting, use peek to check progress, or omit wait to check status.`;
   }
+  if (outcome === "pending_message") {
+    return `Agent is still running. The wait was interrupted by an incoming user message. The subagent was NOT stopped — it continues in the background.\nThe queued message will be delivered after this tool returns.\nCall get_subagent_result with wait: true again to keep waiting, use peek to check progress, or omit wait to check status.`;
+  }
   return "Agent is still running. Use peek to check recent progress, wait: true to block until it finishes, or check back later.";
 }
+
+/**
+ * Create a promise that resolves when the parent session has queued user
+ * messages. Polls at the given interval until `hasPendingMessages()` returns
+ * true. The caller should race this against the agent completion / timeout.
+ */
+export function pollPendingMessages(
+  hasPendingMessages: () => boolean,
+  intervalMs = 1000,
+): { promise: Promise<void>; cancel: () => void } {
+  let settled = false;
+  let resolve!: () => void;
+  const promise = new Promise<void>((r) => { resolve = r; });
+
+  // Check immediately in case a message arrived between the tool call
+  // start and this poll setup.
+  if (hasPendingMessages()) {
+    settled = true;
+    resolve();
+    return { promise, cancel: () => {} };
+  }
+
+  const timer = setInterval(() => {
+    if (settled) return;
+    if (hasPendingMessages()) {
+      settled = true;
+      clearInterval(timer);
+      resolve();
+    }
+  }, intervalMs);
+
+  return {
+    promise,
+    cancel: () => {
+      if (!settled) {
+        settled = true;
+        clearInterval(timer);
+        resolve();
+      }
+    },
+  };
+}