@ian-pascoe/pi-minimal-subagents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Minimal Subagents
+
+## Install and load
+
+Install the package from npm:
+
+```bash
+pi install npm:@ian-pascoe/pi-minimal-subagents
+```
+
+Installing the Git collection enables every extension in the repository:
+
+```bash
+pi install git:github.com/ian-pascoe/pi-extensions
+```
+
+To select only Minimal Subagents from that Git package, set its extension
+filter in `~/.pi/agent/settings.json` using the repository-relative path:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/ian-pascoe/pi-extensions",
+      "extensions": ["packages/pi-minimal-subagents/src/index.ts"]
+    }
+  ]
+}
+```
+
+From this package checkout, load the source directly with
+`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.84.1`.
+
+## Configuration
+
+Configure the extension in Pi's standard settings files:
+
+- global: `~/.pi/agent/settings.json`
+- project: `./.pi/settings.json`, when the project is trusted
+
+Project values override global values. Run `/reload` after editing either file.
+
+## Model roles
+
+`minimalSubagents.modelRoles` gives the parent agent advisory names for
+eligible models. The extension defines no roles itself, performs no task
+classification, and does not route launches. The parent still passes the
+ordinary `model` argument and chooses `thinking_level` independently.
+
+```json
+{
+  "minimalSubagents": {
+    "modelRoles": {
+      "budget": "opencode-go/glm-5.2",
+      "design": {
+        "model": "opencode-go/kimi-k3",
+        "hint": "UI design, visual critique, and frontend polish"
+      }
+    }
+  }
+}
+```
+
+Role names and hints are trimmed, single-line text. Names may be up to 64
+characters and hints up to 500 characters. Models use canonical
+`provider/model` IDs and must be available under the effective `enabledModels`
+scope. Thinking-level suffixes such as `:xhigh` are invalid here.
+
+Global and project roles merge by name in settings order. Expanded role
+objects merge by field; a project string replaces the whole global entry. A
+project can remove one inherited role with `null`, or clear all inherited
+roles by setting `modelRoles` to `null`.
+
+```json
+{
+  "minimalSubagents": {
+    "modelRoles": {
+      "budget": null
+    }
+  }
+}
+```
+
+Invalid or unavailable entries are omitted. The extension emits one
+consolidated startup warning and keeps every valid role.
+
+## Maximum delegation depth
+
+`minimalSubagents.maxSubagentDepth` is a positive safe integer. It counts
+subagent levels beneath the interactive root: `1` permits root children, `2`
+also permits grandchildren, and so on. The default is `2`.
+
+```json
+{
+  "minimalSubagents": {
+    "maxSubagentDepth": 1
+  }
+}
+```
+
+A trusted project value replaces the global value. Project `null` restores
+the built-in default of `2`. An invalid project value emits a warning and
+leaves a valid global value in effect.
+
+Reloading with a lower depth does not delete existing agents or change their
+launch contracts. Before `/reload` invalidates the old extension runtime, the
+extension waits for active child and root work to settle, then disposes idle
+child runtimes. A deliberately non-settling agent can therefore delay reload
+indefinitely. The new limit controls restored tool availability and future
+spawn attempts; the root retains recursive hierarchy management.
+
+## Capabilities and persistence
+
+Child sessions are persistent Pi sessions. Their launch contracts bound model,
+tool, project-context, session-context, delegation, and depth capabilities at
+creation; reloading does not silently broaden them. The default maximum depth
+is two levels beneath the interactive Root Agent.
+
+The extension registers six coordinator tools for the Root Agent and fanout
+children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
+`subagent_cancel`, and `subagent_delete`. Ordinary non-fanout children receive
+only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
+and `subagent_status`.
+
+Deleting a child first uses the optional `trash` command when available and
+falls back to unlinking its session file. Each Child Agent has a persistent
+JSONL session. Append-only Root Agent Registry entries retain hierarchy and
+Delivery Evidence across reloads. Forking cancels and drains active work, then
+clones child session leaves so the fork receives an independent hierarchy.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ian-pascoe/pi-minimal-subagents",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Persistent nested subagents with bounded delegation for Pi",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-minimal-subagents"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./minimal-subagents-extension.js";

package/src/minimal-subagents-capabilities.ts

@@ -0,0 +1,118 @@
+import type { DelegationMode, ToolSelection } from "./minimal-subagents-types.js";
+
+/** Lists Pi thinking levels in increasing effort order for schema validation and clamping. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+/** Defaults explicit fanout to root → child → grandchild when settings omit a depth. */
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 2;
+/** Lists the six coordinator tools excluded from ordinary child capabilities. */
+export const COORDINATOR_TOOL_NAMES = [
+  "subagent",
+  "agent_message",
+  "subagent_wait",
+  "subagent_status",
+  "subagent_cancel",
+  "subagent_delete",
+] as const;
+
+const READ_TOOL_BUNDLE = ["read", "grep", "find", "ls"];
+const MODIFY_TOOL_BUNDLE = [...READ_TOOL_BUNDLE, "bash", "edit", "write"];
+const THINKING_SUFFIX_PATTERN = /:(?:off|minimal|low|medium|high|xhigh|max)$/;
+
+interface ModelReference {
+  provider: string;
+  id: string;
+}
+
+interface ScopedModelReference {
+  model: ModelReference;
+  thinkingLevel?: string;
+}
+
+/** Remove a recognized Pi thinking suffix without changing model IDs containing other colons. */
+export function stripThinkingSuffix(modelPattern: string): string {
+  return modelPattern.replace(THINKING_SUFFIX_PATTERN, "");
+}
+
+/** Build the authenticated runtime model enum from Pi's already-resolved model scope. */
+export function buildEligibleModelIds(input: {
+  availableModels: readonly ModelReference[];
+  scopedModels: readonly ScopedModelReference[];
+  scopeConfigured?: boolean;
+}): string[] {
+  const scopeConfigured = input.scopeConfigured ?? input.scopedModels.length > 0;
+  const source = scopeConfigured
+    ? input.scopedModels.map((entry) => entry.model)
+    : input.availableModels;
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const model of source) {
+    const canonicalId = stripThinkingSuffix(`${model.provider}/${model.id}`);
+    if (!seen.has(canonicalId)) {
+      seen.add(canonicalId);
+      result.push(canonicalId);
+    }
+  }
+
+  return result;
+}
+
+/** Supplies inherited tools, the ancestor ceiling, and runtime availability for exact tool resolution. */
+export interface ToolResolutionContext {
+  ordinaryTools: readonly string[];
+  capabilityCeiling: readonly string[];
+  availableTools: readonly string[];
+}
+
+/** Resolve an exact ordinary-tool contract and reject missing or over-ceiling capabilities. */
+export function resolveOrdinaryToolSelection(
+  selection: ToolSelection | undefined,
+  context: ToolResolutionContext,
+): string[] {
+  const requested =
+    selection === undefined
+      ? [...context.ordinaryTools]
+      : selection === "none"
+        ? []
+        : selection === "read"
+          ? READ_TOOL_BUNDLE
+          : selection === "modify"
+            ? MODIFY_TOOL_BUNDLE
+            : selection;
+  const uniqueRequested = [...new Set(requested)];
+  const available = new Set(context.availableTools);
+  const ceiling = new Set(context.capabilityCeiling);
+  const missing = uniqueRequested.filter((name) => !available.has(name));
+  if (missing.length > 0) {
+    throw new Error(`Minimal subagents tool resolution: unavailable tool: ${missing.join(", ")}`);
+  }
+
+  const exceeded = uniqueRequested.filter((name) => !ceiling.has(name));
+  if (exceeded.length > 0) {
+    throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);
+  }
+
+  return uniqueRequested;
+}
+
+/** Return an agent's hierarchy depth where the interactive root is depth zero. */
+export function getSubagentDepth(agentId: string): number {
+  if (agentId === "root") return 0;
+  const segments = agentId.split(".").length;
+  return agentId.startsWith("root.") ? segments - 1 : segments;
+}
+
+/** Report whether an explicit fanout contract remains below the configured delegation depth cap. */
+export function canAgentContractSpawn(
+  agentId: string,
+  delegation?: DelegationMode,
+  maxSubagentDepth = DEFAULT_MAX_SUBAGENT_DEPTH,
+): boolean {
+  return delegation === "fanout" && getSubagentDepth(agentId) < maxSubagentDepth;
+}
+
+/** Return ordinary tools only, excluding all six coordinator tools. */
+export function excludeCoordinatorTools(toolNames: readonly string[]): string[] {
+  const coordinatorNames = new Set<string>(COORDINATOR_TOOL_NAMES);
+  return toolNames.filter((name) => !coordinatorNames.has(name));
+}

package/src/minimal-subagents-config.ts

@@ -0,0 +1,217 @@
+import {
+  DEFAULT_MAX_SUBAGENT_DEPTH,
+  stripThinkingSuffix,
+} from "./minimal-subagents-capabilities.js";
+
+const MODEL_ROLE_NAME_MAX_LENGTH = 64;
+const MODEL_ROLE_HINT_MAX_LENGTH = 500;
+
+/** Describes one user-authored advisory model role shown to subagent callers. */
+export interface MinimalSubagentsModelRole {
+  name: string;
+  model: string;
+  hint?: string;
+}
+
+/** Contains the validated minimal subagents settings used by one extension session. */
+export interface ResolvedMinimalSubagentsConfig {
+  maxSubagentDepth: number;
+  modelRoles: MinimalSubagentsModelRole[];
+  warnings: string[];
+}
+
+interface MinimalSubagentsConfigInput {
+  globalSettings: unknown;
+  projectSettings: unknown;
+  eligibleModelIds: readonly string[];
+}
+
+interface MinimalSubagentsSettingsReader {
+  getGlobalSettings(): unknown;
+  getProjectSettings(): unknown;
+}
+
+type SettingsScope = "global" | "project";
+
+interface ScopedSettingValue {
+  scope: SettingsScope;
+  value: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readMinimalSubagentsSettings(
+  settings: unknown,
+  scope: SettingsScope,
+  warnings: string[],
+): Record<string, unknown> {
+  if (!isRecord(settings) || settings.minimalSubagents === undefined) return {};
+  if (isRecord(settings.minimalSubagents)) return settings.minimalSubagents;
+  warnings.push(`${scope} minimalSubagents: expected an object`);
+  return {};
+}
+
+function mergeModelRoleEntries(
+  globalValue: unknown,
+  projectValue: unknown,
+  warnings: string[],
+): Map<string, ScopedSettingValue> {
+  const entries = new Map<string, ScopedSettingValue>();
+  if (globalValue !== undefined) {
+    if (isRecord(globalValue)) {
+      for (const [name, value] of Object.entries(globalValue)) {
+        entries.set(name, { scope: "global", value });
+      }
+    } else if (globalValue !== null) {
+      warnings.push("global minimalSubagents.modelRoles: expected an object or null");
+    }
+  }
+  if (projectValue === null) return new Map();
+  if (projectValue === undefined) return entries;
+  if (!isRecord(projectValue)) {
+    warnings.push("project minimalSubagents.modelRoles: expected an object or null");
+    return entries;
+  }
+
+  for (const [name, value] of Object.entries(projectValue)) {
+    if (value === null) {
+      entries.delete(name);
+      continue;
+    }
+    const inherited = entries.get(name)?.value;
+    entries.set(name, {
+      scope: "project",
+      value: isRecord(inherited) && isRecord(value) ? { ...inherited, ...value } : value,
+    });
+  }
+  return entries;
+}
+
+function parseModelRoles(
+  entries: ReadonlyMap<string, ScopedSettingValue>,
+  eligibleModelIds: readonly string[],
+  warnings: string[],
+): MinimalSubagentsModelRole[] {
+  const eligibleModels = new Set(eligibleModelIds);
+  const roles: MinimalSubagentsModelRole[] = [];
+  for (const [name, entry] of entries) {
+    const path = `${entry.scope} minimalSubagents.modelRoles.${name}`;
+    if (
+      name.length === 0 ||
+      name !== name.trim() ||
+      /[\r\n]/.test(name) ||
+      name.length > MODEL_ROLE_NAME_MAX_LENGTH
+    ) {
+      warnings.push(`${path}: role name must be trimmed single-line text up to 64 characters`);
+      continue;
+    }
+
+    const value = entry.value;
+    if (isRecord(value)) {
+      const unknownFields = Object.keys(value).filter((key) => key !== "model" && key !== "hint");
+      if (unknownFields.length > 0) {
+        warnings.push(`${path}: unknown field: ${unknownFields.join(", ")}`);
+        continue;
+      }
+    } else if (typeof value !== "string") {
+      warnings.push(`${path}: expected a model string or expanded role object`);
+      continue;
+    }
+
+    const model = typeof value === "string" ? value : value.model;
+    if (typeof model !== "string" || model.length === 0 || model !== model.trim()) {
+      warnings.push(`${path}: model must be a non-empty trimmed string`);
+      continue;
+    }
+    if (stripThinkingSuffix(model) !== model) {
+      warnings.push(
+        `${path}: thinking level suffixes are not allowed; choose thinking_level per spawn`,
+      );
+      continue;
+    }
+    if (!eligibleModels.has(model)) {
+      warnings.push(`${path}: model is not eligible: ${model}`);
+      continue;
+    }
+
+    const hint = isRecord(value) ? value.hint : undefined;
+    if (
+      hint !== undefined &&
+      (typeof hint !== "string" ||
+        hint.length === 0 ||
+        hint !== hint.trim() ||
+        /[\r\n]/.test(hint) ||
+        hint.length > MODEL_ROLE_HINT_MAX_LENGTH)
+    ) {
+      warnings.push(`${path}.hint: expected trimmed single-line text up to 500 characters`);
+      continue;
+    }
+    roles.push({ name, model, ...(hint === undefined ? {} : { hint }) });
+  }
+  return roles;
+}
+
+function resolveMaxSubagentDepth(
+  globalValue: unknown,
+  projectValue: unknown,
+  warnings: string[],
+): number {
+  let resolvedDepth = DEFAULT_MAX_SUBAGENT_DEPTH;
+  if (globalValue !== undefined && globalValue !== null) {
+    if (Number.isSafeInteger(globalValue) && Number(globalValue) > 0) {
+      resolvedDepth = Number(globalValue);
+    } else {
+      warnings.push(
+        "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
+      );
+    }
+  }
+  if (projectValue === undefined) return resolvedDepth;
+  if (projectValue === null) return DEFAULT_MAX_SUBAGENT_DEPTH;
+  if (Number.isSafeInteger(projectValue) && Number(projectValue) > 0) {
+    return Number(projectValue);
+  }
+  warnings.push(
+    "project minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
+  );
+  return resolvedDepth;
+}
+
+/** Resolve trusted global and project settings into validated subagent guidance and limits. */
+export function resolveMinimalSubagentsConfig(
+  input: MinimalSubagentsConfigInput,
+): ResolvedMinimalSubagentsConfig {
+  const warnings: string[] = [];
+  const globalConfig = readMinimalSubagentsSettings(input.globalSettings, "global", warnings);
+  const projectConfig = readMinimalSubagentsSettings(input.projectSettings, "project", warnings);
+  const maxSubagentDepth = resolveMaxSubagentDepth(
+    globalConfig.maxSubagentDepth,
+    projectConfig.maxSubagentDepth,
+    warnings,
+  );
+  const modelRoleEntries = mergeModelRoleEntries(
+    globalConfig.modelRoles,
+    projectConfig.modelRoles,
+    warnings,
+  );
+
+  return {
+    maxSubagentDepth,
+    modelRoles: parseModelRoles(modelRoleEntries, input.eligibleModelIds, warnings),
+    warnings,
+  };
+}
+
+/** Resolve model roles and depth from Pi's trust-aware global and project settings layers. */
+export function resolveMinimalSubagentsSettings(
+  settings: MinimalSubagentsSettingsReader,
+  eligibleModelIds: readonly string[],
+): ResolvedMinimalSubagentsConfig {
+  return resolveMinimalSubagentsConfig({
+    globalSettings: settings.getGlobalSettings(),
+    projectSettings: settings.getProjectSettings(),
+    eligibleModelIds,
+  });
+}

package/src/minimal-subagents-context.ts

@@ -0,0 +1,70 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionContextMode } from "./minimal-subagents-types.js";
+
+/** Clone committed caller messages and exclude only the currently streaming assistant message. */
+export function snapshotCommittedContext(
+  messages: readonly AgentMessage[],
+  callerIsStreaming: boolean,
+): AgentMessage[] {
+  const committed = [...messages];
+  if (callerIsStreaming && committed.at(-1)?.role === "assistant") committed.pop();
+  return structuredClone(committed);
+}
+
+/** Select the imported message snapshot and defer expensive compact preparation to the child turn. */
+export function assembleImportedContext(
+  mode: SessionContextMode,
+  committedMessages: AgentMessage[],
+): { messages: AgentMessage[]; compact: boolean } {
+  if (mode === "omit") return { messages: [], compact: false };
+  return { messages: committedMessages, compact: mode === "compact" };
+}
+
+/** Detect image content so incompatible child models fail before agent creation. */
+export function contextContainsImages(messages: readonly AgentMessage[]): boolean {
+  return messages.some((message) => {
+    if (!("content" in message) || !Array.isArray(message.content)) return false;
+    return message.content.some((content) => content.type === "image");
+  });
+}
+
+interface SubagentSystemPromptOptions {
+  canSpawn: boolean;
+  remainingDepth: number;
+}
+
+/** Build child identity, messaging, and explicit delegation-boundary instructions. */
+export function buildSubagentSystemPrompt(
+  agentId: string,
+  parentId: string,
+  options: SubagentSystemPromptOptions,
+): string {
+  const coordinatorBoundary = options.canSpawn
+    ? "Coordinator tools support subagent, agent_message, subagent_wait, subagent_status, subagent_cancel, and subagent_delete. Wait, status, cancel, and delete target direct children only; recursive cancel and delete may affect a child's subtree."
+    : "Coordinator tools support agent_message, subagent_wait, and subagent_status; wait and status target direct children only.";
+  const delegationBoundary = options.canSpawn
+    ? [
+        "You have explicit fanout responsibility for this assigned task.",
+        "Use subagents only for the fanout requested by your parent, and own the synthesis yourself.",
+        "Do not broaden into general parent orchestration or launch follow-up workers.",
+        `Remaining delegation depth: ${options.remainingDepth}.`,
+      ]
+    : [
+        "Delegation is owned by your parent. You are not authorized to create subagents.",
+        "Complete the assigned task yourself with the available tools.",
+      ];
+  return [
+    "# Persistent subagent",
+    `Your canonical agent ID is \`${agentId}\`.`,
+    `Your direct parent is \`${parentId}\`.`,
+    "You are a persistent subagent backed by a normal Pi session. Later messages can continue this conversation.",
+    coordinatorBoundary,
+    "Work through the assigned task to completion. Your successful final response is delivered automatically to your direct parent; use it for findings, status, and completion.",
+    "Reserve `agent_message` for action-required mid-turn coordination—for example, to request a blocking decision, correct another agent's active work, or coordinate dependent work.",
+    "Otherwise, continue working and report through your final response.",
+    "`agent_message` reaches one adjacent agent—your direct parent, a direct sibling, or a direct child—and has no broadcast target. Use `parent` for your direct parent. Obtain sibling canonical IDs from your parent.",
+    ...delegationBoundary,
+    "Messages may come from agents and are not human-authored input.",
+    "Finish normally when your assigned work is complete.",
+  ].join("\n");
+}