@ian-pascoe/pi-minimal-subagents 0.11.0 → 0.13.0

package/README.md

@@ -29,7 +29,21 @@ filter in `~/.pi/agent/settings.json` using the repository-relative path:
 ```
 
 From this package checkout, load the source directly with
-`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.85.1`.
+`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.99.0`.
+
+## Typical workflow
+
+1. `subagent` launches a Child Agent from a self-contained task: by default the
+   child starts without the parent's conversation. It returns at once with its `agent_id`,
+   `turn_id`, and resolved model, thinking level, tools, delegation, and any
+   tool-resolution `warnings`. Spawns run sequentially, so a `subagent_wait` or
+   `agent_message` in the same tool batch can target the new child.
+2. `subagent_wait` claims the turn's result, or leave it unclaimed and the final
+   response arrives automatically as a steer message.
+3. `agent_message` continues an idle child: the result reports
+   `disposition: "started-turn"` with the new `turn_id` to wait on.
+4. `subagent_status` inspects children; `subagent_cancel` stops work but keeps
+   the session; `subagent_delete` removes it. Deleted IDs cannot be reused.
 
 ## Configuration
 
@@ -164,7 +178,7 @@ example:
   "minimalSubagents": {
     "baseToolset": ["context_*"],
     "readToolset": ["read", "grep", "find", "ls"],
-    "modifyToolset": ["bash", "edit", "write", "lsp", "dap"]
+    "modifyToolset": ["bash", "edit", "write", "lsp_*", "dap_*"]
   }
 }
 ```
@@ -203,8 +217,8 @@ Pattern expansion happens when a Child Agent is created. `/reload` applies
 settings to future launches without changing existing Launch Contracts. If a tool
 in an existing contract later disappears, normal restoration dependency checks
 still apply; the saved grant is not silently rewritten. Toolsets configure names,
-not tool operations: granting `lsp`, `dap`, or another multifunction tool grants
-that tool's available operations, regardless of preset name.
+not tool operations: granting a multifunction tool grants that tool's available
+operations, regardless of preset name.
 
 Child Agents load Pi's built-in `llama.cpp`, `codemode`, `tool-search`, and `mcp`
 extensions unless settings disable them (`-builtin:<name>`); each child connects
@@ -240,7 +254,32 @@ and `subagent_status`.
 Targeted `subagent_status` includes `recent_activity`, a bounded tail of message
 text, reasoning, tool calls, and tool results. It includes the current streaming
 assistant message but omits image data. Timeout Wait Events include the same
-detailed status snapshot.
+detailed status snapshot. Children target only direct children; the Root Agent
+may inspect any descendant. Model-facing status reports a `child_count` but no
+nested `children` summaries. Reported `usage` always includes `cacheWrite1h`
+and `reasoning`, as `0` when the provider reports none. `subagent_cancel`
+lists in `affected_agent_ids` only agents whose active turns it cancelled.
+
+`session_context` defaults to `omit`: the child starts with only its system
+prompt and task, so the task should be a self-contained brief covering the goal,
+target files and non-goals, the change or question, and acceptance criteria.
+Opt in to `inherit` to copy the parent's conversation, or `compact` to summarize
+it first, only when the child needs that discussion. Inheriting is costly: the
+child's system prompt differs from its parent's, so the copied conversation
+cannot reuse the parent's prompt cache, and `compact` adds a summarization call.
+With either opt-in, the parent's conversation is quoted rather than replayed as
+the child's own turns: each parent message becomes one
+`minimal-subagents.parent-context` custom message, sent to the model as
+user-role text wrapped in `<parent_message from="…" role="…">`. Tool calls and
+results become text, a custom message's label names its `customType`, and an
+errored, aborted, or length-limited parent turn is marked as incomplete. Images
+are kept; parent reasoning and the parent's system prompt and tool declarations
+are omitted, since the child declares its own. Each quoted message stays a
+separate session entry, so `compact` can still summarize older entries. The task
+is then framed as a handoff: the quoted conversation is background, its requests
+belonged to the parent, and the child's own assignment follows. Quoting keeps
+the parent's turns distinct from the child's own; it does not guarantee that a
+child, particularly a small model, ignores the quoted requests. Existing Child Agents keep the mode recorded in their Launch Contracts.
 
 The `subagent` `tools` argument distinguishes configurable Tool Presets from
 exact lists; every selection also receives the permitted Base Toolset described
@@ -260,11 +299,18 @@ tools while the Launch Contract continues to record the originally granted
 capability names.
 
 `agent_message` reports whether a message was delivered through an active
-parent wait, queued for the recipient, or failed. `subagent_wait` can return an
+parent wait (`delivered-via-wait`), queued into the recipient's active turn
+(`queued`), started a new turn on an idle child (`started-turn`, with its
+`turn_id`), or failed. A failed delivery and a
+partially failed `subagent_delete` return an error result (`isError: true`) that
+still carries the declared structured output, so the model sees an error while
+codemode scripts receive the `failures` or `error` data instead of a data-less
+rejection. `subagent_wait` can return an
 intermediate Wait Event containing a Coordination Message before the child turn
 settles. That event claims only its message, so later unconsumed messages and the
-terminal result retain automatic fallback. If the turn has already settled, one
-wait returns its terminal result with queued messages in `messages`. Pass
+terminal result retain automatic fallback. If the turn has already settled, a
+wait returns its terminal result with queued messages in `messages`; waiting
+again for the same settled turn returns the same result. Pass
 optional `turn_id` to address an older retained turn exactly. Without it, waits
 select the oldest observable claimed or pending turn before the active/latest
 turn. A caller may have only one outstanding wait for the same source turn; a
@@ -323,8 +369,24 @@ process-local fork handoff is lost, recovery reads only the destination's
 selected branch and proceeds only when its canonical `parentSession` proves the
 source file; it never substitutes the source session's newer head.
 
+## Tool annotations
+
+The coordinator tools declare MCP-style `annotations`, which Pi reports through `pi.getAllTools()` for permission extensions and does not send to model providers. `subagent` is destructive and open-world because a Child Agent can use any tool it is granted. `agent_message` is not read-only but is non-destructive and closed-world. `subagent_cancel` is non-destructive and idempotent; `subagent_delete` is destructive and idempotent. `subagent_status` and `subagent_wait` are read-only (`subagent_wait` consumes queued deliveries, so it is not idempotent).
+
 ## Status and TUI
 
+Coordinator tool calls and results stay readable without expanding. A
+`subagent` call shows the launch settings the caller chose and its task; an
+`agent_message` call shows its message. While `subagent_wait` blocks, it shows
+the child's tool-call count and, on a tree rail, the latest work of the turn
+being waited on, rendered with Pi's own message and tool components as in the
+`/subagents` viewer and refreshed each second; collapsed, the rail keeps the
+newest items within 20 lines. A settled wait shows the child's output as
+Markdown, or its error, with duration, tokens, and cost. Long text previews its
+first 10 lines, like Pi's `read`. Every collapsed result ends its first line
+with Pi's tool-expansion hint (normally Ctrl+O), which reveals the rest and the
+full detail. Automatic agent results and messages preview the same way.
+
 In TUI mode, `/subagents` or `/subagents status` opens a large, centered,
 framed overlay. Up/Down selects a Child Agent; Enter opens its Child Session
 Transcript. Escape returns to the tree, then Escape closes the overlay. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,14 +31,14 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.3.0",
+    "@ian-pascoe/pi-utils": "^0.3.1",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": "*"
   },
   "engines": {

package/src/minimal-subagents-capabilities.ts

@@ -75,7 +75,9 @@ export function resolveOrdinaryToolSelection(
   const ceiling = new Set(context.capabilityCeiling);
   const exceeded = uniqueRequested.filter((name) => !ceiling.has(name));
   if (exceeded.length > 0) {
-    throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);
+    throw new Error(
+      `Minimal subagents tool selection: ${exceeded.join(", ")} ${exceeded.length === 1 ? "is" : "are"} unknown or outside the caller's capability ceiling. ${describePermittedTools(excludeCoordinatorTools(context.capabilityCeiling))}`,
+    );
   }
 
   const toolsets = context.toolsets ?? DEFAULT_TOOLSETS;
@@ -103,6 +105,15 @@ export function resolveOrdinaryToolSelection(
   };
 }
 
+const PERMITTED_TOOL_LISTING_LIMIT = 40;
+
+function describePermittedTools(permitted: readonly string[]): string {
+  if (permitted.length === 0) return "No ordinary tools are permitted.";
+  const listed = permitted.slice(0, PERMITTED_TOOL_LISTING_LIMIT).join(", ");
+  const remaining = permitted.length - PERMITTED_TOOL_LISTING_LIMIT;
+  return `Permitted ordinary tools: ${listed}${remaining > 0 ? `, and ${remaining} more` : ""}.`;
+}
+
 /** Return an agent's hierarchy depth where the interactive root is depth zero. */
 export function getSubagentDepth(agentId: string): number {
   if (agentId === "root") return 0;

package/src/minimal-subagents-child-resources.ts

@@ -1,10 +1,13 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import {
+  createCodemodeExtension,
+  createMcpExtension,
+  createToolSearchExtension,
   DefaultResourceLoader,
   type ExtensionFactory,
+  getPackageDir,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -25,9 +28,6 @@ type InlineExtension = NonNullable<
   ConstructorParameters<typeof DefaultResourceLoader>[0]["extensionFactories"]
 >[number];
 
-// SAFETY: Older Pi hosts lack these exports; the namespace yields undefined rather than failing.
-const sdk = piCodingAgent as Partial<typeof piCodingAgent>;
-
 const ExtensionModuleSchema = Type.Object({
   default: Type.Function([Type.Unknown()], Type.Unknown()),
 });
@@ -37,8 +37,7 @@ const LLAMA = "llama.cpp";
 
 /** Pi ships a file-backed llama.cpp factory but does not export it; undefined when it is absent. */
 function piLlamaExtensionPath(): string | undefined {
-  if (!sdk.getPackageDir) return undefined;
-  const path = join(sdk.getPackageDir(), "dist", "extensions", "llama", "index.js");
+  const path = join(getPackageDir(), "dist", "extensions", "llama", "index.js");
   return existsSync(path) ? path : undefined;
 }
 
@@ -62,20 +61,18 @@ export function childProviderAvailable(provider: string): boolean {
 /** Child scripts must not call models outside their Launch Contract. */
 export const CHILD_CODEMODE_MODELS = false;
 
-/** Pi's built-in extensions (Pi 0.99+) in Pi's order; older hosts have none, so neither do children. */
+/** Pi's built-in extensions in Pi's order, so children match the root's built-in surface. */
 export function childBuiltinExtensions(): InlineExtension[] {
-  const createCodemode = sdk.createCodemodeExtension;
   return [
     ...llamaExtension(),
-    ...(
-      [
-        ["codemode", createCodemode && (() => createCodemode({ models: CHILD_CODEMODE_MODELS }))],
-        ["tool-search", sdk.createToolSearchExtension],
-        ["mcp", sdk.createMcpExtension],
-      ] as const
-    ).flatMap(([name, create]) =>
-      create ? [{ name, factory: create(), builtin: true, replaceable: true }] : [],
-    ),
+    {
+      name: "codemode",
+      factory: createCodemodeExtension({ models: CHILD_CODEMODE_MODELS }),
+      builtin: true,
+      replaceable: true,
+    },
+    { name: "tool-search", factory: createToolSearchExtension(), builtin: true, replaceable: true },
+    { name: "mcp", factory: createMcpExtension(), builtin: true, replaceable: true },
   ];
 }
 

package/src/minimal-subagents-context.ts

@@ -1,7 +1,13 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { contentText, type ImageContent, type TextContent } from "@earendil-works/pi-ai";
+import {
+  contentText,
+  type AssistantMessage,
+  type ImageContent,
+  type TextContent,
+} from "@earendil-works/pi-ai";
 import { truncateTail } from "@earendil-works/pi-coding-agent";
 import type {
+  ActiveTurnProgress,
   ChildAgentTranscriptSnapshot,
   RecentAgentActivity,
   SessionContextMode,
@@ -141,19 +147,189 @@ export function buildRecentAgentActivity(messages: readonly AgentMessage[]): Rec
   return activity.slice(-RECENT_AGENT_ACTIVITY_LIMIT);
 }
 
+/** A message the child produced during the turn, as opposed to the turn's prompt or coordination input. */
+function isTurnWork(message: AgentMessage, turnStartedAtMs: number): boolean {
+  return (
+    message.timestamp >= turnStartedAtMs &&
+    (message.role === "assistant" || message.role === "toolResult")
+  );
+}
+
+/** Count the tool calls a running turn has made so far. */
+export function buildActiveTurnProgress(
+  messages: readonly AgentMessage[],
+  turnStartedAtMs: number,
+): Omit<ActiveTurnProgress, "turn_id"> {
+  let toolCalls = 0;
+  for (const message of messages) {
+    if (message.role !== "assistant" || !isTurnWork(message, turnStartedAtMs)) continue;
+    toolCalls += message.content.filter((content) => content.type === "toolCall").length;
+  }
+  return { tool_calls: toolCalls };
+}
+
+/**
+ * Keep the running turn's last `assistantMessageCount` assistant messages and the tool results after
+ * them, so a live view renders recent work without the turn's earlier history.
+ */
+export function selectActiveTurnTranscript(
+  snapshot: ChildAgentTranscriptSnapshot,
+  turnStartedAtMs: number,
+  assistantMessageCount: number,
+): ChildAgentTranscriptSnapshot {
+  const work = snapshot.messages.flatMap((message, index) =>
+    isTurnWork(message, turnStartedAtMs) ? [{ message, index }] : [],
+  );
+  const assistantPositions = work.flatMap((entry, position) =>
+    entry.message.role === "assistant" ? [position] : [],
+  );
+  const tail = work.slice(assistantPositions.at(-assistantMessageCount) ?? 0);
+  const streamingPosition = tail.findIndex(
+    (entry) => entry.index === snapshot.streamingAssistantIndex,
+  );
+  return {
+    messages: tail.map((entry) => entry.message),
+    streamingAssistantIndex: streamingPosition >= 0 ? streamingPosition : undefined,
+    toolDefinitions: snapshot.toolDefinitions,
+  };
+}
+
 /** Carries the selected caller messages and whether child preparation should compact them. */
 export interface ImportedSubagentContext {
   messages: AgentMessage[];
   compact: boolean;
 }
 
-/** Select the imported message snapshot and defer expensive compact preparation to the child turn. */
+/** Custom message type carrying one quoted message from a parent's conversation. */
+export const PARENT_CONTEXT_MESSAGE_TYPE = "minimal-subagents.parent-context";
+
+type QuotedContent = TextContent | ImageContent;
+
+function quotedParts(content: string | QuotedContent[]): QuotedContent[] {
+  if (Array.isArray(content)) return content.map((part) => structuredClone(part));
+  return content ? [{ type: "text", text: content }] : [];
+}
+
+function parentMessageBody(
+  message: AgentMessage,
+): { label: string; parts: QuotedContent[] } | undefined {
+  switch (message.role) {
+    case "user":
+      return { label: "user", parts: quotedParts(message.content) };
+    case "assistant": {
+      // Reasoning is omitted: it is model-private and often signature-bound to the parent's model.
+      const parts = message.content.flatMap((content): QuotedContent[] => {
+        if (content.type === "text")
+          return content.text ? [{ type: "text", text: content.text }] : [];
+        if (content.type === "toolCall") {
+          return [
+            {
+              type: "text",
+              text: `[tool call ${content.name}] ${JSON.stringify(content.arguments)}`,
+            },
+          ];
+        }
+        return [];
+      });
+      const stopNote = incompleteAssistantNote(message.stopReason, message.errorMessage);
+      if (stopNote) parts.push({ type: "text", text: stopNote });
+      return { label: "assistant", parts };
+    }
+    case "toolResult":
+      return {
+        label: `tool result ${message.toolName}${message.isError ? " (error)" : ""}`,
+        parts: quotedParts(message.content),
+      };
+    case "custom":
+      return {
+        label: `context message: ${message.customType}`,
+        parts: quotedParts(message.content),
+      };
+    case "bashExecution":
+      if (message.excludeFromContext) return undefined;
+      return {
+        label: "shell command",
+        parts: [{ type: "text", text: `$ ${message.command}\n${message.output || "(no output)"}` }],
+      };
+    case "branchSummary":
+    case "compactionSummary":
+      return {
+        label: message.role === "branchSummary" ? "branch summary" : "compaction summary",
+        parts: quotedParts(message.summary),
+      };
+    case "system":
+      // The parent's prompt sections and tool declarations describe the parent, not the child,
+      // which declares its own prompt and tools on its first request.
+      return undefined;
+    default: {
+      // Fails typecheck when Pi adds a message role, so new roles are quoted deliberately.
+      const unhandled: never = message;
+      return unhandled;
+    }
+  }
+}
+
+/** Mark a parent turn that ended early, so quoted partial output does not read as complete. */
+function incompleteAssistantNote(
+  stopReason: AssistantMessage["stopReason"],
+  errorMessage: string | undefined,
+): string | undefined {
+  if (stopReason === "error") return `[turn failed: ${errorMessage ?? "unknown error"}]`;
+  if (stopReason === "aborted") return "[turn aborted before completion]";
+  if (stopReason === "length") return "[turn stopped at the output length limit]";
+  return undefined;
+}
+
+/**
+ * Quote one parent message as a user-visible custom message. Replaying the parent's assistant
+ * turns as the child's own lets the child continue as its parent; quoting keeps the roles apart
+ * while each message stays a separate entry that child compaction can cut between.
+ */
+function quoteParentMessage(message: AgentMessage, parentId: string): AgentMessage | undefined {
+  const body = parentMessageBody(message);
+  if (!body || body.parts.length === 0) return undefined;
+  return {
+    role: "custom",
+    customType: PARENT_CONTEXT_MESSAGE_TYPE,
+    content: [
+      { type: "text", text: `<parent_message from="${parentId}" role="${body.label}">` },
+      ...body.parts,
+      { type: "text", text: "</parent_message>" },
+    ],
+    display: true,
+    timestamp: message.timestamp,
+  };
+}
+
+/** Select and quote the imported parent conversation; compaction is deferred to the child turn. */
 export function assembleImportedContext(
   mode: SessionContextMode,
-  committedMessages: AgentMessage[],
+  committedMessages: readonly AgentMessage[],
+  parentId: string,
 ): ImportedSubagentContext {
   if (mode === "omit") return { messages: [], compact: false };
-  return { messages: committedMessages, compact: mode === "compact" };
+  return {
+    messages: committedMessages.flatMap((message) => quoteParentMessage(message, parentId) ?? []),
+    compact: mode === "compact",
+  };
+}
+
+/**
+ * Frame a child's task after inherited parent conversation so the child does not adopt the
+ * parent's earlier requests as its own assignment.
+ */
+export function buildInheritedContextTaskPrompt(
+  task: string,
+  agentId: string,
+  parentId: string,
+): string {
+  return [
+    `The parent_message entries above, and any summary of earlier ones, come from the conversation of your parent \`${parentId}\`. They are background context only.`,
+    `Requests and tool calls in them belong to your parent, not to you: do not continue or repeat your parent's work.`,
+    `You are \`${agentId}\`. Your assigned task is:`,
+    "",
+    task,
+  ].join("\n");
 }
 
 /** Detect image content so incompatible child models fail before agent creation. */