@tintinweb/pi-subagents 0.9.1 → 0.10.1

package/dist/worktree.js

@@ -16,9 +16,12 @@ import { join } from "node:path";
  */
 export function createWorktree(cwd, agentId) {
     // Verify we're in a git repo with at least one commit (HEAD must exist)
+    let baseSha;
     try {
         execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
-        execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 });
+        baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 })
+            .toString()
+            .trim();
     }
     catch {
         return undefined;
@@ -33,7 +36,7 @@ export function createWorktree(cwd, agentId) {
             stdio: "pipe",
             timeout: 30000,
         });
-        return { path: worktreePath, branch };
+        return { path: worktreePath, branch, baseSha };
     }
     catch {
         // If worktree creation fails, return undefined (agent runs in normal cwd)
@@ -56,21 +59,30 @@ export function cleanupWorktree(cwd, worktree, agentDescription) {
             stdio: "pipe",
             timeout: 10000,
         }).toString().trim();
-        if (!status) {
-            // No changes — remove worktree
-            removeWorktree(cwd, worktree.path);
-            return { hasChanges: false };
+        if (status) {
+            // Changes exist — stage, commit, and create a branch
+            execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
+            // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+            const safeDesc = agentDescription.slice(0, 200);
+            const commitMsg = `pi-agent: ${safeDesc}`;
+            execFileSync("git", ["commit", "--no-verify", "-m", commitMsg], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 10000,
+            });
+        }
+        else {
+            const currentSha = execFileSync("git", ["rev-parse", "HEAD"], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 5000,
+            }).toString().trim();
+            if (currentSha === worktree.baseSha) {
+                // No changes — remove worktree
+                removeWorktree(cwd, worktree.path);
+                return { hasChanges: false };
+            }
         }
-        // Changes exist — stage, commit, and create a branch
-        execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
-        // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
-        const safeDesc = agentDescription.slice(0, 200);
-        const commitMsg = `pi-agent: ${safeDesc}`;
-        execFileSync("git", ["commit", "-m", commitMsg], {
-            cwd: worktree.path,
-            stdio: "pipe",
-            timeout: 10000,
-        });
         // Create a branch pointing to the worktree's HEAD.
         // If the branch already exists, append a suffix to avoid overwriting previous work.
         let branchName = worktree.branch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "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/"

package/src/agent-runner.ts

@@ -2,8 +2,10 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
 import {
   type AgentSession,
   type AgentSessionEvent,
@@ -14,7 +16,7 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
@@ -23,8 +25,114 @@ import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
+/**
+ * Tool names registered by THIS extension. Single source of truth so the
+ * registration sites (index.ts) and the subagent exclusion list below can't
+ * drift apart. These are our own tools, not pi built-ins, so they can't be
+ * derived from pi — but they only need defining once.
+ */
+export const SUBAGENT_TOOL_NAMES = {
+  AGENT: "Agent",
+  GET_RESULT: "get_subagent_result",
+  STEER: "steer_subagent",
+} as const;
+
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+const EXCLUDED_TOOL_NAMES: string[] = Object.values(SUBAGENT_TOOL_NAMES);
+
+/**
+ * Canonical name of an extension for `extensions: [...]` allowlist matching.
+ * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
+ * resolves the same as `[mcp]`. Tool names within `ext:foo/bar` are not affected.
+ * Directory extensions (`foo/index.ts`) resolve to the parent directory name;
+ * single-file extensions to the basename minus `.ts`/`.js`.
+ */
+export function extensionCanonicalName(extPath: string): string {
+  const base = basename(extPath);
+  const name = base === "index.ts" || base === "index.js"
+    ? basename(dirname(extPath))
+    : base.replace(/\.(ts|js)$/, "");
+  return name.toLowerCase();
+}
+
+/**
+ * Classify `extensions: string[]` frontmatter entries for the loader-level filter.
+ *
+ * An entry is a PATH iff it contains a path separator or starts with `~`; otherwise
+ * it is a NAME. `"*"` sets the wildcard flag (keep all default-discovered extensions).
+ *
+ * Path entries are resolved (`~` expanded, made absolute against `cwd`) into `paths`
+ * — and their canonical name is also added to `names`. The loader override matches
+ * everything by canonical name, so path-loaded extensions are matched via their name
+ * rather than their post-staging `Extension.path`.
+ */
+export function parseExtensionsSpec(
+  entries: string[],
+  cwd: string,
+): { names: Set<string>; paths: string[]; wildcard: boolean } {
+  const names = new Set<string>();
+  const paths: string[] = [];
+  let wildcard = false;
+  for (const entry of entries) {
+    if (!entry) continue;
+    if (entry === "*") {
+      wildcard = true;
+      continue;
+    }
+    const isPathEntry = entry.includes("/") || entry.includes("\\") || entry.startsWith("~");
+    if (!isPathEntry) {
+      names.add(entry.toLowerCase());
+      continue;
+    }
+    let p = entry;
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
+      p = homedir() + p.slice(1);
+    }
+    const abs = isAbsolute(p) ? p : resolve(cwd, p);
+    paths.push(abs);
+    names.add(extensionCanonicalName(abs));
+  }
+  return { names, paths, wildcard };
+}
+
+/**
+ * Parse raw `ext:` selector strings (from the `tools:` CSV) into the set of
+ * extension names to keep loaded and a per-extension tool-narrowing map.
+ *
+ * `ext:foo` → `extNames` has `foo`, no narrowing entry (all of foo's tools).
+ * `ext:foo/bar` → `extNames` has `foo`, `narrowing.foo` has `bar` (only `bar`).
+ * A name lands in `narrowing` only when a `/tool` form is seen, so a bare
+ * `ext:foo` alongside `ext:foo/bar` leaves narrowing in effect (narrowing wins).
+ * The split is on the first `/`; extension canonical names never contain `/`.
+ */
+export function parseExtSelectors(entries: string[]): {
+  extNames: Set<string>;
+  narrowing: Map<string, Set<string>>;
+} {
+  const extNames = new Set<string>();
+  const narrowing = new Map<string, Set<string>>();
+  for (const raw of entries) {
+    if (!raw) continue;
+    const body = raw.slice("ext:".length);
+    const slash = body.indexOf("/");
+    // Extension name matches case-insensitively (matches the loader-side canonical
+    // name). Tool names are case-preserved — they're matched against pi-mono's
+    // registered identifiers, which are case-sensitive.
+    const name = (slash === -1 ? body : body.slice(0, slash)).trim().toLowerCase();
+    if (!name) continue;
+    extNames.add(name);
+    if (slash === -1) continue;
+    const tool = body.slice(slash + 1).trim();
+    if (!tool) continue;
+    let set = narrowing.get(name);
+    if (!set) {
+      set = new Set();
+      narrowing.set(name, set);
+    }
+    set.add(tool);
+  }
+  return { extNames, narrowing };
+}
 
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
@@ -239,16 +347,51 @@ export async function runAgent(
 
   const agentDir = getAgentDir();
 
-  // Load extensions/skills: true or string[] → load; false → don't.
+  // Extension loading:
+  // - true  → all default-discovered extensions
+  // - false → none (noExtensions)
+  // - string[] → loader-level allowlist. Bare names keep the matching
+  //   default-discovered extension; path entries load that extension fresh;
+  //   "*" keeps all default-discovered extensions. Excluded extensions never
+  //   bind handlers or register tools (their factory still runs once).
+  //
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
   // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
+  // `ext:` selectors from the `tools:` CSV narrow which extension tools surface to
+  // the LLM. They do NOT control loading — `extensions:` is the sole authority for
+  // which extensions load. `ext:foo` against an extension that `extensions:` excluded
+  // is an orphan and warns after reload. `isolated` means no extension tools at all.
+  const { extNames, narrowing } = parseExtSelectors(
+    options.isolated ? [] : (agentConfig?.extSelectors ?? []),
+  );
+  const noExtensions = extensions === false;
+
+  const extensionsSpec = Array.isArray(extensions)
+    ? parseExtensionsSpec(extensions, effectiveCwd)
+    : undefined;
+  const keepNames = extensionsSpec?.names ?? new Set<string>();
+  // The override filters loaded extensions down to `keepNames`. It's only needed
+  // when we're neither loading everything (`extensions: true` or a `"*"` wildcard)
+  // nor nothing (`noExtensions`).
+  const loadAll = extensions === true || extensionsSpec?.wildcard === true;
+  const additionalExtensionPaths = extensionsSpec?.paths.length ? extensionsSpec.paths : undefined;
+  const extensionsOverride: ((base: LoadExtensionsResult) => LoadExtensionsResult) | undefined =
+    loadAll || noExtensions
+      ? undefined
+      : (base) => ({
+          ...base,
+          extensions: base.extensions.filter((e) => keepNames.has(extensionCanonicalName(e.path))),
+        });
+
   const loader = new DefaultResourceLoader({
     cwd: effectiveCwd,
     agentDir,
-    noExtensions: extensions === false,
+    noExtensions,
+    additionalExtensionPaths,
+    extensionsOverride,
     noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -258,6 +401,52 @@ export async function runAgent(
   });
   await loader.reload();
 
+  // Plain entries in `tools:` are expected to be built-in names (extension tools
+  // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
+  // this produced a silently broken agent (#75) — pi-mono accepted the bogus name
+  // into the allowlist, then dropped it at registration with no signal back.
+  if (agentConfig?.builtinToolNames?.length) {
+    const knownBuiltins = new Set(BUILTIN_TOOL_NAMES);
+    for (const name of agentConfig.builtinToolNames) {
+      if (!knownBuiltins.has(name)) {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `tools-error:tool "${name}" requested by agent "${type}" is not a known built-in`,
+        });
+      }
+    }
+  }
+
+  // A subagent spawns mid-task, so a bad `extensions:`/`ext:` entry warns rather
+  // than aborts. Two distinct misconfigurations to catch:
+  //   - `extensions: [foo]` but no extension named foo was discovered (typo or
+  //     path that failed to load — path entries fold their canonical name into
+  //     `keepNames`, so this covers them too).
+  //   - `tools: ext:foo` but foo isn't in the loaded set (because `extensions:`
+  //     didn't include it). Since v0.9, `ext:` no longer pulls extensions in;
+  //     loading is `extensions:`-authoritative.
+  if (keepNames.size > 0 || extNames.size > 0) {
+    const survivingNames = new Set(
+      loader.getExtensions().extensions.map((e) => extensionCanonicalName(e.path)),
+    );
+    for (const name of keepNames) {
+      if (!survivingNames.has(name)) {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `extension-error:extension "${name}" requested by agent "${type}" was not loaded`,
+        });
+      }
+    }
+    for (const name of extNames) {
+      if (!survivingNames.has(name)) {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `extension-error:ext:${name} referenced by agent "${type}" but extension "${name}" is not loaded (add it to extensions:)`,
+        });
+      }
+    }
+  }
+
   // Resolve model: explicit option > config.model > parent model
   const model = options.model ?? resolveDefaultModel(
     ctx.model, ctx.modelRegistry, agentConfig?.model,
@@ -266,6 +455,46 @@ export async function runAgent(
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
+  const disallowedSet = agentConfig?.disallowedTools
+    ? new Set(agentConfig.disallowedTools)
+    : undefined;
+
+  // Enumerate extension-registered tool names from the loaded resource loader.
+  // Extensions populate `extension.tools` during `loader.reload()` and the set
+  // is stable afterwards — `bindExtensions` does not register new tools.
+  //
+  // Opt-in flip: when any `ext:` selector is present, extension tools become an
+  // explicit allowlist — a loaded extension not named by a selector contributes
+  // no tools (its handlers still ran), and `ext:foo/bar` narrows `foo` to `bar`.
+  const extensionToolNames: string[] = [];
+  if (!noExtensions) {
+    const optInActive = extNames.size > 0;
+    for (const extension of loader.getExtensions().extensions) {
+      const canon = extensionCanonicalName(extension.path);
+      if (optInActive && !extNames.has(canon)) continue;
+      const narrowed = narrowing.get(canon);
+      for (const toolName of extension.tools.keys()) {
+        if (narrowed && !narrowed.has(toolName)) continue;
+        extensionToolNames.push(toolName);
+      }
+    }
+  }
+
+  // Build the master tool allowlist applied at session construction.
+  // pi-mono's `allowedToolNames` gates BOTH registration and the initial active
+  // set, so listing the exact final set here means the session is correctly
+  // scoped from the first instant — no post-construction narrowing required.
+  const builtinToolNameSet = new Set(toolNames);
+  const allowedTools = [...toolNames, ...extensionToolNames].filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    if (disallowedSet?.has(t)) return false;
+    if (builtinToolNameSet.has(t)) return true;
+    // Reached only for extension tools. The extension set was already filtered
+    // at the loader (extensionsOverride / noExtensions) and at enumeration
+    // (`ext:` opt-in flip), so any extension tool in `extensionToolNames` is allowed.
+    return !noExtensions;
+  });
+
   const sessionOpts: Parameters<typeof createAgentSession>[0] = {
     cwd: effectiveCwd,
     agentDir,
@@ -273,7 +502,7 @@ export async function runAgent(
     settingsManager: SettingsManager.create(effectiveCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model,
-    tools: toolNames,
+    tools: allowedTools,
     resourceLoader: loader,
   };
   if (thinkingLevel) {
@@ -287,35 +516,10 @@ export async function runAgent(
     options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
   );
 
-  // Build disallowed tools set from agent config
-  const disallowedSet = agentConfig?.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
-
-  // Filter active tools: remove our own tools to prevent nesting,
-  // apply extension allowlist if specified, and apply disallowedTools denylist
-  if (extensions !== false) {
-    const builtinToolNameSet = new Set(toolNames);
-    const activeTools = session.getActiveToolNames().filter((t) => {
-      if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-      if (disallowedSet?.has(t)) return false;
-      if (builtinToolNameSet.has(t)) return true;
-      if (Array.isArray(extensions)) {
-        return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
-      }
-      return true;
-    });
-    session.setActiveToolsByName(activeTools);
-  } else if (disallowedSet) {
-    // Even with extensions disabled, apply denylist to built-in tools
-    const activeTools = session.getActiveToolNames().filter(t => !disallowedSet.has(t));
-    session.setActiveToolsByName(activeTools);
-  }
-
   // Bind extensions so that session_start fires and extensions can initialize
-  // (e.g. loading credentials, setting up state). Placed after tool filtering
-  // so extension-provided skills/prompts from extendResourcesFromExtensions()
-  // respect the active tool set. All ExtensionBindings fields are optional.
+  // (e.g. loading credentials, setting up state). Tool gating already happened
+  // at session construction via the `tools:` allowlist above — no separate
+  // post-bind filter is needed. All ExtensionBindings fields are optional.
   await session.bindExtensions({
     onError: (err) => {
       options.onToolActivity?.({

package/src/agent-types.ts

@@ -5,15 +5,34 @@
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
 
+import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import type { AgentConfig } from "./types.js";
 
-/** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * All known built-in tool names, derived from pi's own tool factories rather
+ * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
+ * `createCodingTools` → read/bash/edit/write; `createReadOnlyTools` →
+ * read/grep/find/ls; their de-duplicated union is the 7 built-ins
+ * (read, bash, edit, write, grep, find, ls). The `cwd` only binds tool
+ * operations we never invoke here — we read each tool's `.name` and discard it.
+ */
+export const BUILTIN_TOOL_NAMES: string[] = [
+  ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
+];
 
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
 
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+
+/** Check whether default agents are disabled. */
+export function isDefaultsDisabled(): boolean { return disableDefaults; }
+
+/** Set whether default agents are disabled. */
+export function setDefaultsDisabled(b: boolean): void { disableDefaults = b; }
+
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -22,9 +41,11 @@ const agents = new Map<string, AgentConfig>();
 export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   agents.clear();
 
-  // Start with defaults
-  for (const [name, config] of DEFAULT_AGENTS) {
-    agents.set(name, config);
+  // Start with defaults (unless disabled via settings)
+  if (!disableDefaults) {
+    for (const [name, config] of DEFAULT_AGENTS) {
+      agents.set(name, config);
+    }
   }
 
   // Overlay user agents (overrides defaults with same name)
@@ -112,8 +133,9 @@ export function getToolNamesForType(type: string): string[] {
   const key = resolveKey(type);
   const raw = key ? agents.get(key) : undefined;
   const config = raw?.enabled !== false ? raw : undefined;
-  const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
-  return names;
+  // `undefined` (definition omitted the field) → all built-ins; an explicit `[]`
+  // (`tools: none` or a `tools:` with only `ext:` entries) → zero built-ins.
+  return config?.builtinToolNames ?? [...BUILTIN_TOOL_NAMES];
 }
 
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */

package/src/custom-agents.ts

@@ -50,11 +50,14 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
 
     const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(content);
 
+    const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
+
     agents.set(name, {
       name,
       displayName: str(fm.display_name),
       description: str(fm.description) ?? name,
-      builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+      builtinToolNames,
+      extSelectors,
       disallowedTools: csvListOptional(fm.disallowed_tools),
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
@@ -107,6 +110,25 @@ function csvList(val: unknown, defaults: string[]): string[] {
   return parseCsvField(val) ?? [];
 }
 
+/**
+ * Partition the `tools:` CSV into the built-in tool allowlist and raw `ext:` selectors.
+ * `*` (and the case-insensitive alias `all`, for `tools: all`) expands to all
+ * built-ins; plain entries are built-in names; `ext:` entries are extension-tool
+ * selectors parsed later by the runner. omitted → all built-ins, no selectors.
+ * `tools:` present with only `ext:` entries → zero built-ins (use `*`).
+ */
+function parseToolsField(val: unknown): { builtinToolNames: string[]; extSelectors: string[] | undefined } {
+  const entries = csvList(val, BUILTIN_TOOL_NAMES);
+  const isWildcard = (e: string) => e === "*" || e.toLowerCase() === "all";
+  const hasWildcard = entries.some(isWildcard);
+  const plain = entries.filter(e => !isWildcard(e) && !e.startsWith("ext:"));
+  const extEntries = entries.filter(e => e.startsWith("ext:"));
+  return {
+    builtinToolNames: hasWildcard ? [...new Set([...BUILTIN_TOOL_NAMES, ...plain])] : plain,
+    extSelectors: extEntries.length > 0 ? extEntries : undefined,
+  };
+}
+
 /**
  * Parse an optional comma-separated list field.
  * omitted → undefined; "none"/empty → undefined; csv → listed items.