@tintinweb/pi-subagents 0.10.1 → 0.10.3

package/src/agent-manager.ts

@@ -7,6 +7,8 @@
  */
 
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
@@ -22,6 +24,28 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
+/**
+ * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
+ * (parent cwd). Anything else must be an absolute path to an existing
+ * directory — curated errors instead of TypeErrors from path/fs internals
+ * (RPC callers send arbitrary JSON: null, numbers, file paths).
+ */
+function assertValidSpawnCwd(cwd: unknown): asserts cwd is string | undefined | null {
+  if (cwd == null) return;
+  if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+    throw new Error(`SpawnOptions.cwd must be an absolute path: "${String(cwd)}"`);
+  }
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(cwd).isDirectory();
+  } catch {
+    throw new Error(`SpawnOptions.cwd does not exist: "${cwd}"`);
+  }
+  if (!isDirectory) {
+    throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
+  }
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -46,6 +70,15 @@ interface SpawnOptions {
   bypassQueue?: boolean;
   /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
   isolation?: IsolationMode;
+  /**
+   * Working directory for the agent (absolute path). Default: parent session
+   * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+   * settings, memory) still loads from the parent session's project — the
+   * target directory's `.pi` extensions never execute. With isolation:
+   * "worktree", the worktree is created FROM this directory and the result
+   * branch lands in that repo.
+   */
+  cwd?: string;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
@@ -71,6 +104,9 @@ export class AgentManager {
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
   private maxConcurrent: number;
+  /** Base repos worktrees were created from — so dispose() can prune them all,
+   *  not just the parent repo (caller-supplied cwd can target other repos). */
+  private worktreeRepos = new Set<string>();
 
   /** Queue of background agents waiting to start. */
   private queue: { id: string; args: SpawnArgs }[] = [];
@@ -114,6 +150,11 @@ export class AgentManager {
     prompt: string,
     options: SpawnOptions,
   ): string {
+    // Validate before the queue branch — a queued spawn should fail at the
+    // call, not minutes later at drain. Throw (not warn): programmatic callers
+    // can fix and retry; the RPC layer converts throws into error envelopes.
+    assertValidSpawnCwd(options.cwd);
+
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
     const record: AgentRecord = {
@@ -151,12 +192,21 @@ export class AgentManager {
 
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+    // Re-validate a caller-supplied cwd: queued spawns can start minutes after
+    // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
+    // curated errors; drainQueue parks a throw on the record as an error.
+    assertValidSpawnCwd(options.cwd);
+    // Single resolution point for the caller-supplied cwd — the worktree base
+    // repo and both cleanup calls below MUST agree on this value forever.
+    const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
+    const baseCwd = customCwd ?? ctx.cwd;
+
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined;
     if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
+      const wt = createWorktree(baseCwd, id);
       if (!wt) {
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -164,7 +214,14 @@ export class AgentManager {
         );
       }
       record.worktree = wt;
-      worktreeCwd = wt.path;
+      // workPath preserves subdirectory scoping for caller-supplied cwds: a
+      // cwd deep in a monorepo maps to the same subdir inside the copy, not
+      // the copied repo's root. Plain worktree spawns keep the historical
+      // behavior (agent at the copy's root) — moving them to workPath would
+      // also move .pi config discovery when the parent session sits in a repo
+      // subdirectory, silently dropping extensions/skills.
+      worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
+      this.worktreeRepos.add(baseCwd);
     }
 
     record.status = "running";
@@ -189,7 +246,13 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
-      cwd: worktreeCwd,
+      // Worktree wins for the working dir (the agent must run in the copy —
+      // which, with a custom cwd, was created from that target). Config stays
+      // with the parent project when a caller-supplied cwd is in play; it must
+      // stay undefined otherwise so plain worktree runs keep resolving config
+      // (incl. relative extension paths and memory) inside the worktree copy.
+      cwd: worktreeCwd ?? customCwd,
+      configCwd: customCwd !== undefined ? ctx.cwd : undefined,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -237,11 +300,14 @@ export class AgentManager {
 
         // Clean up worktree if used
         if (record.worktree) {
-          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
+            // With a caller-supplied cwd the branch lives in THAT repo, not the
+            // parent session's — say so, or the orchestrator merges in the wrong repo.
+            const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
             record.result = (record.result ?? "") +
-              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
           }
         }
 
@@ -271,7 +337,7 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch { /* ignore cleanup errors */ }
         }
@@ -479,5 +545,10 @@ export class AgentManager {
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
     try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+    // Also prune repos that caller-supplied cwds created worktrees in — a clean
+    // exit with in-flight agents would otherwise leave stale registrations there.
+    for (const repo of this.worktreeRepos) {
+      try { pruneWorktrees(repo); } catch { /* ignore */ }
+    }
   }
 }

package/src/agent-runner.ts

@@ -206,6 +206,20 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
+  /**
+   * Where .pi config is discovered (project extensions, skills, pi settings,
+   * agent memory). Default: same as the working directory. The manager sets
+   * this to the parent session's cwd when `SpawnOptions.cwd` points the
+   * working directory elsewhere — the agent works *there* but carries the
+   * parent project's config (the target's `.pi` extensions never execute).
+   *
+   * WARNING for future callers: if you pass `cwd` pointing at a directory the
+   * user didn't open, you almost certainly must pass `configCwd` too —
+   * omitting it makes the target's `.pi` extensions execute in this process.
+   * (Worktree isolation is the one intentional exception: its copy IS the
+   * parent's repo, so config resolving inside it is correct.)
+   */
+  configCwd?: string;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -285,6 +299,9 @@ export async function runAgent(
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
+  // Filesystem work happens in effectiveCwd; config discovery in configCwd.
+  // They differ only for SpawnOptions.cwd spawns (config stays with the parent).
+  const configCwd = options.configCwd ?? effectiveCwd;
 
   const env = await detectEnv(options.pi, effectiveCwd);
 
@@ -296,11 +313,14 @@ 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
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, effectiveCwd);
+    const loaded = preloadSkills(skills, configCwd);
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -320,12 +340,12 @@ export async function runAgent(
       // Read-write memory: add any missing memory tool names (read/write/edit)
       const extraNames = getMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
     } else {
       // Read-only memory: only add read tool name, use read-only prompt
       const extraNames = getReadOnlyMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
     }
   }
 
@@ -370,24 +390,41 @@ export async function runAgent(
   const noExtensions = extensions === false;
 
   const extensionsSpec = Array.isArray(extensions)
-    ? parseExtensionsSpec(extensions, effectiveCwd)
+    ? parseExtensionsSpec(extensions, configCwd)
     : 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,
+    cwd: configCwd,
     agentDir,
     noExtensions,
     additionalExtensionPaths,
@@ -425,6 +462,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 +491,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 +501,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:)`,
         });
       }
     }
@@ -499,7 +559,7 @@ export async function runAgent(
     cwd: effectiveCwd,
     agentDir,
     sessionManager: SessionManager.inMemory(effectiveCwd),
-    settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+    settingsManager: SettingsManager.create(configCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model,
     tools: allowedTools,

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