@tintinweb/pi-subagents 0.9.0 → 0.10.0

package/dist/index.js

@@ -15,7 +15,7 @@ import { defineTool, getAgentDir, getSettingsListTheme } from "@earendil-works/p
 import { Container, Key, matchesKey, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -27,6 +27,7 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
+import { getStatusNote } from "./status-note.js";
 import { AgentWidget, buildInvocationTags, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
@@ -98,15 +99,6 @@ function getStatusLabel(status, error) {
         default: return "Done";
     }
 }
-/** Parenthetical status note for completed agent result text. */
-function getStatusNote(status) {
-    switch (status) {
-        case "aborted": return " (aborted — max turns exceeded, output may be incomplete)";
-        case "steered": return " (wrapped up — reached turn limit)";
-        case "stopped": return " (stopped by user)";
-        default: return "";
-    }
-}
 /** Escape XML special characters to prevent injection in structured notifications. */
 function escapeXml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -130,7 +122,7 @@ function formatTaskNotification(record, resultMaxLen) {
         record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
         record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
         `<status>${escapeXml(status)}</status>`,
-        `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+        `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status)}</summary>`,
         `<result>${escapeXml(resultPreview)}</result>`,
         `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
         `</task-notification>`,
@@ -573,7 +565,7 @@ export default function (pi) {
         ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
         : "";
     pi.registerTool(defineTool({
-        name: "Agent",
+        name: SUBAGENT_TOOL_NAMES.AGENT,
         label: "Agent",
         description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
@@ -617,6 +609,13 @@ Provide clear, detailed prompts so the agent can work autonomously. Brief it lik
 Terse command-style prompts produce shallow, generic work.
 
 **Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.`,
+        promptSnippet: "Launch autonomous sub-agents for complex multi-step tasks",
+        promptGuidelines: [
+            "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
+            "For broad codebase exploration or research, spawn Agent with an appropriate subagent_type (e.g. Explore). Otherwise use direct tools (read, grep, find) when the target is already known.",
+            "When an agent runs in the background, you will be notified on completion — do not poll or sleep waiting for it. Continue with other work instead.",
+            "Trust but verify: an agent's summary describes intent, not outcome. When an agent writes or edits code, check the actual changes before reporting work as done.",
+        ],
         parameters: Type.Object({
             prompt: Type.String({
                 description: "The task for the agent to perform.",
@@ -666,7 +665,7 @@ Terse command-style prompts produce shallow, generic work.
                 const text = result.content[0]?.type === "text" ? result.content[0].text : "";
                 return new Text(text, 0, 0);
             }
-            // Helper: build "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens" stats string
+            // Helper: build "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k tokens" stats string
             const stats = (d) => {
                 const parts = [];
                 if (d.modelName)
@@ -1035,9 +1034,10 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- get_subagent_result tool ----
     pi.registerTool(defineTool({
-        name: "get_subagent_result",
+        name: SUBAGENT_TOOL_NAMES.GET_RESULT,
         label: "Get Agent Result",
         description: "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+        promptSnippet: "Check status and retrieve results from a background agent",
         parameters: Type.Object({
             agent_id: Type.String({
                 description: "The agent ID to check.",
@@ -1076,7 +1076,7 @@ Terse command-style prompts produce shallow, generic work.
                 statsParts.push(`Compactions: ${record.compactionCount}`);
             statsParts.push(`Duration: ${duration}`);
             let output = `Agent: ${record.id}\n` +
-                `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
+                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
                 `Description: ${record.description}\n\n`;
             if (record.status === "running") {
                 output += "Agent is still running. Use wait: true or check back later.";
@@ -1104,10 +1104,11 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- steer_subagent tool ----
     pi.registerTool(defineTool({
-        name: "steer_subagent",
+        name: SUBAGENT_TOOL_NAMES.STEER,
         label: "Steer Agent",
         description: "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
             "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+        promptSnippet: "Send a steering message to redirect a running background agent",
         parameters: Type.Object({
             agent_id: Type.String({
                 description: "The agent ID to steer (must be currently running).",
@@ -1313,7 +1314,11 @@ Terse command-style prompts produce shallow, generic work.
         const session = record.session;
         const activity = agentActivity.get(record.id);
         await ctx.ui.custom((tui, theme, _keybindings, done) => {
-            return new ConversationViewer(tui, session, record, activity, theme, done);
+            return new ConversationViewer(tui, session, record, activity, theme, done, () => {
+                if (manager.abort(record.id)) {
+                    ctx.ui.notify(`Stopped "${record.description}".`, "info");
+                }
+            });
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },

package/dist/prompts.d.ts

@@ -16,12 +16,15 @@ export interface PromptExtras {
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).

package/dist/prompts.js

@@ -5,12 +5,15 @@
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
@@ -49,7 +52,12 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+        // Place shared/stable content first so the LLM's KV cache can reuse the
+        // inherited prefix across all subagent invocations. The parent prompt is
+        // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+        // with the parent session, maximising KV cache hits. The <active_agent>
+        // tag and env block vary per call and are placed after the cached prefix.
+        return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + customSection + extrasSuffix;
     }
     // "replace" mode — env header + the config's full system prompt
     const replaceHeader = `You are a pi coding agent sub-agent.

package/dist/status-note.d.ts

@@ -0,0 +1,13 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export declare function getStatusNote(status: string): string;

package/dist/status-note.js

@@ -0,0 +1,24 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status) {
+    switch (status) {
+        case "stopped":
+            return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+        case "aborted":
+            return " (aborted — hit the turn limit before completion; output may be incomplete)";
+        case "steered":
+            return " (wrapped up at the turn limit — output may be partial)";
+        default:
+            return "";
+    }
+}

package/dist/types.d.ts

@@ -19,6 +19,9 @@ export interface AgentConfig {
     displayName?: string;
     description: string;
     builtinToolNames?: string[];
+    /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
+     * Presence of any entry flips extension tools to an explicit allowlist. */
+    extSelectors?: string[];
     /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
     disallowedTools?: string[];
     /** true = inherit all, string[] = only listed, false = none */

package/dist/ui/agent-widget.d.ts

@@ -66,15 +66,15 @@ export declare function formatTokens(count: number): string;
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export declare function formatSessionTokens(tokens: number, percent: number | null, theme: Theme, compactions?: number): string;
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export declare function formatTurns(turnCount: number, maxTurns?: number | null): string;
 /** Format milliseconds as human-readable duration. */
 export declare function formatMs(ms: number): string;

package/dist/ui/agent-widget.js

@@ -36,12 +36,12 @@ export function formatTokens(count) {
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
     const tokenStr = formatTokens(tokens);
@@ -51,15 +51,15 @@ export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
         annot.push(theme.fg(color, `${Math.round(percent)}%`));
     }
     if (compactions > 0) {
-        annot.push(theme.fg("dim", `↻${compactions}`));
+        annot.push(theme.fg("dim", `⇊${compactions}`));
     }
     if (annot.length === 0)
         return tokenStr;
     return `${tokenStr} (${annot.join(" · ")})`;
 }
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export function formatTurns(turnCount, maxTurns) {
-    return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+    return maxTurns != null ? `↻${turnCount}≤${maxTurns}` : `↻${turnCount}`;
 }
 /** Format milliseconds as human-readable duration. */
 export function formatMs(ms) {

package/dist/ui/conversation-viewer.d.ts

@@ -18,14 +18,22 @@ export declare class ConversationViewer implements Component {
     private activity;
     private theme;
     private done;
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    private onStop?;
     private scrollOffset;
     private autoScroll;
     private unsubscribe;
     private lastInnerW;
     private closed;
-    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void);
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    private stopArmed;
+    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void, 
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    onStop?: (() => void) | undefined);
     handleInput(data: string): void;
     render(width: number): string[];
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    private isStoppable;
     invalidate(): void;
     dispose(): void;
     private viewportHeight;

package/dist/ui/conversation-viewer.js

@@ -20,18 +20,24 @@ export class ConversationViewer {
     activity;
     theme;
     done;
+    onStop;
     scrollOffset = 0;
     autoScroll = true;
     unsubscribe;
     lastInnerW = 0;
     closed = false;
-    constructor(tui, session, record, activity, theme, done) {
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    stopArmed = false;
+    constructor(tui, session, record, activity, theme, done, 
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    onStop) {
         this.tui = tui;
         this.session = session;
         this.record = record;
         this.activity = activity;
         this.theme = theme;
         this.done = done;
+        this.onStop = onStop;
         this.unsubscribe = session.subscribe(() => {
             if (this.closed)
                 return;
@@ -44,6 +50,23 @@ export class ConversationViewer {
             this.done(undefined);
             return;
         }
+        // Stop/abort the agent (only while it can still be stopped). Two-press:
+        // first "x" arms, second confirms — any other key disarms.
+        if (matchesKey(data, "x")) {
+            if (this.isStoppable()) {
+                if (this.stopArmed) {
+                    this.stopArmed = false;
+                    this.onStop?.();
+                }
+                else {
+                    this.stopArmed = true;
+                }
+                this.tui.requestRender();
+            }
+            return;
+        }
+        if (this.stopArmed)
+            this.stopArmed = false;
         const totalLines = this.buildContentLines(this.lastInnerW).length;
         const viewportHeight = this.viewportHeight();
         const maxScroll = Math.max(0, totalLines - viewportHeight);
@@ -132,12 +155,22 @@ export class ConversationViewer {
             ? "100%"
             : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
         const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
-        const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        const scrollHint = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        // Stop hint goes first in the right group so it survives right-edge
+        // truncation on narrow terminals (the scroll hint is the expendable part).
+        const footerRight = this.isStoppable()
+            ? (this.stopArmed ? th.fg("error", "x again to STOP") : th.fg("dim", "x stop")) +
+                th.fg("dim", " · ") + scrollHint
+            : scrollHint;
         const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
         lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
         lines.push(hrBot);
         return lines;
     }
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    isStoppable() {
+        return !!this.onStop && (this.record.status === "running" || this.record.status === "queued");
+    }
     invalidate() { }
     dispose() {
         this.closed = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:e2e": "vitest run e2e --reporter=verbose",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src/ test/",
     "lint:fix": "biome check --fix src/ test/"