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

package/README.md

@@ -29,7 +29,7 @@ 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`.
 
 ## Configuration
 
@@ -164,7 +164,7 @@ example:
   "minimalSubagents": {
     "baseToolset": ["context_*"],
     "readToolset": ["read", "grep", "find", "ls"],
-    "modifyToolset": ["bash", "edit", "write", "lsp", "dap"]
+    "modifyToolset": ["bash", "edit", "write", "lsp_*", "dap_*"]
   }
 }
 ```
@@ -203,8 +203,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
@@ -260,7 +260,11 @@ 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, queued for the recipient, 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
@@ -323,6 +327,10 @@ 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
 
 In TUI mode, `/subagents` or `/subagents status` opens a large, centered,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.11.0",
+  "version": "0.12.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-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-tools.ts

@@ -130,13 +130,31 @@ function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   };
 }
 
-function failedStructuredOperation(prefix: string, result: DeleteResult): never {
-  const json = JSON.stringify(result);
-  const truncated = truncateHead(json, {
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxLines: DEFAULT_MAX_LINES,
-  });
-  throw new Error(withTroubleshootingHint(`${prefix}: ${truncated.content}`));
+/**
+ * Report a failed operation that still carries declared output: the model sees an error and
+ * codemode scripts receive `structuredContent` instead of a data-less rejection.
+ */
+function failedStructuredToolResult<TDetails extends CoordinatorToolResultDetails>(
+  prefix: string,
+  result: TDetails,
+  options: { troubleshootingHint: boolean },
+): AgentToolResult<TDetails> & { isError: true } {
+  const success = structuredToolResult(result);
+  const text = `${prefix}:\n${textOf(success)}`;
+  return {
+    ...success,
+    content: [
+      {
+        type: "text" as const,
+        text: options.troubleshootingHint ? withTroubleshootingHint(text) : text,
+      },
+    ],
+    isError: true,
+  };
+}
+
+function textOf(result: AgentToolResult<unknown>): string {
+  return result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
 }
 
 function callerSourceTurnId(
@@ -164,6 +182,12 @@ export function createCoordinatorToolDefinitions(
     promptSnippet: "Spawn a persistent child with a prefix-free root-child ID",
     promptGuidelines: modelRolePromptGuidelines,
     parameters: options.schemas.subagent,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async execute(_toolCallId, parameters, _signal, _onUpdate, context) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.spawn(
@@ -191,6 +215,12 @@ export function createCoordinatorToolDefinitions(
       "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued for the recipient, or failed.",
     promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
     parameters: options.schemas.agent_message,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
     async execute(toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.sendAgentMessage(
@@ -201,7 +231,12 @@ export function createCoordinatorToolDefinitions(
           },
           callerSourceTurnId(options.coordinator, options.callerId, toolCallId),
         );
-        return structuredToolResult(result);
+        return result.disposition === "failed"
+          ? failedStructuredToolResult("Minimal subagents message delivery failed", result, {
+              // The coordinator already appends the hint to `error`.
+              troubleshootingHint: false,
+            })
+          : structuredToolResult(result);
       });
     },
     ...createCoordinatorToolRendering("agent_message"),
@@ -214,6 +249,12 @@ export function createCoordinatorToolDefinitions(
       "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters, signal, onUpdate) {
       const startedAt = Date.now();
       const updateWaitingResult = () =>
@@ -262,6 +303,12 @@ export function createCoordinatorToolDefinitions(
       "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, () =>
         structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
@@ -277,6 +324,12 @@ export function createCoordinatorToolDefinitions(
       "Abort active work for one direct child while preserving sessions for later continuation. Recursive cancellation includes its subtree and defaults to true.",
     promptSnippet: "Cancel active subagent turns without deleting sessions",
     parameters: options.schemas.subagent_cancel,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () =>
         structuredToolResult(
@@ -298,6 +351,12 @@ export function createCoordinatorToolDefinitions(
       "Delete one direct child's persistent session and retain durable ID tombstones. Recursive deletion includes its subtree and defaults to true.",
     promptSnippet: "Delete subagent sessions and tombstone their IDs",
     parameters: options.schemas.subagent_delete,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.delete(
@@ -309,7 +368,9 @@ export function createCoordinatorToolDefinitions(
           options.onAttention?.(
             `Minimal subagents deletion partially failed for ${parameters.agent_id}`,
           );
-          failedStructuredOperation("Minimal subagents deletion partially failed", result);
+          return failedStructuredToolResult("Minimal subagents deletion partially failed", result, {
+            troubleshootingHint: true,
+          });
         }
         return structuredToolResult(result);
       });