@tintinweb/pi-subagents 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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

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,7 +370,7 @@ 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, disable defaults 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.
@@ -374,6 +379,21 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 **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:**
 
 ```bash

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

@@ -54,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

@@ -127,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,
         };
@@ -139,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

@@ -473,6 +473,13 @@ export default function (pi) {
         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
@@ -539,6 +546,16 @@ export default function (pi) {
             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")
@@ -557,6 +574,7 @@ export default function (pi) {
         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
@@ -575,10 +593,21 @@ 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:
 ${buildTypeListText()}
@@ -619,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.",
@@ -1326,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}%` },
@@ -1439,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))
@@ -1704,6 +1789,7 @@ ${systemPrompt}
             schedulingEnabled: isSchedulingEnabled(),
             scopeModels: isScopeModelsEnabled(),
             disableDefaultAgents: isDefaultsDisabled(),
+            toolDescriptionMode: getToolDescriptionMode(),
         };
     }
     const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
@@ -1762,6 +1848,13 @@ ${systemPrompt}
                     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) {
@@ -1816,6 +1909,10 @@ ${systemPrompt}
                 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

@@ -47,7 +47,19 @@ export interface SubagentsSettings {
      * 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;
@@ -57,6 +69,7 @@ export interface SettingsAppliers {
     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.
@@ -44,6 +45,9 @@ function sanitize(raw) {
     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() {
@@ -105,6 +109,8 @@ export function applySettings(s, appliers) {
         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;

package/dist/ui/conversation-viewer.d.ts

@@ -9,6 +9,7 @@ import { type Component, type TUI } from "@earendil-works/pi-tui";
 import type { AgentRecord } from "../types.js";
 import type { Theme } from "./agent-widget.js";
 import { type AgentActivity } from "./agent-widget.js";
+import { type ViewerKeybindings } from "./viewer-keys.js";
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export declare const VIEWPORT_HEIGHT_PCT = 70;
 export declare class ConversationViewer implements Component {
@@ -27,9 +28,12 @@ export declare class ConversationViewer implements Component {
     private closed;
     /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
     private stopArmed;
+    private keys;
     constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void, 
     /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
-    onStop?: (() => void) | undefined);
+    onStop?: (() => void) | undefined, 
+    /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */
+    keybindings?: ViewerKeybindings);
     handleInput(data: string): void;
     render(width: number): string[];
     /** Stoppable only when a stop handler exists and the agent is still active. */

package/dist/ui/conversation-viewer.js

@@ -8,6 +8,7 @@ import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@ea
 import { extractText } from "../context.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import { createViewerKeys } from "./viewer-keys.js";
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
@@ -28,9 +29,12 @@ export class ConversationViewer {
     closed = false;
     /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
     stopArmed = false;
+    keys;
     constructor(tui, session, record, activity, theme, done, 
     /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
-    onStop) {
+    onStop, 
+    /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */
+    keybindings) {
         this.tui = tui;
         this.session = session;
         this.record = record;
@@ -38,6 +42,7 @@ export class ConversationViewer {
         this.theme = theme;
         this.done = done;
         this.onStop = onStop;
+        this.keys = createViewerKeys(keybindings);
         this.unsubscribe = session.subscribe(() => {
             if (this.closed)
                 return;
@@ -70,19 +75,19 @@ export class ConversationViewer {
         const totalLines = this.buildContentLines(this.lastInnerW).length;
         const viewportHeight = this.viewportHeight();
         const maxScroll = Math.max(0, totalLines - viewportHeight);
-        if (matchesKey(data, "up") || matchesKey(data, "k")) {
+        if (this.keys.scrollUp(data)) {
             this.scrollOffset = Math.max(0, this.scrollOffset - 1);
             this.autoScroll = this.scrollOffset >= maxScroll;
         }
-        else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+        else if (this.keys.scrollDown(data)) {
             this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
             this.autoScroll = this.scrollOffset >= maxScroll;
         }
-        else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
+        else if (this.keys.pageUp(data)) {
             this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
             this.autoScroll = false;
         }
-        else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
+        else if (this.keys.pageDown(data)) {
             this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
             this.autoScroll = this.scrollOffset >= maxScroll;
         }

package/dist/ui/viewer-keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+/** The `tui.select.*` keybinding ids the viewer resolves. */
+export type ViewerScrollKeybinding = "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown";
+/** Structural subset of pi-tui's `KeybindingsManager` (which satisfies it). */
+export interface ViewerKeybindings {
+    matches(data: string, keybinding: ViewerScrollKeybinding): boolean;
+}
+export interface ViewerKeys {
+    scrollUp(data: string): boolean;
+    scrollDown(data: string): boolean;
+    pageUp(data: string): boolean;
+    pageDown(data: string): boolean;
+}
+export declare function createViewerKeys(keybindings?: ViewerKeybindings): ViewerKeys;

package/dist/ui/viewer-keys.js

@@ -0,0 +1,17 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+import { matchesKey } from "@earendil-works/pi-tui";
+export function createViewerKeys(keybindings) {
+    const matches = (data, id, fallback) => keybindings ? keybindings.matches(data, id) : matchesKey(data, fallback);
+    return {
+        scrollUp: (data) => matches(data, "tui.select.up", "up") || matchesKey(data, "k"),
+        scrollDown: (data) => matches(data, "tui.select.down", "down") || matchesKey(data, "j"),
+        pageUp: (data) => matches(data, "tui.select.pageUp", "pageUp") || matchesKey(data, "shift+up"),
+        pageDown: (data) => matches(data, "tui.select.pageDown", "pageDown") || matchesKey(data, "shift+down"),
+    };
+}

package/examples/agent-tool-description.md

@@ -0,0 +1,42 @@
+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:
+{{typeList}}
+
+Custom agents can be defined in .pi/agents/<name>.md (project) or {{agentDir}}/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.
+
+When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
+
+## When not to use
+
+If the target is already known, use a direct tool — `read` for a known path, `grep`/`find` for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.
+
+## Usage notes
+
+- Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
+- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
+- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
+- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
+- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
+- Use steer_subagent to send mid-run messages to a running background agent.
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
+- If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
+- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
+- Use thinking to control extended thinking level.
+- Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
+
+## Writing the prompt
+
+Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-runner.ts

@@ -296,6 +296,9 @@ export async function runAgent(
 
   // 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
@@ -373,18 +376,35 @@ export async function runAgent(
     ? 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`).
+  // `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;
+  // 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: Set<string> | undefined;
   const extensionsOverride: ((base: LoadExtensionsResult) => LoadExtensionsResult) | undefined =
-    loadAll || noExtensions
+    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,
@@ -425,6 +445,27 @@ export async function runAgent(
   //   - `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)),
@@ -433,7 +474,9 @@ export async function runAgent(
       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`,
         });
       }
     }
@@ -441,7 +484,7 @@ export async function runAgent(
       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/src/agent-types.ts

@@ -144,6 +144,7 @@ export function getConfig(type: string): {
   description: string;
   builtinToolNames: string[];
   extensions: true | string[] | false;
+  excludeExtensions?: string[];
   skills: true | string[] | false;
   promptMode: "replace" | "append";
 } {
@@ -155,6 +156,7 @@ export function getConfig(type: string): {
       description: config.description,
       builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: config.extensions,
+      excludeExtensions: config.excludeExtensions,
       skills: config.skills,
       promptMode: config.promptMode,
     };
@@ -168,6 +170,7 @@ export function getConfig(type: string): {
       description: gp.description,
       builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: gp.extensions,
+      excludeExtensions: gp.excludeExtensions,
       skills: gp.skills,
       promptMode: gp.promptMode,
     };

package/src/custom-agents.ts

@@ -60,6 +60,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       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) as ThinkingLevel | undefined,

package/src/index.ts

@@ -27,7 +27,7 @@ import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
-import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
+import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
 import { getStatusNote } from "./status-note.js";
 import { type AgentConfig, type AgentInvocation, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
@@ -533,6 +533,14 @@ export default function (pi: ExtensionAPI) {
     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: ToolDescriptionMode = "full";
+  function getToolDescriptionMode(): ToolDescriptionMode { return toolDescriptionMode; }
+  function setToolDescriptionMode(mode: ToolDescriptionMode): void { 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
@@ -604,6 +612,19 @@ export default function (pi: ExtensionAPI) {
     }).join("\n");
   };
 
+  /** First sentence of an agent description — for the compact type list. */
+  const firstSentence = (text: string): string => {
+    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: string): string {
     // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
@@ -624,6 +645,7 @@ export default function (pi: ExtensionAPI) {
       setSchedulingEnabled,
       setScopeModels: setScopeModelsEnabled,
       setDisableDefaultAgents: setDisableDefaultAgents,
+      setToolDescriptionMode: setToolDescriptionMode,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -652,10 +674,22 @@ export default function (pi: ExtensionAPI) {
     ? `\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:
 ${buildTypeListText()}
@@ -696,7 +730,59 @@ 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: string): string => {
+    const vars: Record<string, () => string> = {
+      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: string) => {
+      if (vars[name]) return vars[name]();
+      console.warn(`[pi-subagents] agent-tool-description.md: unknown placeholder ${raw} left as-is`);
+      return raw;
+    });
+  };
+
+  const loadCustomToolDescription = (): string | undefined => {
+    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.",
@@ -1494,12 +1580,12 @@ Terse command-style prompts produce shallow, generic work.
     const activity = agentActivity.get(record.id);
 
     await ctx.ui.custom<undefined>(
-      (tui, theme, _keybindings, done) => {
+      (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,
@@ -1601,6 +1687,7 @@ Terse command-style prompts produce shallow, generic work.
     fmFields.push(`prompt_mode: ${cfg.promptMode}`);
     if (cfg.extensions === false) 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)) fmFields.push(`skills: ${cfg.skills.join(", ")}`);
     if (cfg.disallowedTools?.length) fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
@@ -1869,6 +1956,7 @@ ${systemPrompt}
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
       disableDefaultAgents: isDefaultsDisabled(),
+      toolDescriptionMode: getToolDescriptionMode(),
     };
   }
 
@@ -1930,6 +2018,13 @@ ${systemPrompt}
           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"],
+        },
       ];
     }
 
@@ -1978,6 +2073,9 @@ ${systemPrompt}
         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 as ToolDescriptionMode);
+        notifyApplied(ctx, `Tool description set to ${value}. Takes effect on next pi session.`);
       }
     }
 

package/src/settings.ts

@@ -55,8 +55,21 @@ export interface SubagentsSettings {
    * 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;
@@ -66,12 +79,14 @@ export interface SettingsAppliers {
   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;
 
 const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
+const VALID_TOOL_DESCRIPTION_MODES: ReadonlySet<string> = new Set<ToolDescriptionMode>(["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
@@ -118,6 +133,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   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 as ToolDescriptionMode;
+  }
   return out;
 }
 
@@ -175,6 +193,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   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);
+  if (s.toolDescriptionMode) appliers.setToolDescriptionMode(s.toolDescriptionMode);
 }
 
 /**

package/src/types.ts

@@ -33,6 +33,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;

package/src/ui/conversation-viewer.ts

@@ -12,6 +12,7 @@ import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-widget.js";
 import { type AgentActivity, buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
 
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
@@ -27,6 +28,7 @@ export class ConversationViewer implements Component {
   private closed = false;
   /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
   private stopArmed = false;
+  private keys: ViewerKeys;
 
   constructor(
     private tui: TUI,
@@ -37,7 +39,10 @@ export class ConversationViewer implements Component {
     private done: (result: undefined) => void,
     /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
     private onStop?: () => void,
+    /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */
+    keybindings?: ViewerKeybindings,
   ) {
+    this.keys = createViewerKeys(keybindings);
     this.unsubscribe = session.subscribe(() => {
       if (this.closed) return;
       this.tui.requestRender();
@@ -71,16 +76,16 @@ export class ConversationViewer implements Component {
     const viewportHeight = this.viewportHeight();
     const maxScroll = Math.max(0, totalLines - viewportHeight);
 
-    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+    if (this.keys.scrollUp(data)) {
       this.scrollOffset = Math.max(0, this.scrollOffset - 1);
       this.autoScroll = this.scrollOffset >= maxScroll;
-    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+    } else if (this.keys.scrollDown(data)) {
       this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
       this.autoScroll = this.scrollOffset >= maxScroll;
-    } else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
+    } else if (this.keys.pageUp(data)) {
       this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
       this.autoScroll = false;
-    } else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
+    } else if (this.keys.pageDown(data)) {
       this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
       this.autoScroll = this.scrollOffset >= maxScroll;
     } else if (matchesKey(data, "home")) {

package/src/ui/viewer-keys.ts

@@ -0,0 +1,39 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+/** The `tui.select.*` keybinding ids the viewer resolves. */
+export type ViewerScrollKeybinding =
+  | "tui.select.up"
+  | "tui.select.down"
+  | "tui.select.pageUp"
+  | "tui.select.pageDown";
+
+/** Structural subset of pi-tui's `KeybindingsManager` (which satisfies it). */
+export interface ViewerKeybindings {
+  matches(data: string, keybinding: ViewerScrollKeybinding): boolean;
+}
+
+export interface ViewerKeys {
+  scrollUp(data: string): boolean;
+  scrollDown(data: string): boolean;
+  pageUp(data: string): boolean;
+  pageDown(data: string): boolean;
+}
+
+export function createViewerKeys(keybindings?: ViewerKeybindings): ViewerKeys {
+  const matches = (data: string, id: ViewerScrollKeybinding, fallback: KeyId): boolean =>
+    keybindings ? keybindings.matches(data, id) : matchesKey(data, fallback);
+  return {
+    scrollUp: (data) => matches(data, "tui.select.up", "up") || matchesKey(data, "k"),
+    scrollDown: (data) => matches(data, "tui.select.down", "down") || matchesKey(data, "j"),
+    pageUp: (data) => matches(data, "tui.select.pageUp", "pageUp") || matchesKey(data, "shift+up"),
+    pageDown: (data) => matches(data, "tui.select.pageDown", "pageDown") || matchesKey(data, "shift+down"),
+  };
+}