@clanker-code/pi-subagents 0.10.5 → 0.10.7

package/AGENTS.md

@@ -17,7 +17,17 @@ Every release must:
 3. **Update `README.md` to document any new or changed user-facing features.**
 4. Run and pass: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`.
 5. Commit and push.
-6. User publishes with `npm publish` from a clean `master` checkout.
+6. Push a `vX.Y.Z` tag. The `release.yml` workflow then publishes to npm and creates a GitHub Release automatically.
+
+One-time npm setup for CI publishing:
+
+```bash
+npm trust github @clanker-code/pi-subagents --repo=clankercode/pi-subagents --file=release.yml
+```
+
+If `npm trust` fails, open `https://www.npmjs.com/package/@clanker-code/pi-subagents/access` and add a GitHub Actions trusted publisher for the `release.yml` workflow.
+
+See the general guide at `~/.llm-general/npm-autopublish-via-ci.md` for other repos.
 
 ## Keeping Upstream In Sync
 

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **Release workflow test** — patch bump to verify the tag-driven CI publish and GitHub Release creation.
+
 ## [0.10.5] - 2026-06-21
 
 ### Changed
@@ -23,7 +34,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/RELEASE.md

@@ -21,19 +21,25 @@
    git push
    ```
 
-4. **Create a GitHub release**
-   - Tag the commit matching the version:
-     ```bash
-     git tag vX.Y.Z
-     git push origin vX.Y.Z
-     ```
-   - Open the [GitHub releases page](https://github.com/clankercode/pi-subagents/releases) and create a new release for the tag.
-   - Copy the relevant `[x.y.z]` section from `CHANGELOG.md` into the release notes.
-   - Highlight any breaking changes, fork-specific features, or upgrade notes.
-
-5. **Publish to npm**
+4. **Push the version tag**
+   The `release.yml` workflow publishes to npm and creates the GitHub Release automatically:
    ```bash
-   npm publish
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
    ```
 
+5. **Verify**
+   - Check the [Actions run](https://github.com/clankercode/pi-subagents/actions) succeeded.
+   - Confirm the package version appears on npm: `npm view @clanker-code/pi-subagents`.
+   - Confirm the GitHub Release has the changelog notes.
+
+One-time npm trusted-publisher setup:
+```bash
+npm trust github @clanker-code/pi-subagents --repo=clankercode/pi-subagents --file=release.yml
+```
+
+If `npm trust` fails, open `https://www.npmjs.com/package/@clanker-code/pi-subagents/access` and add a GitHub Actions trusted publisher for the `release.yml` workflow.
+
+See `~/.llm-general/npm-autopublish-via-ci.md` for general instructions.
+
 > Note: `prepublishOnly` already runs lint, typecheck, tests, and build before publishing.

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";
@@ -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." })),
@@ -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
@@ -964,27 +965,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-code/pi-subagents",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "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";
@@ -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(
@@ -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.",
         );
       }
@@ -1117,15 +1118,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 +1146,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)}`;
+          }
         }
       }