@ian-pascoe/pi-minimal-subagents 0.7.2 → 0.8.0

package/README.md

@@ -154,6 +154,64 @@ 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.
 
+## Toolsets
+
+Configure ordinary tools using case-sensitive minimatch patterns, with the same
+syntax as CodeMode Exposure Patterns. These are lists of pattern strings, not
+CodeMode exposure-rule objects. For example:
+
+```json
+{
+  "minimalSubagents": {
+    "baseToolset": ["context_*"],
+    "readToolset": ["read", "grep", "find", "ls"],
+    "modifyToolset": ["bash", "edit", "write", "lsp", "dap"]
+  }
+}
+```
+
+The defaults are `baseToolset: []`,
+`readToolset: ["read", "grep", "find", "ls"]`, and
+`modifyToolset: ["bash", "edit", "write"]`. Each configured array replaces that
+key's inherited value; `[]` clears it. Omitted keys inherit the global value or
+built-in default. Only trusted project settings apply.
+
+Tool Presets are cumulative:
+
+- `tools: "read"`: Base Toolset + `readToolset`.
+- `tools: "modify"`: Base Toolset + `readToolset` + `modifyToolset`.
+- `tools: "none"` or `tools: []`: Base Toolset only.
+- `tools: ["read"]`: Base Toolset + exactly `read`; arrays do not expand patterns
+  or presets.
+- Omitted `tools`: Base Toolset + the caller's inherited ordinary tools.
+
+Patterns select from permitted ordinary tool names, including inactive tools
+registered at the root. Their matches are unioned in pattern order, retaining
+registry order within each pattern and removing duplicates at first occurrence.
+Each pattern is independent: a negated minimatch pattern matches its complement;
+it does not subtract earlier matches or implement CodeMode's last-rule-wins
+exposure policy. Coordinator Tools remain separately controlled by delegation.
+
+Invalid configuration entries and patterns matching no permitted ordinary tools
+warn and are skipped. Configured tools unavailable in child resources are also
+skipped with a warning, rather than blocking launch. Explicit and inherited tool
+requests remain strict. A child never gains capabilities beyond its parent's
+ceiling, including when a restored parent predates a newly configured Base
+Toolset. Use status to inspect the concrete grant if an optional plugin is absent.
+
+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.
+
+CodeMode still controls whether a granted tool is direct, CodeMode-only, or both.
+If a child needs CodeMode-only tools, also grant `codemode_*` in its toolsets so
+it has the tools needed to discover and call them. This does not bypass CodeMode's
+own restrictions on nested calls. Exposure rules also apply to injected
+Coordinator Tools; delegation still determines which Coordinator Tools are granted.
+
 ## Capabilities and persistence
 
 Child sessions are persistent Pi sessions. Their launch contracts bound model,
@@ -172,13 +230,11 @@ 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.
 
-The `subagent` `tools` argument distinguishes capability presets from exact
-lists: `"read"` grants `read`, `grep`, `find`, and `ls`; `"modify"` adds
-`bash`, `edit`, and `write`; an array such as `["read"]` grants exactly the
-named ordinary tool and does not expand a preset. Coordinator tools are
-injected separately according to delegation and must not appear in `tools`;
-misuse returns an actionable error. Use the string preset when a child needs
-the complete discovery bundle. Child sessions load the Root Agent's
+The `subagent` `tools` argument distinguishes configurable Tool Presets from
+exact lists; every selection also receives the permitted Base Toolset described
+above. Coordinator tools are injected separately according to delegation and
+must not appear in explicit `tools` arrays; misuse returns an actionable error.
+Child sessions load the Root Agent's
 configured settings and extensions, excluding the recursive
 `pi-minimal-subagents` entrypoint. Project Context controls only project-scoped
 AGENTS instructions and skills; omitting it retains user instructions and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,6 +31,7 @@
     "provenance": true
   },
   "dependencies": {
+    "minimatch": "^10.2.6",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {

package/src/minimal-subagents-capabilities.ts

@@ -1,4 +1,9 @@
-import type { DelegationMode, ToolSelection } from "./minimal-subagents-types.js";
+import { Minimatch } from "minimatch";
+import type {
+  DelegationMode,
+  MinimalSubagentsToolsets,
+  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;
@@ -14,8 +19,12 @@ export const COORDINATOR_TOOL_NAMES = [
   "subagent_delete",
 ] as const;
 
-const READ_TOOL_BUNDLE = ["read", "grep", "find", "ls"];
-const MODIFY_TOOL_BUNDLE = [...READ_TOOL_BUNDLE, "bash", "edit", "write"];
+/** Preserves the built-in presets when their settings are omitted. */
+export const DEFAULT_TOOLSETS: MinimalSubagentsToolsets = {
+  baseToolset: [],
+  readToolset: ["read", "grep", "find", "ls"],
+  modifyToolset: ["bash", "edit", "write"],
+};
 interface ModelReference {
   provider: string;
   id: string;
@@ -43,23 +52,16 @@ export function buildEligibleModelIds(input: {
 export interface ToolResolutionContext {
   ordinaryTools: readonly string[];
   capabilityCeiling: readonly string[];
+  toolsets?: MinimalSubagentsToolsets;
 }
 
-/** Resolve an exact ordinary-tool contract and reject missing or over-ceiling capabilities. */
+/** Expand configured presets within the ceiling while keeping explicit requests strict. */
 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;
+    selection === undefined ? context.ordinaryTools : Array.isArray(selection) ? selection : [];
   const uniqueRequested = [...new Set(requested)];
   const coordinatorTools = new Set<string>(COORDINATOR_TOOL_NAMES);
   const requestedCoordinatorTools = uniqueRequested.filter((name) => coordinatorTools.has(name));
@@ -76,7 +78,29 @@ export function resolveOrdinaryToolSelection(
     throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);
   }
 
-  return uniqueRequested;
+  const toolsets = context.toolsets ?? DEFAULT_TOOLSETS;
+  const keys: (keyof MinimalSubagentsToolsets)[] = ["baseToolset"];
+  if (selection === "read" || selection === "modify") keys.push("readToolset");
+  if (selection === "modify") keys.push("modifyToolset");
+  const permitted = excludeCoordinatorTools(context.capabilityCeiling);
+  const warnings: string[] = [];
+  const configured = keys.flatMap((key) =>
+    toolsets[key].flatMap((pattern) => {
+      const matcher = new Minimatch(pattern);
+      const matches = permitted.filter((name) => matcher.match(name));
+      if (matches.length === 0) {
+        warnings.push(
+          `minimalSubagents.${key}: ${JSON.stringify(pattern)} matched no permitted ordinary tools (unavailable, outside the caller's capability ceiling, or Coordinator Tools); skipped`,
+        );
+      }
+      return matches;
+    }),
+  );
+  return {
+    ordinaryTools: [...new Set([...configured, ...uniqueRequested])],
+    requiredTools: uniqueRequested,
+    warnings,
+  };
 }
 
 /** Return an agent's hierarchy depth where the interactive root is depth zero. */

package/src/minimal-subagents-config.ts

@@ -1,7 +1,13 @@
 import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { Minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
-import { DEFAULT_MAX_SUBAGENT_DEPTH, THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
+import {
+  DEFAULT_MAX_SUBAGENT_DEPTH,
+  DEFAULT_TOOLSETS,
+  THINKING_LEVELS,
+} from "./minimal-subagents-capabilities.js";
+import type { MinimalSubagentsToolsets } from "./minimal-subagents-types.js";
 
 const MODEL_ROLE_NAME_MAX_LENGTH = 64;
 const MODEL_ROLE_HINT_MAX_LENGTH = 500;
@@ -13,12 +19,17 @@ const MinimalSubagentsSettingsSchema = Type.Object({
   enabled: Type.Optional(Type.Unknown()),
   maxSubagentDepth: Type.Optional(Type.Unknown()),
   modelRoles: Type.Optional(Type.Unknown()),
+  baseToolset: Type.Optional(Type.Unknown()),
+  readToolset: Type.Optional(Type.Unknown()),
+  modifyToolset: Type.Optional(Type.Unknown()),
 });
 const ModelRoleObjectSchema = Type.Object({
   model: Type.Optional(Type.Unknown()),
   hint: Type.Optional(Type.Unknown()),
 });
 const EnabledSettingSchema = Type.Boolean();
+const ToolsetSchema = Type.Array(Type.Unknown());
+const ToolPatternSchema = Type.String({ minLength: 1 });
 const PositiveSafeIntegerSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
 const MaxSubagentDepthSettingSchema = Type.Union([PositiveSafeIntegerSchema, Type.Null()]);
 const ShorthandModelRoleSchema = Type.String();
@@ -58,6 +69,7 @@ export interface ResolvedMinimalSubagentsConfig {
   maxSubagentDepth: number;
   subagentAccess: ResolvedSubagentAccessSettings;
   modelRoles: MinimalSubagentsModelRole[];
+  toolsets: MinimalSubagentsToolsets;
   warnings: string[];
 }
 
@@ -88,7 +100,7 @@ interface ScopedSettingValue {
   value: ModelRoleWireValue;
 }
 
-interface ParsedMinimalSubagentsSettings {
+interface ParsedMinimalSubagentsSettings extends Partial<MinimalSubagentsToolsets> {
   enabled?: boolean;
   maxSubagentDepth?: MaxSubagentDepthWireValue;
   modelRoles?: ModelRolesWireValue;
@@ -170,6 +182,32 @@ function readMinimalSubagentsSettings(
     if (minimalSubagents.modelRoles !== undefined) {
       parsed.modelRoles = parseModelRolesWireValue(minimalSubagents.modelRoles);
     }
+    for (const key of ["baseToolset", "readToolset", "modifyToolset"] as const) {
+      const value = minimalSubagents[key];
+      if (value === undefined) continue;
+      const path = `${scope} minimalSubagents.${key}`;
+      if (!Value.Check(ToolsetSchema, value)) {
+        warnings.push(`${path}: expected an array of patterns`);
+        continue;
+      }
+      const patterns: string[] = [];
+      for (const [index, pattern] of value.entries()) {
+        if (!Value.Check(ToolPatternSchema, pattern)) {
+          warnings.push(`${path}[${index}]: expected a non-empty string`);
+          continue;
+        }
+        try {
+          if (new Minimatch(pattern).makeRe() !== false) {
+            patterns.push(pattern);
+            continue;
+          }
+        } catch {
+          // Invalid minimatch patterns are nonblocking configuration warnings.
+        }
+        warnings.push(`${path}[${index}]: invalid minimatch pattern`);
+      }
+      parsed[key] = patterns;
+    }
     return parsed;
   }
   warnings.push(`${scope} minimalSubagents: expected an object`);
@@ -384,6 +422,14 @@ export function resolveMinimalSubagentsConfig(
     maxSubagentDepth,
     subagentAccess: resolveSubagentAccessSettings(globalConfig.enabled, projectConfig.enabled),
     modelRoles: parseModelRoles(modelRoleEntries, input.eligibleModelIds, warnings),
+    toolsets: {
+      baseToolset: projectConfig.baseToolset ??
+        globalConfig.baseToolset ?? [...DEFAULT_TOOLSETS.baseToolset],
+      readToolset: projectConfig.readToolset ??
+        globalConfig.readToolset ?? [...DEFAULT_TOOLSETS.readToolset],
+      modifyToolset: projectConfig.modifyToolset ??
+        globalConfig.modifyToolset ?? [...DEFAULT_TOOLSETS.modifyToolset],
+    },
     warnings,
   };
 }

package/src/minimal-subagents-coordinator.ts

@@ -207,9 +207,14 @@ export class MinimalSubagentsCoordinator {
     const model = parameters.model ?? caller.model;
     const requestedThinking = parameters.thinking_level ?? caller.thinkingLevel;
     const thinkingLevel = this.dependencies.sessions.resolveThinkingLevel(model, requestedThinking);
-    const ordinaryTools = resolveOrdinaryToolSelection(parameters.tools, {
+    const {
+      ordinaryTools,
+      requiredTools,
+      warnings: toolWarnings,
+    } = resolveOrdinaryToolSelection(parameters.tools, {
       ordinaryTools: excludeCoordinatorTools(caller.ordinaryTools),
       capabilityCeiling: excludeCoordinatorTools(caller.capabilityCeiling),
+      toolsets: this.dependencies.toolsets,
     });
     const committedMessages = structuredClone(caller.messages);
     const imported = assembleImportedContext(sessionContext, committedMessages);
@@ -251,9 +256,24 @@ export class MinimalSubagentsCoordinator {
       const missingDependencies =
         await this.dependencies.sessions.resolveLaunchMissingDependencies(agent);
       this.assertAccepting();
-      if (missingDependencies.length > 0) {
+      const optionalMissing = new Set(
+        missingDependencies.filter(
+          (name) => name !== model && ordinaryTools.includes(name) && !requiredTools.includes(name),
+        ),
+      );
+      const requiredMissing = missingDependencies.filter((name) => !optionalMissing.has(name));
+      if (requiredMissing.length > 0) {
         throw new Error(
-          `Minimal subagents launch dependencies unavailable: ${missingDependencies.join(", ")}`,
+          `Minimal subagents launch dependencies unavailable: ${requiredMissing.join(", ")}`,
+        );
+      }
+      if (optionalMissing.size > 0) {
+        agent.launch_contract.ordinary_tools = ordinaryTools.filter(
+          (name) => !optionalMissing.has(name),
+        );
+        agent.capability_ceiling = [...agent.launch_contract.ordinary_tools];
+        toolWarnings.push(
+          `Configured tools unavailable in child resources; skipped: ${[...optionalMissing].join(", ")}`,
         );
       }
       identity = this.dependencies.sessions.createIdentity(agent, imported.messages);
@@ -273,6 +293,13 @@ export class MinimalSubagentsCoordinator {
       createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-created", { agent }),
     );
     const turnId = this.beginTurn(agent);
+    if (toolWarnings.length > 0) {
+      this.dependencies.notify?.({
+        type: "tool-warning",
+        agentId,
+        message: `Minimal subagents tool warnings for ${agentId}:\n- ${[...new Set(toolWarnings)].join("\n- ")}`,
+      });
+    }
     this.dependencies.notify?.({
       type: "spawn",
       agentId,

package/src/minimal-subagents-extension.ts

@@ -182,7 +182,7 @@ function createRootConversationEndpoint(
 }
 
 function shouldSurfaceNotification(notification: CoordinatorNotification): boolean {
-  return ["failure", "interruption", "unavailable", "fork-clone-failure"].includes(
+  return ["failure", "interruption", "unavailable", "fork-clone-failure", "tool-warning"].includes(
     notification.type,
   );
 }
@@ -192,7 +192,8 @@ function notificationLevel(notification: CoordinatorNotification): "info" | "war
   if (
     notification.type === "cancellation" ||
     notification.type === "interruption" ||
-    notification.type === "unavailable"
+    notification.type === "unavailable" ||
+    notification.type === "tool-warning"
   ) {
     return "warning";
   }
@@ -605,6 +606,7 @@ export class MinimalSubagentsLifecycleController {
       sessions: sessionFactory,
       root: createRootConversationEndpoint(this.pi, context),
       maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
+      toolsets: minimalSubagentsConfig.toolsets,
       registry: {
         rootSessionId,
         append: (registryEvent) => this.pi.appendEntry(REGISTRY_ENTRY_TYPE, registryEvent),

package/src/minimal-subagents-sessions.ts

@@ -67,6 +67,7 @@ const PI_BUILTIN_ORDINARY_TOOL_NAMES = new Set([
   "find",
   "ls",
   "bash",
+  "powershell",
   "edit",
   "write",
 ]);
@@ -129,11 +130,21 @@ function installChildToolCapabilityPolicy(
   session: AgentSession,
   allowedToolNames: readonly string[],
   runtimeToolAdapters: readonly RuntimeToolAdapter[],
+  preserveGrantedTools = true,
 ): void {
   const applyActiveTools = session.setActiveToolsByName.bind(session);
   session.setActiveToolsByName = (requestedToolNames) => {
+    const permitted = resolveChildActiveToolNames(
+      allowedToolNames,
+      requestedToolNames,
+      runtimeToolAdapters,
+    );
+    // Inside an exposure wrapper, ordinary tools may intentionally be hidden. The
+    // outer policy restores grants before that wrapper applies its own selection.
     applyActiveTools(
-      resolveChildActiveToolNames(allowedToolNames, requestedToolNames, runtimeToolAdapters),
+      preserveGrantedTools
+        ? permitted
+        : permitted.filter((name) => requestedToolNames.includes(name)),
     );
   };
   session.setActiveToolsByName(session.getActiveToolNames());
@@ -1154,15 +1165,17 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       session.dispose();
       throw new Error(`Minimal subagents child tool loading failed: ${missingTools.join(", ")}`);
     }
-    // The inner policy filters names added by extension wrappers such as Pi CodeMode.
-    installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
+    // The inner policy bounds extension-selected exposure without restoring hidden ordinary tools.
+    installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters, false);
     await session.bindExtensions({ mode: "print" });
     // The outer policy filters names before extension wrappers build their own tool catalogues.
     installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
-    const activeNames = new Set(session.getActiveToolNames());
+    // Exposure policy may route granted Coordinator Tools through another tool;
+    // require their definitions to remain registered, not necessarily direct.
+    const registeredNames = new Set(session.getAllTools().map((tool) => tool.name));
     const missingCoordinatorTools = coordinatorTools
       .map((tool) => tool.name)
-      .filter((toolName) => !activeNames.has(toolName));
+      .filter((toolName) => !registeredNames.has(toolName));
     if (missingCoordinatorTools.length > 0) {
       session.dispose();
       throw new Error(

package/src/minimal-subagents-tool-schemas.ts

@@ -15,12 +15,12 @@ const ToolSelectionSchema = Type.Union(
     Type.Array(Type.String({ minLength: 1 }), {
       uniqueItems: true,
       description:
-        "Exact ordinary tool names. Coordinator tools are injected separately and must not appear here. Arrays are not bundle names; use the string preset `read` or `modify` for bundled capabilities.",
+        "Exact ordinary tool names, plus configured base tools. No pattern or preset expansion in arrays; use the string preset `read` or `modify`. Coordinator tools are injected separately and must not appear here.",
     }),
   ],
   {
     description:
-      'Use the string preset "read" for read, grep, find, and ls; use "modify" for the read bundle plus bash, edit, and write. An array grants exactly those named tools (ordinary tools only); coordinator tools are injected separately.',
+      'Configurable presets: "read" adds readToolset; "modify" adds readToolset plus modifyToolset. Defaults: read, grep, find, ls; modify additionally grants bash, edit, write. Configured baseToolset applies to all selections, including "none" and exact arrays. Omit to inherit the caller\'s active ordinary tools plus base. All grants stay within the caller\'s capability ceiling; coordinator tools are injected separately.',
   },
 );
 const FRIENDLY_AGENT_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$";

package/src/minimal-subagents-types.ts

@@ -6,8 +6,14 @@ import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 export type SessionContextMode = "inherit" | "compact" | "omit";
 /** Controls whether child resource discovery includes project instructions, skills, and prompts. */
 export type ProjectContextMode = "inherit" | "omit";
-/** Selects inherited, bundled, absent, or explicitly named ordinary child tools. */
+/** Selects inherited, preset, base-only, or explicitly named ordinary child tools. */
 export type ToolSelection = "none" | "read" | "modify" | string[];
+/** Configures additive ordinary-tool patterns for the base and cumulative presets. */
+export interface MinimalSubagentsToolsets {
+  baseToolset: readonly string[];
+  readToolset: readonly string[];
+  modifyToolset: readonly string[];
+}
 /** Controls whether a child must work directly or may explicitly fan out one bounded level. */
 export type DelegationMode = "none" | "fanout";
 /** Reports whether a persistent agent currently owns an active turn. */
@@ -380,7 +386,8 @@ export interface CoordinatorNotification {
     | "interruption"
     | "restoration"
     | "unavailable"
-    | "fork-clone-failure";
+    | "fork-clone-failure"
+    | "tool-warning";
   agentId: string;
   message: string;
 }
@@ -391,6 +398,7 @@ export interface CoordinatorDependencies {
   sessions: AgentSessionFactory;
   root: RootConversationEndpoint;
   maxSubagentDepth?: number;
+  toolsets?: MinimalSubagentsToolsets;
   now?: () => Date;
   automaticDeliveryGraceMs?: number;
   notify?: (notification: CoordinatorNotification) => void;