@tintinweb/pi-subagents 0.10.0 → 0.10.2

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/dist/worktree.d.ts

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

package/dist/worktree.js

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

package/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.0",
+  "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

@@ -24,6 +24,15 @@ export const BUILTIN_TOOL_NAMES: string[] = [
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
 
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+
+/** Check whether default agents are disabled. */
+export function isDefaultsDisabled(): boolean { return disableDefaults; }
+
+/** Set whether default agents are disabled. */
+export function setDefaultsDisabled(b: boolean): void { disableDefaults = b; }
+
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -32,9 +41,11 @@ const agents = new Map<string, AgentConfig>();
 export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   agents.clear();
 
-  // Start with defaults
-  for (const [name, config] of DEFAULT_AGENTS) {
-    agents.set(name, config);
+  // Start with defaults (unless disabled via settings)
+  if (!disableDefaults) {
+    for (const [name, config] of DEFAULT_AGENTS) {
+      agents.set(name, config);
+    }
   }
 
   // Overlay user agents (overrides defaults with same name)
@@ -133,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";
 } {
@@ -144,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,
     };
@@ -157,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,