@tintinweb/pi-subagents 0.9.1 → 0.10.1

package/dist/agent-types.js

@@ -4,11 +4,27 @@
  * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
+import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-/** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * All known built-in tool names, derived from pi's own tool factories rather
+ * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
+ * `createCodingTools` → read/bash/edit/write; `createReadOnlyTools` →
+ * read/grep/find/ls; their de-duplicated union is the 7 built-ins
+ * (read, bash, edit, write, grep, find, ls). The `cwd` only binds tool
+ * operations we never invoke here — we read each tool's `.name` and discard it.
+ */
+export const BUILTIN_TOOL_NAMES = [
+    ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
+];
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map();
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+/** Check whether default agents are disabled. */
+export function isDefaultsDisabled() { return disableDefaults; }
+/** Set whether default agents are disabled. */
+export function setDefaultsDisabled(b) { disableDefaults = b; }
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
@@ -16,9 +32,11 @@ const agents = new Map();
  */
 export function registerAgents(userAgents) {
     agents.clear();
-    // Start with defaults
-    for (const [name, config] of DEFAULT_AGENTS) {
-        agents.set(name, config);
+    // Start with defaults (unless disabled via settings)
+    if (!disableDefaults) {
+        for (const [name, config] of DEFAULT_AGENTS) {
+            agents.set(name, config);
+        }
     }
     // Overlay user agents (overrides defaults with same name)
     for (const [name, config] of userAgents) {
@@ -95,8 +113,9 @@ export function getToolNamesForType(type) {
     const key = resolveKey(type);
     const raw = key ? agents.get(key) : undefined;
     const config = raw?.enabled !== false ? raw : undefined;
-    const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
-    return names;
+    // `undefined` (definition omitted the field) → all built-ins; an explicit `[]`
+    // (`tools: none` or a `tools:` with only `ext:` entries) → zero built-ins.
+    return config?.builtinToolNames ?? [...BUILTIN_TOOL_NAMES];
 }
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
 export function getConfig(type) {

package/dist/custom-agents.js

@@ -43,11 +43,13 @@ function loadFromDir(dir, agents, source) {
             continue;
         }
         const { frontmatter: fm, body } = parseFrontmatter(content);
+        const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
         agents.set(name, {
             name,
             displayName: str(fm.display_name),
             description: str(fm.description) ?? name,
-            builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+            builtinToolNames,
+            extSelectors,
             disallowedTools: csvListOptional(fm.disallowed_tools),
             extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
             skills: inheritField(fm.skills ?? fm.inherit_skills),
@@ -97,6 +99,24 @@ function csvList(val, defaults) {
         return defaults;
     return parseCsvField(val) ?? [];
 }
+/**
+ * Partition the `tools:` CSV into the built-in tool allowlist and raw `ext:` selectors.
+ * `*` (and the case-insensitive alias `all`, for `tools: all`) expands to all
+ * built-ins; plain entries are built-in names; `ext:` entries are extension-tool
+ * selectors parsed later by the runner. omitted → all built-ins, no selectors.
+ * `tools:` present with only `ext:` entries → zero built-ins (use `*`).
+ */
+function parseToolsField(val) {
+    const entries = csvList(val, BUILTIN_TOOL_NAMES);
+    const isWildcard = (e) => e === "*" || e.toLowerCase() === "all";
+    const hasWildcard = entries.some(isWildcard);
+    const plain = entries.filter(e => !isWildcard(e) && !e.startsWith("ext:"));
+    const extEntries = entries.filter(e => e.startsWith("ext:"));
+    return {
+        builtinToolNames: hasWildcard ? [...new Set([...BUILTIN_TOOL_NAMES, ...plain])] : plain,
+        extSelectors: extEntries.length > 0 ? extEntries : undefined,
+    };
+}
 /**
  * Parse an optional comma-separated list field.
  * omitted → undefined; "none"/empty → undefined; csv → listed items.

package/dist/index.js

@@ -15,8 +15,8 @@ import { defineTool, getAgentDir, getSettingsListTheme } from "@earendil-works/p
 import { Container, Key, matchesKey, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
-import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
@@ -27,6 +27,7 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
+import { getStatusNote } from "./status-note.js";
 import { AgentWidget, buildInvocationTags, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
@@ -98,15 +99,6 @@ function getStatusLabel(status, error) {
         default: return "Done";
     }
 }
-/** Parenthetical status note for completed agent result text. */
-function getStatusNote(status) {
-    switch (status) {
-        case "aborted": return " (aborted — max turns exceeded, output may be incomplete)";
-        case "steered": return " (wrapped up — reached turn limit)";
-        case "stopped": return " (stopped by user)";
-        default: return "";
-    }
-}
 /** Escape XML special characters to prevent injection in structured notifications. */
 function escapeXml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -130,7 +122,7 @@ function formatTaskNotification(record, resultMaxLen) {
         record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
         record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
         `<status>${escapeXml(status)}</status>`,
-        `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+        `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status)}</summary>`,
         `<result>${escapeXml(resultPreview)}</result>`,
         `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
         `</task-notification>`,
@@ -470,6 +462,17 @@ export default function (pi) {
     let scopeModelsEnabled = false;
     function isScopeModelsEnabled() { return scopeModelsEnabled; }
     function setScopeModelsEnabled(enabled) { scopeModelsEnabled = enabled; }
+    // ---- Disable default agents configuration ----
+    // When enabled, the three hardcoded default agents (general-purpose, Explore,
+    // Plan) are not registered. User-defined agents from .pi/agents/*.md are
+    // completely unaffected — only DEFAULT_AGENTS are suppressed.
+    // Defaults to false; opt-in via `/agents → Settings` or subagents.json.
+    // State lives in agent-types.ts (isDefaultsDisabled) because registerAgents
+    // needs it; this wrapper just re-registers after flipping it.
+    function setDisableDefaultAgents(b) {
+        setDefaultsDisabled(b);
+        reloadCustomAgents(); // re-register with new setting
+    }
     // ---- 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
@@ -526,10 +529,10 @@ export default function (pi) {
             && BUILTIN_TOOL_NAMES.every((t) => tools.includes(t));
         return isFullSet ? "*" : tools.join(", ");
     };
-    /** Build the full type list text dynamically from the unified registry. */
+    /** Build the full type list text dynamically from available agents only. */
     const buildTypeListText = () => {
-        const allNames = [...getDefaultAgentNames(), ...getUserAgentNames()];
-        return allNames.map((name) => {
+        const available = getAvailableTypes();
+        return available.map((name) => {
             const cfg = getAgentConfig(name);
             const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
             const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
@@ -543,7 +546,6 @@ export default function (pi) {
         // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
         return name.replace(/-\d{8}$/, "");
     }
-    const typeListText = buildTypeListText();
     // Apply persisted settings on startup and emit `subagents:settings_loaded`.
     // Global + project merged; missing → defaults; corrupt file emits a warning
     // to stderr and falls back to defaults.
@@ -554,6 +556,7 @@ export default function (pi) {
         setDefaultJoinMode,
         setSchedulingEnabled,
         setScopeModels: setScopeModelsEnabled,
+        setDisableDefaultAgents: setDisableDefaultAgents,
     }, (event, payload) => pi.events.emit(event, payload));
     // ---- Agent tool ----
     // Schedule param + its guideline are gated on `schedulingEnabled` (read once
@@ -573,12 +576,12 @@ export default function (pi) {
         ? `\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: "Agent",
+        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.
 
 Available agent types and the tools they have access to:
-${typeListText}
+${buildTypeListText()}
 
 Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
 
@@ -673,7 +676,7 @@ Terse command-style prompts produce shallow, generic work.
                 const text = result.content[0]?.type === "text" ? result.content[0].text : "";
                 return new Text(text, 0, 0);
             }
-            // Helper: build "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens" stats string
+            // Helper: build "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k tokens" stats string
             const stats = (d) => {
                 const parts = [];
                 if (d.modelName)
@@ -1026,8 +1029,10 @@ Terse command-style prompts produce shallow, generic work.
             // Get final token count
             const tokenText = formatLifetimeTokens(fgState);
             const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
+            // "general-purpose" may itself be unregistered (defaults disabled, no
+            // user override) — getConfig then uses the hardcoded fallback config.
             const fallbackNote = fellBack
-                ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
+                ? `Note: Unknown agent type "${rawType}" — using ${resolveType("general-purpose") ? "general-purpose" : "the fallback agent config"}.\n\n`
                 : "";
             if (record.status === "error") {
                 return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
@@ -1042,7 +1047,7 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- get_subagent_result tool ----
     pi.registerTool(defineTool({
-        name: "get_subagent_result",
+        name: SUBAGENT_TOOL_NAMES.GET_RESULT,
         label: "Get Agent Result",
         description: "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
         promptSnippet: "Check status and retrieve results from a background agent",
@@ -1084,7 +1089,7 @@ Terse command-style prompts produce shallow, generic work.
                 statsParts.push(`Compactions: ${record.compactionCount}`);
             statsParts.push(`Duration: ${duration}`);
             let output = `Agent: ${record.id}\n` +
-                `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
+                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
                 `Description: ${record.description}\n\n`;
             if (record.status === "running") {
                 output += "Agent is still running. Use wait: true or check back later.";
@@ -1112,7 +1117,7 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- steer_subagent tool ----
     pi.registerTool(defineTool({
-        name: "steer_subagent",
+        name: SUBAGENT_TOOL_NAMES.STEER,
         label: "Steer Agent",
         description: "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
             "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
@@ -1322,7 +1327,11 @@ Terse command-style prompts produce shallow, generic work.
         const session = record.session;
         const activity = agentActivity.get(record.id);
         await ctx.ui.custom((tui, theme, _keybindings, done) => {
-            return new ConversationViewer(tui, session, record, activity, theme, done);
+            return new ConversationViewer(tui, session, record, activity, theme, done, () => {
+                if (manager.abort(record.id)) {
+                    ctx.ui.notify(`Stopped "${record.description}".`, "info");
+                }
+            });
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
@@ -1694,6 +1703,7 @@ ${systemPrompt}
             defaultJoinMode: getDefaultJoinMode(),
             schedulingEnabled: isSchedulingEnabled(),
             scopeModels: isScopeModelsEnabled(),
+            disableDefaultAgents: isDefaultsDisabled(),
         };
     }
     const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
@@ -1745,6 +1755,13 @@ ${systemPrompt}
                     currentValue: isScopeModelsEnabled() ? "on" : "off",
                     values: ["on", "off"],
                 },
+                {
+                    id: "disableDefaultAgents",
+                    label: "Disable defaults",
+                    description: "Hide built-in agents (general-purpose, Explore, Plan) — custom agents are unaffected",
+                    currentValue: isDefaultsDisabled() ? "on" : "off",
+                    values: ["on", "off"],
+                },
             ];
         }
         function applyValue(id, value) {
@@ -1794,6 +1811,11 @@ ${systemPrompt}
                 setScopeModelsEnabled(enabled);
                 notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`);
             }
+            else if (id === "disableDefaultAgents") {
+                const enabled = value === "on";
+                setDisableDefaultAgents(enabled);
+                notifyApplied(ctx, `Default agents ${enabled ? "disabled" : "enabled"}. Tool spec change takes effect on next pi session.`);
+            }
         }
         let list;
         // Track current selection index directly (SettingsList doesn't expose it).

package/dist/prompts.d.ts

@@ -16,12 +16,15 @@ export interface PromptExtras {
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).

package/dist/prompts.js

@@ -5,12 +5,15 @@
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
@@ -49,7 +52,12 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+        // Place shared/stable content first so the LLM's KV cache can reuse the
+        // inherited prefix across all subagent invocations. The parent prompt is
+        // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+        // with the parent session, maximising KV cache hits. The <active_agent>
+        // tag and env block vary per call and are placed after the cached prefix.
+        return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + customSection + extrasSuffix;
     }
     // "replace" mode — env header + the config's full system prompt
     const replaceHeader = `You are a pi coding agent sub-agent.

package/dist/settings.d.ts

@@ -40,6 +40,13 @@ export interface SubagentsSettings {
      * against. Defaults to false: subagents may use any model.
      */
     scopeModels?: boolean;
+    /**
+     * When true, the three built-in default agents (general-purpose, Explore, Plan)
+     * are not registered at startup. User-defined agents from .pi/agents/*.md are
+     * completely unaffected — only the hardcoded DEFAULT_AGENTS are suppressed.
+     * Defaults to false.
+     */
+    disableDefaultAgents?: boolean;
 }
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
 export interface SettingsAppliers {
@@ -49,6 +56,7 @@ export interface SettingsAppliers {
     setDefaultJoinMode: (mode: JoinMode) => void;
     setSchedulingEnabled: (b: boolean) => void;
     setScopeModels: (enabled: boolean) => void;
+    setDisableDefaultAgents: (b: boolean) => 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

@@ -41,6 +41,9 @@ function sanitize(raw) {
     if (typeof r.scopeModels === "boolean") {
         out.scopeModels = r.scopeModels;
     }
+    if (typeof r.disableDefaultAgents === "boolean") {
+        out.disableDefaultAgents = r.disableDefaultAgents;
+    }
     return out;
 }
 function globalPath() {
@@ -100,6 +103,8 @@ export function applySettings(s, appliers) {
         appliers.setSchedulingEnabled(s.schedulingEnabled);
     if (typeof s.scopeModels === "boolean")
         appliers.setScopeModels(s.scopeModels);
+    if (typeof s.disableDefaultAgents === "boolean")
+        appliers.setDisableDefaultAgents(s.disableDefaultAgents);
 }
 /**
  * Format the user-facing toast for a settings mutation. Pure function —

package/dist/status-note.d.ts

@@ -0,0 +1,13 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export declare function getStatusNote(status: string): string;

package/dist/status-note.js

@@ -0,0 +1,24 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status) {
+    switch (status) {
+        case "stopped":
+            return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+        case "aborted":
+            return " (aborted — hit the turn limit before completion; output may be incomplete)";
+        case "steered":
+            return " (wrapped up at the turn limit — output may be partial)";
+        default:
+            return "";
+    }
+}

package/dist/types.d.ts

@@ -19,6 +19,9 @@ export interface AgentConfig {
     displayName?: string;
     description: string;
     builtinToolNames?: string[];
+    /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
+     * Presence of any entry flips extension tools to an explicit allowlist. */
+    extSelectors?: string[];
     /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
     disallowedTools?: string[];
     /** true = inherit all, string[] = only listed, false = none */
@@ -71,6 +74,7 @@ export interface AgentRecord {
     worktree?: {
         path: string;
         branch: string;
+        baseSha: string;
     };
     /** Worktree cleanup result after agent completion. */
     worktreeResult?: {

package/dist/ui/agent-widget.d.ts

@@ -66,15 +66,15 @@ export declare function formatTokens(count: number): string;
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export declare function formatSessionTokens(tokens: number, percent: number | null, theme: Theme, compactions?: number): string;
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export declare function formatTurns(turnCount: number, maxTurns?: number | null): string;
 /** Format milliseconds as human-readable duration. */
 export declare function formatMs(ms: number): string;

package/dist/ui/agent-widget.js

@@ -36,12 +36,12 @@ export function formatTokens(count) {
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
     const tokenStr = formatTokens(tokens);
@@ -51,15 +51,15 @@ export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
         annot.push(theme.fg(color, `${Math.round(percent)}%`));
     }
     if (compactions > 0) {
-        annot.push(theme.fg("dim", `↻${compactions}`));
+        annot.push(theme.fg("dim", `⇊${compactions}`));
     }
     if (annot.length === 0)
         return tokenStr;
     return `${tokenStr} (${annot.join(" · ")})`;
 }
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export function formatTurns(turnCount, maxTurns) {
-    return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+    return maxTurns != null ? `↻${turnCount}≤${maxTurns}` : `↻${turnCount}`;
 }
 /** Format milliseconds as human-readable duration. */
 export function formatMs(ms) {

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

@@ -18,14 +18,22 @@ export declare class ConversationViewer implements Component {
     private activity;
     private theme;
     private done;
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    private onStop?;
     private scrollOffset;
     private autoScroll;
     private unsubscribe;
     private lastInnerW;
     private closed;
-    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void);
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    private stopArmed;
+    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);
     handleInput(data: string): void;
     render(width: number): string[];
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    private isStoppable;
     invalidate(): void;
     dispose(): void;
     private viewportHeight;

package/dist/ui/conversation-viewer.js

@@ -20,18 +20,24 @@ export class ConversationViewer {
     activity;
     theme;
     done;
+    onStop;
     scrollOffset = 0;
     autoScroll = true;
     unsubscribe;
     lastInnerW = 0;
     closed = false;
-    constructor(tui, session, record, activity, theme, done) {
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    stopArmed = false;
+    constructor(tui, session, record, activity, theme, done, 
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    onStop) {
         this.tui = tui;
         this.session = session;
         this.record = record;
         this.activity = activity;
         this.theme = theme;
         this.done = done;
+        this.onStop = onStop;
         this.unsubscribe = session.subscribe(() => {
             if (this.closed)
                 return;
@@ -44,6 +50,23 @@ export class ConversationViewer {
             this.done(undefined);
             return;
         }
+        // Stop/abort the agent (only while it can still be stopped). Two-press:
+        // first "x" arms, second confirms — any other key disarms.
+        if (matchesKey(data, "x")) {
+            if (this.isStoppable()) {
+                if (this.stopArmed) {
+                    this.stopArmed = false;
+                    this.onStop?.();
+                }
+                else {
+                    this.stopArmed = true;
+                }
+                this.tui.requestRender();
+            }
+            return;
+        }
+        if (this.stopArmed)
+            this.stopArmed = false;
         const totalLines = this.buildContentLines(this.lastInnerW).length;
         const viewportHeight = this.viewportHeight();
         const maxScroll = Math.max(0, totalLines - viewportHeight);
@@ -132,12 +155,22 @@ export class ConversationViewer {
             ? "100%"
             : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
         const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
-        const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        const scrollHint = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        // Stop hint goes first in the right group so it survives right-edge
+        // truncation on narrow terminals (the scroll hint is the expendable part).
+        const footerRight = this.isStoppable()
+            ? (this.stopArmed ? th.fg("error", "x again to STOP") : th.fg("dim", "x stop")) +
+                th.fg("dim", " · ") + scrollHint
+            : scrollHint;
         const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
         lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
         lines.push(hrBot);
         return lines;
     }
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    isStoppable() {
+        return !!this.onStop && (this.record.status === "running" || this.record.status === "queued");
+    }
     invalidate() { }
     dispose() {
         this.closed = true;

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. */