@tintinweb/pi-subagents 0.10.1 → 0.10.3

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;
@@ -75,6 +78,7 @@ export interface AgentRecord {
         path: string;
         branch: string;
         baseSha: string;
+        workPath: string;
     };
     /** Worktree cleanup result after agent completion. */
     worktreeResult?: {

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

@@ -6,12 +6,19 @@
  * If changes exist, a branch is created and returned in the result.
  */
 export interface WorktreeInfo {
-    /** Absolute path to the worktree directory. */
+    /** Absolute path to the worktree directory (the copied repo's root). */
     path: string;
     /** Branch name created for this worktree (if changes exist). */
     branch: string;
     /** Commit SHA that the worktree was created from. */
     baseSha: string;
+    /**
+     * Where the agent should work inside the worktree: the equivalent of the
+     * cwd the worktree was created from. Equals `path` when that cwd was the
+     * repo root; points at the copied subdirectory when it was deeper (e.g. a
+     * monorepo package), so the requested scoping survives isolation.
+     */
+    workPath: string;
 }
 export interface WorktreeCleanupResult {
     /** Whether changes were found in the worktree. */

package/dist/worktree.js

@@ -7,9 +7,9 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 /**
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
@@ -17,11 +17,20 @@ 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;
+    let subdir;
     try {
         execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
         baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 })
             .toString()
             .trim();
+        // Where cwd sits inside the repo ("" at the root): the agent must work at
+        // the same subdirectory inside the copy, or a monorepo-package cwd would
+        // silently widen to the whole repo. realpath both sides — git emits
+        // resolved paths while cwd may arrive through a symlink (macOS /tmp).
+        const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, stdio: "pipe", timeout: 5000 })
+            .toString()
+            .trim();
+        subdir = relative(realpathSync(topLevel), realpathSync(cwd));
     }
     catch {
         return undefined;
@@ -36,7 +45,7 @@ export function createWorktree(cwd, agentId) {
             stdio: "pipe",
             timeout: 30000,
         });
-        return { path: worktreePath, branch, baseSha };
+        return { path: worktreePath, branch, baseSha, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
     }
     catch {
         // If worktree creation fails, return undefined (agent runs in normal cwd)

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