@tintinweb/pi-subagents 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-06-10
+
+### Added
+- **`exclude_extensions:` agent frontmatter — extension denylist for subagents** ([#94](https://github.com/tintinweb/pi-subagents/issues/94) — thanks [@ramhaidar](https://github.com/ramhaidar)). Applied after the `extensions:` include set; exclude wins, including over `tools: ext:` selectors (an excluded extension never loads, so its `ext:` reference becomes the usual orphan warning). The key use case: `extensions: true` + `exclude_extensions: pi-notify` — all extensions except a noisy one, without hand-maintaining an allowlist. Plain canonical names only (case-insensitive); paths, `*`, and unmatched names fire `extension-error:…` warnings (warn-not-abort, as with `extensions:` mismatches); `extensions: false` + an exclude warns that the exclude has no effect. **Not a sandbox:** excluded extensions' factory code still executes once during loading — exclusion suppresses handler binding and tool registration, not load-time side effects. The negation syntax `extensions: ["*", "!name"]` was deliberately rejected: an unquoted `!name` is a YAML tag and silently mis-parses.
+- **`toolDescriptionMode` setting — opt-in compact Agent tool description** ([#91](https://github.com/tintinweb/pi-subagents/issues/91) — thanks [@tiberiuichim](https://github.com/tiberiuichim)). The full Claude Code-style description costs ~1,400 tokens with the default agents and grows with each custom agent (the type list embeds full agent descriptions) — significant for small/local models. `toolDescriptionMode: "compact"` (via `/agents → Settings → Tool description` or `subagents.json`) swaps in a ~75% smaller description: one-line type list (first sentence of each agent description), terse usage notes, per-option details left to the parameter descriptions. Default `"full"` is byte-identical to before — the rich description's guardrails are deliberately load-bearing and stay the default. A third mode, `"custom"`, registers a user-authored description from `<cwd>/.pi/agent-tool-description.md` (project) or `<agentDir>/agent-tool-description.md` (global; project wins), with `{{placeholder}}` substitution keeping the dynamic parts live — `{{typeList}}`, `{{compactTypeList}}`, `{{agentDir}}`, `{{scheduleGuideline}}` — so a hand-written description can't drift out of sync with the registered agents (the advertised-vs-spawnable staleness [#92](https://github.com/tintinweb/pi-subagents/issues/92) just fixed). Unknown placeholders are left verbatim with a stderr warning; a missing/empty file falls back to `"full"`. Only the prose is customizable — the parameter schema stays code-owned. A ready-made starting point ships at `examples/agent-tool-description.md`, reproducing the full description exactly (CI-enforced byte-identical, so the example can't go stale). Like `schedulingEnabled`, the mode is read at tool registration — changing it applies on the next pi session. The issue's original ask (move the description to a skill) isn't possible in pi: tools must register their description in the tool schema for the model to call them; skills are lazily-loaded instructions, not tool registrations.
+
+### Fixed
+- **Conversation viewer honors custom `tui.select.*` keybindings** ([#99](https://github.com/tintinweb/pi-subagents/issues/99) — thanks [@owenniles](https://github.com/owenniles)). The viewer hardcoded its scroll keys and discarded the `KeybindingsManager` pi injects into `ctx.ui.custom()`, so user bindings (e.g. emacs-style `ctrl+p`/`ctrl+n` on `tui.select.up`/`down`) worked in pi core selectors but not here. Scrolling now resolves through `tui.select.up`/`down`/`pageUp`/`pageDown`; the viewer-specific `k`/`j` and `shift+arrow` aliases still work alongside, and behavior without custom bindings is unchanged (the `tui.select.*` defaults are the previously hardcoded keys).
+
+## [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

@@ -196,6 +196,7 @@ All fields are optional — sensible defaults for everything.
 | `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `tools` | all 7 | Which tools the agent can call. Built-in names (`read, grep, …`), `*` / `all` (all built-ins), `none`, and `ext:<extension>` / `ext:<extension>/<tool>` selectors for extension tools. See [Tool & extension scoping](#tool--extension-scoping) below |
 | `extensions` | `true` | Which extensions to load for the agent. `true` (all defaults), `false` (none), or an explicit list: `[mcp, "/abs/path.ts", "*"]`. See [Tool & extension scoping](#tool--extension-scoping) below |
+| `exclude_extensions` | — | Extension denylist applied after `extensions:` — exclude wins. Plain names only (case-insensitive), no paths or `*`. Useful with `extensions: true` to drop one extension (e.g. `pi-notify`) |
 | `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations) |
 | `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
@@ -227,6 +228,8 @@ extensions: false                 # no extensions load
 extensions: [mcp]                 # only mcp loads
 extensions: ["*", "/abs/foo.ts"]  # all defaults plus one path-loaded extension
 
+exclude_extensions: pi-notify     # everything except pi-notify (with extensions: true)
+
 # Specialist: load one extension, expose only one of its tools, keep built-ins
 extensions: [mcp]
 tools: "*, ext:mcp/search"
@@ -240,6 +243,8 @@ A few rules the examples don't make obvious:
 - Any `ext:` entry flips extension tools to an explicit allowlist — unnamed extensions still load (handlers fire) but expose no tools. So `tools: "*, ext:mcp/search"` exposes only `search` from `mcp`, nothing from any other extension.
 - Extension names match case-insensitively (`[Mcp]` = `[mcp]`); tool names in `ext:foo/bar` stay case-sensitive.
 - Plain `tools:` typos fail loudly: `tools: reed, grep` fires `tools-error:…` instead of silently producing an under-tooled agent.
+- `exclude_extensions:` wins over `extensions:` and over `ext:` selectors — an excluded extension never loads and a `tools: ext:` entry can't pull it back. Plain names only (no paths, no `*`); a name matching nothing fires an `extension-error:…` warning.
+- `exclude_extensions:` is **not a sandbox**: excluded extensions' factory code still executes once during loading — exclusion suppresses their handlers and tools, not their load-time side effects. Don't rely on it to contain an untrusted extension.
 - Array and string forms are equivalent: `[a, b]` == `"a, b"`.
 
 ## Tools
@@ -365,12 +370,29 @@ 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, tool description full/compact/custom) 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).
+
+**Tool description** (`toolDescriptionMode`, default `"full"`): which Agent tool description the LLM sees. `"full"` is the rich Claude Code-style prompt (~1,400 tokens with the default agents); `"compact"` is ~75% smaller — one-line agent type list, terse usage notes — for small/local models where tool-spec tokens are expensive. Per-option details stay in the parameter descriptions in every mode (the parameter schema is never customizable). Applies on the next pi session.
+
+`"custom"` registers your own description from `<cwd>/.pi/agent-tool-description.md` (project) or `<agentDir>/agent-tool-description.md` (global; project wins). The file is read once at tool registration, so edits also apply on the next pi session. Dynamic parts stay live via placeholders — a static agent list would go stale the moment you add a custom agent:
+
+```markdown
+Launch an autonomous agent. Available types:
+{{typeList}}
+
+Custom agents live in .pi/agents/ or {{agentDir}}/agents/.
+```
+
+Placeholders: `{{typeList}}` (full per-agent descriptions), `{{compactTypeList}}` (first sentence each), `{{agentDir}}`, `{{scheduleGuideline}}` (expands with its own leading newline + `- ` bullet when scheduling is on — place it directly after your last rule line; empty when scheduling is off). Unknown placeholders are left verbatim with a stderr warning; a missing or empty file falls back to `"full"` with a warning. Note the usual trust umbrella: a project-level file shapes the orchestrator's prompt, same as project agents and extensions do.
+
+**Starting point:** copy [`examples/agent-tool-description.md`](examples/agent-tool-description.md) — it reproduces the default full description exactly (a CI test keeps it in sync), so you can trim from a known-good baseline instead of writing from scratch.
 
 **Example — global defaults for a beefy machine:**
 
@@ -507,6 +529,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-runner.js

@@ -206,6 +206,9 @@ export async function runAgent(ctx, type, prompt, options) {
     const extras = {};
     // Resolve extensions/skills: isolated overrides to false
     const extensions = options.isolated ? false : config.extensions;
+    // Nulling excludes under isolated also suppresses the orphaned-exclude warning —
+    // isolation is an intentional override, not a misconfiguration.
+    const excludeExtensions = options.isolated ? undefined : config.excludeExtensions;
     const skills = options.isolated ? false : config.skills;
     // Skill preloading: when skills is string[], preload their content into prompt
     if (Array.isArray(skills)) {
@@ -277,17 +280,35 @@ export async function runAgent(ctx, type, prompt, options) {
         ? parseExtensionsSpec(extensions, effectiveCwd)
         : undefined;
     const keepNames = extensionsSpec?.names ?? new Set();
-    // 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`).
+    // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
+    // Plain canonical names only (case-insensitive). Note: excluded extensions'
+    // factories still run once during reload() (see comment above) — exclusion
+    // suppresses handler binding and tool registration; it is not a sandbox.
+    const excludeNames = new Set((excludeExtensions ?? []).map((n) => n.toLowerCase()));
+    const hasExcludes = excludeNames.size > 0;
+    // The override filters loaded extensions down to `keepNames` minus `excludeNames`.
+    // It's only needed when we're neither loading everything without excludes
+    // (`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 = loadAll || noExtensions
+    // Pre-filter discovered set, captured by the override — the exclude-typo warning
+    // must compare against this, not the surviving set (absence from survivors is
+    // an exclude *succeeding*).
+    let discoveredNames;
+    const extensionsOverride = noExtensions || (loadAll && !hasExcludes)
         ? undefined
-        : (base) => ({
-            ...base,
-            extensions: base.extensions.filter((e) => keepNames.has(extensionCanonicalName(e.path))),
-        });
+        : (base) => {
+            discoveredNames = new Set(base.extensions.map((e) => extensionCanonicalName(e.path)));
+            return {
+                ...base,
+                extensions: base.extensions.filter((e) => {
+                    const name = extensionCanonicalName(e.path);
+                    if (excludeNames.has(name))
+                        return false; // exclude wins
+                    return loadAll || keepNames.has(name);
+                }),
+            };
+        };
     const loader = new DefaultResourceLoader({
         cwd: effectiveCwd,
         agentDir,
@@ -325,13 +346,36 @@ export async function runAgent(ctx, type, prompt, options) {
     //   - `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.
+    // An exclude_extensions: alongside extensions: false is contradictory — nothing
+    // loads, so there is nothing to exclude.
+    if (hasExcludes && noExtensions) {
+        options.onToolActivity?.({
+            type: "end",
+            toolName: `extension-error:exclude_extensions has no effect for agent "${type}" — extensions: false loads nothing`,
+        });
+    }
+    // Exclude typo check: compares against the PRE-filter discovered set (an excluded
+    // name absent from the surviving set is the exclude working as intended). Also
+    // flags path-like and "*" entries — excludes are plain names only.
+    if (hasExcludes && discoveredNames) {
+        for (const name of excludeNames) {
+            if (!discoveredNames.has(name)) {
+                options.onToolActivity?.({
+                    type: "end",
+                    toolName: `extension-error:exclude_extensions: "${name}" for agent "${type}" did not match any discovered extension`,
+                });
+            }
+        }
+    }
     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`,
+                    toolName: excludeNames.has(name)
+                        ? `extension-error:extension "${name}" is in both extensions: and exclude_extensions: for agent "${type}" — exclude wins`
+                        : `extension-error:extension "${name}" requested by agent "${type}" was not loaded`,
                 });
             }
         }
@@ -339,7 +383,7 @@ export async function runAgent(ctx, type, prompt, options) {
             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:)`,
+                    toolName: `extension-error:ext:${name} referenced by agent "${type}" but extension "${name}" is not loaded (check extensions:/exclude_extensions:)`,
                 });
             }
         }

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).
@@ -50,6 +54,7 @@ export declare function getConfig(type: string): {
     description: string;
     builtinToolNames: string[];
     extensions: true | string[] | false;
+    excludeExtensions?: string[];
     skills: true | string[] | false;
     promptMode: "replace" | "append";
 };

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) {
@@ -119,6 +127,7 @@ export function getConfig(type) {
             description: config.description,
             builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: config.extensions,
+            excludeExtensions: config.excludeExtensions,
             skills: config.skills,
             promptMode: config.promptMode,
         };
@@ -131,6 +140,7 @@ export function getConfig(type) {
             description: gp.description,
             builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: gp.extensions,
+            excludeExtensions: gp.excludeExtensions,
             skills: gp.skills,
             promptMode: gp.promptMode,
         };

package/dist/custom-agents.js

@@ -52,6 +52,7 @@ function loadFromDir(dir, agents, source) {
             extSelectors,
             disallowedTools: csvListOptional(fm.disallowed_tools),
             extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+            excludeExtensions: csvListOptional(fm.exclude_extensions),
             skills: inheritField(fm.skills ?? fm.inherit_skills),
             model: str(fm.model),
             thinking: str(fm.thinking),

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,24 @@ 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
+    }
+    // ---- Agent tool description mode ----
+    // "full" (default) keeps the rich Claude Code-style description; "compact"
+    // swaps in a ~75% smaller one for small/local models (#91). Read once at
+    // tool registration — flipping it applies on the next pi session.
+    let toolDescriptionMode = "full";
+    function getToolDescriptionMode() { return toolDescriptionMode; }
+    function setToolDescriptionMode(mode) { toolDescriptionMode = mode; }
     // ---- 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,16 +536,26 @@ 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)})`;
             return `- ${name}: ${cfg?.description ?? name}${modelSuffix}${toolsSuffix}`;
         }).join("\n");
     };
+    /** First sentence of an agent description — for the compact type list. */
+    const firstSentence = (text) => {
+        const match = text.match(/^.*?[.!?](?=\s|$)/s);
+        return (match ? match[0] : text).replace(/\s+/g, " ").trim();
+    };
+    /** Compact type list: one line per agent, first sentence only. */
+    const buildCompactTypeListText = () => getAvailableTypes().map((name) => {
+        const cfg = getAgentConfig(name);
+        return `- ${name}: ${firstSentence(cfg?.description ?? name)} (Tools: ${formatToolsSuffix(cfg)})`;
+    }).join("\n");
     /** Derive a short model label from a model string. */
     function getModelLabelFromConfig(model) {
         // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
@@ -535,7 +563,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 +573,8 @@ export default function (pi) {
         setDefaultJoinMode,
         setSchedulingEnabled,
         setScopeModels: setScopeModelsEnabled,
+        setDisableDefaultAgents: setDisableDefaultAgents,
+        setToolDescriptionMode: setToolDescriptionMode,
     }, (event, payload) => pi.events.emit(event, payload));
     // ---- Agent tool ----
     // Schedule param + its guideline are gated on `schedulingEnabled` (read once
@@ -564,13 +593,24 @@ export default function (pi) {
     const scheduleGuideline = isSchedulingEnabled()
         ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
         : "";
-    pi.registerTool(defineTool({
-        name: SUBAGENT_TOOL_NAMES.AGENT,
-        label: "Agent",
-        description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
+    // Compact Agent tool description (#91, `toolDescriptionMode: "compact"`) —
+    // the same load-bearing facts as the full version at ~75% fewer tokens, for
+    // small/local models. Per-option details live in the param descriptions.
+    const compactAgentToolDescription = `Launch an autonomous agent for complex, multi-step tasks. Agent types:
+${buildCompactTypeListText()}
+
+Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global).
+
+Notes:
+- description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
+- Parallel work: one message, multiple Agent calls, run_in_background: true on each. You are notified when background agents finish — never poll or sleep.
+- The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
+- resume continues a previous agent by ID; steer_subagent messages a running one.
+- isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.`;
+    const fullAgentToolDescription = `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.
 
@@ -608,7 +648,61 @@ Provide clear, detailed prompts so the agent can work autonomously. Brief it lik
 
 Terse command-style prompts produce shallow, generic work.
 
-**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.`,
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.`;
+    // `toolDescriptionMode: "custom"` — user-authored description with live
+    // dynamic parts. Project file wins over global; missing/empty falls back to
+    // "full" (a stale fallback beats a blank tool description). Only the prose
+    // is customizable — the parameter schema stays code-owned.
+    const renderToolDescriptionTemplate = (template) => {
+        const vars = {
+            typeList: buildTypeListText,
+            compactTypeList: buildCompactTypeListText,
+            agentDir: getAgentDir,
+            scheduleGuideline: () => scheduleGuideline,
+        };
+        // Replacement callback (not a string) — agent descriptions may contain `$&` etc.
+        return template.replace(/\{\{(\w+)\}\}/g, (raw, name) => {
+            if (vars[name])
+                return vars[name]();
+            console.warn(`[pi-subagents] agent-tool-description.md: unknown placeholder ${raw} left as-is`);
+            return raw;
+        });
+    };
+    const loadCustomToolDescription = () => {
+        for (const path of [
+            join(process.cwd(), ".pi", "agent-tool-description.md"),
+            join(getAgentDir(), "agent-tool-description.md"),
+        ]) {
+            try {
+                if (!existsSync(path))
+                    continue;
+                const text = readFileSync(path, "utf-8").trim();
+                if (text)
+                    return renderToolDescriptionTemplate(text);
+                console.warn(`[pi-subagents] ${path} is empty — ignoring`);
+            }
+            catch (err) {
+                console.warn(`[pi-subagents] failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return undefined;
+    };
+    const agentToolDescription = (() => {
+        const mode = getToolDescriptionMode();
+        if (mode === "compact")
+            return compactAgentToolDescription;
+        if (mode === "custom") {
+            const custom = loadCustomToolDescription();
+            if (custom)
+                return custom;
+            console.warn('[pi-subagents] toolDescriptionMode is "custom" but no agent-tool-description.md found — using "full"');
+        }
+        return fullAgentToolDescription;
+    })();
+    pi.registerTool(defineTool({
+        name: SUBAGENT_TOOL_NAMES.AGENT,
+        label: "Agent",
+        description: agentToolDescription,
         promptSnippet: "Launch autonomous sub-agents for complex multi-step tasks",
         promptGuidelines: [
             "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
@@ -1018,8 +1112,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);
@@ -1313,12 +1409,12 @@ Terse command-style prompts produce shallow, generic work.
         const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import("./ui/conversation-viewer.js");
         const session = record.session;
         const activity = agentActivity.get(record.id);
-        await ctx.ui.custom((tui, theme, _keybindings, done) => {
+        await ctx.ui.custom((tui, theme, keybindings, done) => {
             return new ConversationViewer(tui, session, record, activity, theme, done, () => {
                 if (manager.abort(record.id)) {
                     ctx.ui.notify(`Stopped "${record.description}".`, "info");
                 }
-            });
+            }, keybindings);
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
@@ -1426,6 +1522,8 @@ Terse command-style prompts produce shallow, generic work.
             fmFields.push("extensions: false");
         else if (Array.isArray(cfg.extensions))
             fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+        if (cfg.excludeExtensions?.length)
+            fmFields.push(`exclude_extensions: ${cfg.excludeExtensions.join(", ")}`);
         if (cfg.skills === false)
             fmFields.push("skills: false");
         else if (Array.isArray(cfg.skills))
@@ -1690,6 +1788,8 @@ ${systemPrompt}
             defaultJoinMode: getDefaultJoinMode(),
             schedulingEnabled: isSchedulingEnabled(),
             scopeModels: isScopeModelsEnabled(),
+            disableDefaultAgents: isDefaultsDisabled(),
+            toolDescriptionMode: getToolDescriptionMode(),
         };
     }
     const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
@@ -1741,6 +1841,20 @@ ${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"],
+                },
+                {
+                    id: "toolDescriptionMode",
+                    label: "Tool description",
+                    description: "Agent tool description sent to the LLM: full (rich, default), compact (~75% fewer tokens, for small/local models), or custom (.pi/agent-tool-description.md with {{placeholders}})",
+                    currentValue: getToolDescriptionMode(),
+                    values: ["full", "compact", "custom"],
+                },
             ];
         }
         function applyValue(id, value) {
@@ -1790,6 +1904,15 @@ ${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.`);
+            }
+            else if (id === "toolDescriptionMode") {
+                setToolDescriptionMode(value);
+                notifyApplied(ctx, `Tool description set to ${value}. Takes effect on next pi session.`);
+            }
         }
         let list;
         // Track current selection index directly (SettingsList doesn't expose it).

package/dist/settings.d.ts

@@ -40,7 +40,26 @@ 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;
+    /**
+     * Which Agent tool description the LLM sees. "full" (default) is the rich
+     * Claude Code-style prompt; "compact" is a ~75% smaller version (one-line
+     * agent type list, terse usage notes) for small/local models where tool-spec
+     * tokens are expensive; "custom" reads `.pi/agent-tool-description.md`
+     * (project, falling back to `<agentDir>/agent-tool-description.md`) with
+     * `{{placeholder}}` substitution — a missing/empty file falls back to "full".
+     * The mode is read once at tool registration — changing it applies on the
+     * next pi session.
+     */
+    toolDescriptionMode?: ToolDescriptionMode;
 }
+export type ToolDescriptionMode = "full" | "compact" | "custom";
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
 export interface SettingsAppliers {
     setMaxConcurrent: (n: number) => void;
@@ -49,6 +68,8 @@ export interface SettingsAppliers {
     setDefaultJoinMode: (mode: JoinMode) => void;
     setSchedulingEnabled: (b: boolean) => void;
     setScopeModels: (enabled: boolean) => void;
+    setDisableDefaultAgents: (b: boolean) => void;
+    setToolDescriptionMode: (mode: ToolDescriptionMode) => 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

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 const VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
+const VALID_TOOL_DESCRIPTION_MODES = new Set(["full", "compact", "custom"]);
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
 // that any realistic power-user setting passes through.
@@ -41,6 +42,12 @@ function sanitize(raw) {
     if (typeof r.scopeModels === "boolean") {
         out.scopeModels = r.scopeModels;
     }
+    if (typeof r.disableDefaultAgents === "boolean") {
+        out.disableDefaultAgents = r.disableDefaultAgents;
+    }
+    if (typeof r.toolDescriptionMode === "string" && VALID_TOOL_DESCRIPTION_MODES.has(r.toolDescriptionMode)) {
+        out.toolDescriptionMode = r.toolDescriptionMode;
+    }
     return out;
 }
 function globalPath() {
@@ -100,6 +107,10 @@ 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);
+    if (s.toolDescriptionMode)
+        appliers.setToolDescriptionMode(s.toolDescriptionMode);
 }
 /**
  * Format the user-facing toast for a settings mutation. Pure function —

package/dist/types.d.ts

@@ -26,6 +26,9 @@ export interface AgentConfig {
     disallowedTools?: string[];
     /** true = inherit all, string[] = only listed, false = none */
     extensions: true | string[] | false;
+    /** Extension-name denylist applied after the `extensions:` include set. Exclude wins.
+     * Plain canonical names only (case-insensitive); no paths, no wildcard. */
+    excludeExtensions?: string[];
     /** true = inherit all, string[] = only listed, false = none */
     skills: true | string[] | false;
     model?: string;
@@ -74,6 +77,7 @@ export interface AgentRecord {
     worktree?: {
         path: string;
         branch: string;
+        baseSha: string;
     };
     /** Worktree cleanup result after agent completion. */
     worktreeResult?: {