@tintinweb/pi-subagents 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-06-10
+
+### Added
+- **`disableDefaultAgents` setting** ([#92](https://github.com/tintinweb/pi-subagents/issues/92) — thanks [@TommyC81](https://github.com/TommyC81)). When on, the three built-in default agents (general-purpose, Explore, Plan) are skipped at registration — only user-defined `.pi/agents/*.md` agents are advertised and spawnable. User agents are unaffected, including ones overriding a default by name; with no user agents defined, spawning falls back to the hardcoded generic config. Off by default; toggle via `/agents → Settings → Disable defaults` or `disableDefaultAgents` in `subagents.json`. Like `schedulingEnabled`, the Agent tool's type list reflects the change on the next pi session (tool schema is registered at startup).
+
+### Fixed
+- **Agents with `enabled: false` are no longer advertised in the Agent tool description** ([#92](https://github.com/tintinweb/pi-subagents/issues/92)). `buildTypeListText` listed every registered agent, including disabled ones that `isValidType` then refused to spawn — the LLM was offered types it could never use. The type list now filters through `getAvailableTypes()`, matching the `subagent_type` parameter description.
+- **Agent tool type list no longer built from pre-settings state.** The description text was captured into a variable before persisted settings were applied; it's now built at tool-registration time, after `subagents:settings_loaded`.
+- **Committed work from `isolation: "worktree"` subagents is now preserved** ([#68](https://github.com/tintinweb/pi-subagents/pull/68) — thanks [@rylwin](https://github.com/rylwin)). If an isolated subagent creates its own commit, cleanup previously saw a clean `git status`, treated it as "no changes", and removed the detached worktree — silently discarding the commits. The worktree now records its base SHA at creation, and cleanup creates the expected `pi-agent-*` branch whenever HEAD moved past it, even with a clean tree.
+- **Automatic commits in isolated worktrees skip local Git hooks** ([#68](https://github.com/tintinweb/pi-subagents/pull/68)). The preservation commit at worktree cleanup now uses `--no-verify`, so a failing local pre-commit hook can't abort it (which previously surfaced as `hasChanges: false` — the agent's work lost).
+
 ## [0.10.0] - 2026-06-01
 
 > **⚠️ Breaking: `extensions:` and `tools:` in agent frontmatter semantics changed.** The `extensions: [...]` array now selects which extensions *load*, not which tool names surface. Agents that previously used the array form will behave differently — see migration below. The `tools:` field also grew new `ext:` and `*` selector forms; existing `tools:` values without these selectors are unchanged.

package/README.md

@@ -365,12 +365,14 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off, disable defaults on/off) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, join mode `smart`).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, join mode `smart`, defaults enabled).
+
+**Disable defaults** (`disableDefaultAgents`, default `false`): when on, the three built-in agents (general-purpose, Explore, Plan) are not registered — only your `.pi/agents/*.md` agents are advertised and spawnable. User-defined agents are unaffected, including ones that override a default by name. The Agent tool's type list updates on the next pi session (the tool schema is registered at startup).
 
 **Example — global defaults for a beefy machine:**
 
@@ -507,6 +509,9 @@ Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
 The agent gets a full, isolated copy of the repository. On completion:
 - **No changes:** worktree is cleaned up automatically
 - **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
+- **Agent committed its own work:** the branch is created at the agent's HEAD, preserving its commits (uncommitted leftovers are committed on top first)
+
+The automatic preservation commit uses `--no-verify`, so local pre-commit hooks can't block it — the commit is local-only and never pushed, and pre-push/server-side hooks still apply.
 
 If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `Agent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint. Initialize git and commit at least once, or omit `isolation`.
 

package/dist/agent-types.d.ts

@@ -14,6 +14,10 @@ import type { AgentConfig } from "./types.js";
  * operations we never invoke here — we read each tool's `.name` and discard it.
  */
 export declare const BUILTIN_TOOL_NAMES: string[];
+/** Check whether default agents are disabled. */
+export declare function isDefaultsDisabled(): boolean;
+/** Set whether default agents are disabled. */
+export declare function setDefaultsDisabled(b: boolean): void;
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).

package/dist/agent-types.js

@@ -19,6 +19,12 @@ export const BUILTIN_TOOL_NAMES = [
 ];
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map();
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+/** Check whether default agents are disabled. */
+export function isDefaultsDisabled() { return disableDefaults; }
+/** Set whether default agents are disabled. */
+export function setDefaultsDisabled(b) { disableDefaults = b; }
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -26,9 +32,11 @@ const agents = new Map();
  */
 export function registerAgents(userAgents) {
     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)
     for (const [name, config] of userAgents) {

package/dist/index.js

@@ -16,7 +16,7 @@ import { Container, Key, matchesKey, SettingsList, Spacer, Text } from "@earendi
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
-import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
@@ -462,6 +462,17 @@ export default function (pi) {
     let scopeModelsEnabled = false;
     function isScopeModelsEnabled() { return scopeModelsEnabled; }
     function setScopeModelsEnabled(enabled) { scopeModelsEnabled = enabled; }
+    // ---- Disable default agents configuration ----
+    // When enabled, the three hardcoded default agents (general-purpose, Explore,
+    // Plan) are not registered. User-defined agents from .pi/agents/*.md are
+    // completely unaffected — only DEFAULT_AGENTS are suppressed.
+    // Defaults to false; opt-in via `/agents → Settings` or subagents.json.
+    // State lives in agent-types.ts (isDefaultsDisabled) because registerAgents
+    // needs it; this wrapper just re-registers after flipping it.
+    function setDisableDefaultAgents(b) {
+        setDefaultsDisabled(b);
+        reloadCustomAgents(); // re-register with new setting
+    }
     // ---- Batch tracking for smart join mode ----
     // Collects background agent IDs spawned in the current turn for smart grouping.
     // Uses a debounced timer: each new agent resets the 100ms window so that all
@@ -518,10 +529,10 @@ export default function (pi) {
             && BUILTIN_TOOL_NAMES.every((t) => tools.includes(t));
         return isFullSet ? "*" : tools.join(", ");
     };
-    /** Build the full type list text dynamically from the unified registry. */
+    /** Build the full type list text dynamically from available agents only. */
     const buildTypeListText = () => {
-        const allNames = [...getDefaultAgentNames(), ...getUserAgentNames()];
-        return allNames.map((name) => {
+        const available = getAvailableTypes();
+        return available.map((name) => {
             const cfg = getAgentConfig(name);
             const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
             const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
@@ -535,7 +546,6 @@ export default function (pi) {
         // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
         return name.replace(/-\d{8}$/, "");
     }
-    const typeListText = buildTypeListText();
     // Apply persisted settings on startup and emit `subagents:settings_loaded`.
     // Global + project merged; missing → defaults; corrupt file emits a warning
     // to stderr and falls back to defaults.
@@ -546,6 +556,7 @@ export default function (pi) {
         setDefaultJoinMode,
         setSchedulingEnabled,
         setScopeModels: setScopeModelsEnabled,
+        setDisableDefaultAgents: setDisableDefaultAgents,
     }, (event, payload) => pi.events.emit(event, payload));
     // ---- Agent tool ----
     // Schedule param + its guideline are gated on `schedulingEnabled` (read once
@@ -570,7 +581,7 @@ export default function (pi) {
         description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
 Available agent types and the tools they have access to:
-${typeListText}
+${buildTypeListText()}
 
 Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
 
@@ -1018,8 +1029,10 @@ Terse command-style prompts produce shallow, generic work.
             // Get final token count
             const tokenText = formatLifetimeTokens(fgState);
             const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
+            // "general-purpose" may itself be unregistered (defaults disabled, no
+            // user override) — getConfig then uses the hardcoded fallback config.
             const fallbackNote = fellBack
-                ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
+                ? `Note: Unknown agent type "${rawType}" — using ${resolveType("general-purpose") ? "general-purpose" : "the fallback agent config"}.\n\n`
                 : "";
             if (record.status === "error") {
                 return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
@@ -1690,6 +1703,7 @@ ${systemPrompt}
             defaultJoinMode: getDefaultJoinMode(),
             schedulingEnabled: isSchedulingEnabled(),
             scopeModels: isScopeModelsEnabled(),
+            disableDefaultAgents: isDefaultsDisabled(),
         };
     }
     const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
@@ -1741,6 +1755,13 @@ ${systemPrompt}
                     currentValue: isScopeModelsEnabled() ? "on" : "off",
                     values: ["on", "off"],
                 },
+                {
+                    id: "disableDefaultAgents",
+                    label: "Disable defaults",
+                    description: "Hide built-in agents (general-purpose, Explore, Plan) — custom agents are unaffected",
+                    currentValue: isDefaultsDisabled() ? "on" : "off",
+                    values: ["on", "off"],
+                },
             ];
         }
         function applyValue(id, value) {
@@ -1790,6 +1811,11 @@ ${systemPrompt}
                 setScopeModelsEnabled(enabled);
                 notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`);
             }
+            else if (id === "disableDefaultAgents") {
+                const enabled = value === "on";
+                setDisableDefaultAgents(enabled);
+                notifyApplied(ctx, `Default agents ${enabled ? "disabled" : "enabled"}. Tool spec change takes effect on next pi session.`);
+            }
         }
         let list;
         // Track current selection index directly (SettingsList doesn't expose it).

package/dist/settings.d.ts

@@ -40,6 +40,13 @@ export interface SubagentsSettings {
      * against. Defaults to false: subagents may use any model.
      */
     scopeModels?: boolean;
+    /**
+     * When true, the three built-in default agents (general-purpose, Explore, Plan)
+     * are not registered at startup. User-defined agents from .pi/agents/*.md are
+     * completely unaffected — only the hardcoded DEFAULT_AGENTS are suppressed.
+     * Defaults to false.
+     */
+    disableDefaultAgents?: boolean;
 }
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
 export interface SettingsAppliers {
@@ -49,6 +56,7 @@ export interface SettingsAppliers {
     setDefaultJoinMode: (mode: JoinMode) => void;
     setSchedulingEnabled: (b: boolean) => void;
     setScopeModels: (enabled: boolean) => void;
+    setDisableDefaultAgents: (b: boolean) => void;
 }
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
 export type SettingsEmit = (event: string, payload: unknown) => void;

package/dist/settings.js

@@ -41,6 +41,9 @@ function sanitize(raw) {
     if (typeof r.scopeModels === "boolean") {
         out.scopeModels = r.scopeModels;
     }
+    if (typeof r.disableDefaultAgents === "boolean") {
+        out.disableDefaultAgents = r.disableDefaultAgents;
+    }
     return out;
 }
 function globalPath() {
@@ -100,6 +103,8 @@ export function applySettings(s, appliers) {
         appliers.setSchedulingEnabled(s.schedulingEnabled);
     if (typeof s.scopeModels === "boolean")
         appliers.setScopeModels(s.scopeModels);
+    if (typeof s.disableDefaultAgents === "boolean")
+        appliers.setDisableDefaultAgents(s.disableDefaultAgents);
 }
 /**
  * Format the user-facing toast for a settings mutation. Pure function —

package/dist/types.d.ts

@@ -74,6 +74,7 @@ export interface AgentRecord {
     worktree?: {
         path: string;
         branch: string;
+        baseSha: string;
     };
     /** Worktree cleanup result after agent completion. */
     worktreeResult?: {

package/dist/worktree.d.ts

@@ -10,6 +10,8 @@ export interface WorktreeInfo {
     path: string;
     /** Branch name created for this worktree (if changes exist). */
     branch: string;
+    /** Commit SHA that the worktree was created from. */
+    baseSha: string;
 }
 export interface WorktreeCleanupResult {
     /** Whether changes were found in the worktree. */

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.10.0",
+  "version": "0.10.1",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-types.ts

@@ -24,6 +24,15 @@ export const BUILTIN_TOOL_NAMES: string[] = [
 /** 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).
@@ -32,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)

package/src/index.ts

@@ -17,7 +17,7 @@ import { Container, Key, matchesKey, type SettingItem, SettingsList, Spacer, Tex
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
-import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
@@ -521,6 +521,18 @@ export default function (pi: ExtensionAPI) {
   function isScopeModelsEnabled(): boolean { return scopeModelsEnabled; }
   function setScopeModelsEnabled(enabled: boolean): void { scopeModelsEnabled = enabled; }
 
+  // ---- Disable default agents configuration ----
+  // When enabled, the three hardcoded default agents (general-purpose, Explore,
+  // Plan) are not registered. User-defined agents from .pi/agents/*.md are
+  // completely unaffected — only DEFAULT_AGENTS are suppressed.
+  // Defaults to false; opt-in via `/agents → Settings` or subagents.json.
+  // State lives in agent-types.ts (isDefaultsDisabled) because registerAgents
+  // needs it; this wrapper just re-registers after flipping it.
+  function setDisableDefaultAgents(b: boolean): void {
+    setDefaultsDisabled(b);
+    reloadCustomAgents(); // re-register with new setting
+  }
+
   // ---- Batch tracking for smart join mode ----
   // Collects background agent IDs spawned in the current turn for smart grouping.
   // Uses a debounced timer: each new agent resets the 100ms window so that all
@@ -580,11 +592,11 @@ export default function (pi: ExtensionAPI) {
     return isFullSet ? "*" : tools.join(", ");
   };
 
-  /** Build the full type list text dynamically from the unified registry. */
+  /** Build the full type list text dynamically from available agents only. */
   const buildTypeListText = () => {
-    const allNames = [...getDefaultAgentNames(), ...getUserAgentNames()];
+    const available = getAvailableTypes();
 
-    return allNames.map((name) => {
+    return available.map((name) => {
       const cfg = getAgentConfig(name);
       const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
       const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
@@ -600,8 +612,6 @@ export default function (pi: ExtensionAPI) {
     return name.replace(/-\d{8}$/, "");
   }
 
-  const typeListText = buildTypeListText();
-
   // Apply persisted settings on startup and emit `subagents:settings_loaded`.
   // Global + project merged; missing → defaults; corrupt file emits a warning
   // to stderr and falls back to defaults.
@@ -613,6 +623,7 @@ export default function (pi: ExtensionAPI) {
       setDefaultJoinMode,
       setSchedulingEnabled,
       setScopeModels: setScopeModelsEnabled,
+      setDisableDefaultAgents: setDisableDefaultAgents,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -647,7 +658,7 @@ export default function (pi: ExtensionAPI) {
     description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
 Available agent types and the tools they have access to:
-${typeListText}
+${buildTypeListText()}
 
 Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
 
@@ -1157,8 +1168,10 @@ Terse command-style prompts produce shallow, generic work.
 
       const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
 
+      // "general-purpose" may itself be unregistered (defaults disabled, no
+      // user override) — getConfig then uses the hardcoded fallback config.
       const fallbackNote = fellBack
-        ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
+        ? `Note: Unknown agent type "${rawType}" — using ${resolveType("general-purpose") ? "general-purpose" : "the fallback agent config"}.\n\n`
         : "";
 
       if (record.status === "error") {
@@ -1855,6 +1868,7 @@ ${systemPrompt}
       defaultJoinMode: getDefaultJoinMode(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
+      disableDefaultAgents: isDefaultsDisabled(),
     };
   }
 
@@ -1909,6 +1923,13 @@ ${systemPrompt}
           currentValue: isScopeModelsEnabled() ? "on" : "off",
           values: ["on", "off"],
         },
+        {
+          id: "disableDefaultAgents",
+          label: "Disable defaults",
+          description: "Hide built-in agents (general-purpose, Explore, Plan) — custom agents are unaffected",
+          currentValue: isDefaultsDisabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
       ];
     }
 
@@ -1953,6 +1974,10 @@ ${systemPrompt}
         const enabled = value === "on";
         setScopeModelsEnabled(enabled);
         notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`);
+      } else if (id === "disableDefaultAgents") {
+        const enabled = value === "on";
+        setDisableDefaultAgents(enabled);
+        notifyApplied(ctx, `Default agents ${enabled ? "disabled" : "enabled"}. Tool spec change takes effect on next pi session.`);
       }
     }
 

package/src/settings.ts

@@ -48,6 +48,13 @@ export interface SubagentsSettings {
    * against. Defaults to false: subagents may use any model.
    */
   scopeModels?: boolean;
+  /**
+   * When true, the three built-in default agents (general-purpose, Explore, Plan)
+   * are not registered at startup. User-defined agents from .pi/agents/*.md are
+   * completely unaffected — only the hardcoded DEFAULT_AGENTS are suppressed.
+   * Defaults to false.
+   */
+  disableDefaultAgents?: boolean;
 }
 
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
@@ -58,6 +65,7 @@ export interface SettingsAppliers {
   setDefaultJoinMode: (mode: JoinMode) => void;
   setSchedulingEnabled: (b: boolean) => void;
   setScopeModels: (enabled: boolean) => void;
+  setDisableDefaultAgents: (b: boolean) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
@@ -107,6 +115,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.scopeModels === "boolean") {
     out.scopeModels = r.scopeModels;
   }
+  if (typeof r.disableDefaultAgents === "boolean") {
+    out.disableDefaultAgents = r.disableDefaultAgents;
+  }
   return out;
 }
 
@@ -163,6 +174,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
   if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);
+  if (typeof s.disableDefaultAgents === "boolean") appliers.setDisableDefaultAgents(s.disableDefaultAgents);
 }
 
 /**

package/src/types.ts

@@ -80,7 +80,7 @@ export interface AgentRecord {
   /** Steering messages queued before the session was ready. */
   pendingSteers?: string[];
   /** Worktree info if the agent is running in an isolated worktree. */
-  worktree?: { path: string; branch: string };
+  worktree?: { path: string; branch: string; baseSha: string };
   /** Worktree cleanup result after agent completion. */
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */

package/src/worktree.ts

@@ -17,6 +17,8 @@ export interface WorktreeInfo {
   path: string;
   /** Branch name created for this worktree (if changes exist). */
   branch: string;
+  /** Commit SHA that the worktree was created from. */
+  baseSha: string;
 }
 
 export interface WorktreeCleanupResult {
@@ -34,9 +36,12 @@ export interface WorktreeCleanupResult {
  */
 export function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined {
   // Verify we're in a git repo with at least one commit (HEAD must exist)
+  let baseSha: string;
   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;
   }
@@ -52,7 +57,7 @@ export function createWorktree(cwd: string, agentId: string): WorktreeInfo | und
       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)
     return undefined;
@@ -81,22 +86,30 @@ export function cleanupWorktree(
       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();
 
-    // 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,
-    });
+      if (currentSha === worktree.baseSha) {
+        // No changes — remove worktree
+        removeWorktree(cwd, worktree.path);
+        return { hasChanges: false };
+      }
+    }
 
     // Create a branch pointing to the worktree's HEAD.
     // If the branch already exists, append a suffix to avoid overwriting previous work.

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  // The print-mode e2e suite (test/subagents-print-mode-e2e.test.ts) drives REAL
+  // faux-model turns through pi-coding-agent + pi-agent-core. That requires ONE
+  // shared @earendil-works/pi-ai instance so the faux provider the test registers
+  // lands in the same api-registry the session streams through. npm physically
+  // duplicates pi-ai (a top-level copy and one nested under pi-coding-agent), which
+  // otherwise yields two registries and "No API provider registered" errors.
+  // Inlining the @earendil-works packages routes them through Vite's resolver so
+  // dedupe can collapse pi-ai to a single instance — for the parent AND for every
+  // subagent session the extension spawns. dedupe alone is insufficient (it only
+  // affects modules Vite resolves; without inline the runtime stays externalized).
+  test: {
+    server: { deps: { inline: [/@earendil-works\/pi-/] } },
+  },
+  resolve: { dedupe: ["@earendil-works/pi-ai"] },
+});