@tintinweb/pi-subagents 0.9.1 → 0.10.0

package/src/agent-runner.ts

@@ -2,8 +2,10 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
 import {
   type AgentSession,
   type AgentSessionEvent,
@@ -14,7 +16,7 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
@@ -23,8 +25,114 @@ import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
+/**
+ * Tool names registered by THIS extension. Single source of truth so the
+ * registration sites (index.ts) and the subagent exclusion list below can't
+ * drift apart. These are our own tools, not pi built-ins, so they can't be
+ * derived from pi — but they only need defining once.
+ */
+export const SUBAGENT_TOOL_NAMES = {
+  AGENT: "Agent",
+  GET_RESULT: "get_subagent_result",
+  STEER: "steer_subagent",
+} as const;
+
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+const EXCLUDED_TOOL_NAMES: string[] = Object.values(SUBAGENT_TOOL_NAMES);
+
+/**
+ * Canonical name of an extension for `extensions: [...]` allowlist matching.
+ * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
+ * resolves the same as `[mcp]`. Tool names within `ext:foo/bar` are not affected.
+ * Directory extensions (`foo/index.ts`) resolve to the parent directory name;
+ * single-file extensions to the basename minus `.ts`/`.js`.
+ */
+export function extensionCanonicalName(extPath: string): string {
+  const base = basename(extPath);
+  const name = base === "index.ts" || base === "index.js"
+    ? basename(dirname(extPath))
+    : base.replace(/\.(ts|js)$/, "");
+  return name.toLowerCase();
+}
+
+/**
+ * Classify `extensions: string[]` frontmatter entries for the loader-level filter.
+ *
+ * An entry is a PATH iff it contains a path separator or starts with `~`; otherwise
+ * it is a NAME. `"*"` sets the wildcard flag (keep all default-discovered extensions).
+ *
+ * Path entries are resolved (`~` expanded, made absolute against `cwd`) into `paths`
+ * — and their canonical name is also added to `names`. The loader override matches
+ * everything by canonical name, so path-loaded extensions are matched via their name
+ * rather than their post-staging `Extension.path`.
+ */
+export function parseExtensionsSpec(
+  entries: string[],
+  cwd: string,
+): { names: Set<string>; paths: string[]; wildcard: boolean } {
+  const names = new Set<string>();
+  const paths: string[] = [];
+  let wildcard = false;
+  for (const entry of entries) {
+    if (!entry) continue;
+    if (entry === "*") {
+      wildcard = true;
+      continue;
+    }
+    const isPathEntry = entry.includes("/") || entry.includes("\\") || entry.startsWith("~");
+    if (!isPathEntry) {
+      names.add(entry.toLowerCase());
+      continue;
+    }
+    let p = entry;
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
+      p = homedir() + p.slice(1);
+    }
+    const abs = isAbsolute(p) ? p : resolve(cwd, p);
+    paths.push(abs);
+    names.add(extensionCanonicalName(abs));
+  }
+  return { names, paths, wildcard };
+}
+
+/**
+ * Parse raw `ext:` selector strings (from the `tools:` CSV) into the set of
+ * extension names to keep loaded and a per-extension tool-narrowing map.
+ *
+ * `ext:foo` → `extNames` has `foo`, no narrowing entry (all of foo's tools).
+ * `ext:foo/bar` → `extNames` has `foo`, `narrowing.foo` has `bar` (only `bar`).
+ * A name lands in `narrowing` only when a `/tool` form is seen, so a bare
+ * `ext:foo` alongside `ext:foo/bar` leaves narrowing in effect (narrowing wins).
+ * The split is on the first `/`; extension canonical names never contain `/`.
+ */
+export function parseExtSelectors(entries: string[]): {
+  extNames: Set<string>;
+  narrowing: Map<string, Set<string>>;
+} {
+  const extNames = new Set<string>();
+  const narrowing = new Map<string, Set<string>>();
+  for (const raw of entries) {
+    if (!raw) continue;
+    const body = raw.slice("ext:".length);
+    const slash = body.indexOf("/");
+    // Extension name matches case-insensitively (matches the loader-side canonical
+    // name). Tool names are case-preserved — they're matched against pi-mono's
+    // registered identifiers, which are case-sensitive.
+    const name = (slash === -1 ? body : body.slice(0, slash)).trim().toLowerCase();
+    if (!name) continue;
+    extNames.add(name);
+    if (slash === -1) continue;
+    const tool = body.slice(slash + 1).trim();
+    if (!tool) continue;
+    let set = narrowing.get(name);
+    if (!set) {
+      set = new Set();
+      narrowing.set(name, set);
+    }
+    set.add(tool);
+  }
+  return { extNames, narrowing };
+}
 
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
@@ -239,16 +347,51 @@ export async function runAgent(
 
   const agentDir = getAgentDir();
 
-  // Load extensions/skills: true or string[] → load; false → don't.
+  // Extension loading:
+  // - true  → all default-discovered extensions
+  // - false → none (noExtensions)
+  // - string[] → loader-level allowlist. Bare names keep the matching
+  //   default-discovered extension; path entries load that extension fresh;
+  //   "*" keeps all default-discovered extensions. Excluded extensions never
+  //   bind handlers or register tools (their factory still runs once).
+  //
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
   // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
+  // `ext:` selectors from the `tools:` CSV narrow which extension tools surface to
+  // the LLM. They do NOT control loading — `extensions:` is the sole authority for
+  // which extensions load. `ext:foo` against an extension that `extensions:` excluded
+  // is an orphan and warns after reload. `isolated` means no extension tools at all.
+  const { extNames, narrowing } = parseExtSelectors(
+    options.isolated ? [] : (agentConfig?.extSelectors ?? []),
+  );
+  const noExtensions = extensions === false;
+
+  const extensionsSpec = Array.isArray(extensions)
+    ? 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`).
+  const loadAll = extensions === true || extensionsSpec?.wildcard === true;
+  const additionalExtensionPaths = extensionsSpec?.paths.length ? extensionsSpec.paths : undefined;
+  const extensionsOverride: ((base: LoadExtensionsResult) => LoadExtensionsResult) | undefined =
+    loadAll || noExtensions
+      ? undefined
+      : (base) => ({
+          ...base,
+          extensions: base.extensions.filter((e) => keepNames.has(extensionCanonicalName(e.path))),
+        });
+
   const loader = new DefaultResourceLoader({
     cwd: effectiveCwd,
     agentDir,
-    noExtensions: extensions === false,
+    noExtensions,
+    additionalExtensionPaths,
+    extensionsOverride,
     noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -258,6 +401,52 @@ export async function runAgent(
   });
   await loader.reload();
 
+  // Plain entries in `tools:` are expected to be built-in names (extension tools
+  // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
+  // this produced a silently broken agent (#75) — pi-mono accepted the bogus name
+  // into the allowlist, then dropped it at registration with no signal back.
+  if (agentConfig?.builtinToolNames?.length) {
+    const knownBuiltins = new Set(BUILTIN_TOOL_NAMES);
+    for (const name of agentConfig.builtinToolNames) {
+      if (!knownBuiltins.has(name)) {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `tools-error:tool "${name}" requested by agent "${type}" is not a known built-in`,
+        });
+      }
+    }
+  }
+
+  // A subagent spawns mid-task, so a bad `extensions:`/`ext:` entry warns rather
+  // than aborts. Two distinct misconfigurations to catch:
+  //   - `extensions: [foo]` but no extension named foo was discovered (typo or
+  //     path that failed to load — path entries fold their canonical name into
+  //     `keepNames`, so this covers them too).
+  //   - `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.
+  if (keepNames.size > 0 || extNames.size > 0) {
+    const survivingNames = new Set(
+      loader.getExtensions().extensions.map((e) => extensionCanonicalName(e.path)),
+    );
+    for (const name of keepNames) {
+      if (!survivingNames.has(name)) {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `extension-error:extension "${name}" requested by agent "${type}" was not loaded`,
+        });
+      }
+    }
+    for (const name of extNames) {
+      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:)`,
+        });
+      }
+    }
+  }
+
   // Resolve model: explicit option > config.model > parent model
   const model = options.model ?? resolveDefaultModel(
     ctx.model, ctx.modelRegistry, agentConfig?.model,
@@ -266,6 +455,46 @@ export async function runAgent(
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
+  const disallowedSet = agentConfig?.disallowedTools
+    ? new Set(agentConfig.disallowedTools)
+    : undefined;
+
+  // Enumerate extension-registered tool names from the loaded resource loader.
+  // Extensions populate `extension.tools` during `loader.reload()` and the set
+  // is stable afterwards — `bindExtensions` does not register new tools.
+  //
+  // Opt-in flip: when any `ext:` selector is present, extension tools become an
+  // explicit allowlist — a loaded extension not named by a selector contributes
+  // no tools (its handlers still ran), and `ext:foo/bar` narrows `foo` to `bar`.
+  const extensionToolNames: string[] = [];
+  if (!noExtensions) {
+    const optInActive = extNames.size > 0;
+    for (const extension of loader.getExtensions().extensions) {
+      const canon = extensionCanonicalName(extension.path);
+      if (optInActive && !extNames.has(canon)) continue;
+      const narrowed = narrowing.get(canon);
+      for (const toolName of extension.tools.keys()) {
+        if (narrowed && !narrowed.has(toolName)) continue;
+        extensionToolNames.push(toolName);
+      }
+    }
+  }
+
+  // Build the master tool allowlist applied at session construction.
+  // pi-mono's `allowedToolNames` gates BOTH registration and the initial active
+  // set, so listing the exact final set here means the session is correctly
+  // scoped from the first instant — no post-construction narrowing required.
+  const builtinToolNameSet = new Set(toolNames);
+  const allowedTools = [...toolNames, ...extensionToolNames].filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    if (disallowedSet?.has(t)) return false;
+    if (builtinToolNameSet.has(t)) return true;
+    // Reached only for extension tools. The extension set was already filtered
+    // at the loader (extensionsOverride / noExtensions) and at enumeration
+    // (`ext:` opt-in flip), so any extension tool in `extensionToolNames` is allowed.
+    return !noExtensions;
+  });
+
   const sessionOpts: Parameters<typeof createAgentSession>[0] = {
     cwd: effectiveCwd,
     agentDir,
@@ -273,7 +502,7 @@ export async function runAgent(
     settingsManager: SettingsManager.create(effectiveCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model,
-    tools: toolNames,
+    tools: allowedTools,
     resourceLoader: loader,
   };
   if (thinkingLevel) {
@@ -287,35 +516,10 @@ export async function runAgent(
     options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
   );
 
-  // Build disallowed tools set from agent config
-  const disallowedSet = agentConfig?.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
-
-  // Filter active tools: remove our own tools to prevent nesting,
-  // apply extension allowlist if specified, and apply disallowedTools denylist
-  if (extensions !== false) {
-    const builtinToolNameSet = new Set(toolNames);
-    const activeTools = session.getActiveToolNames().filter((t) => {
-      if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-      if (disallowedSet?.has(t)) return false;
-      if (builtinToolNameSet.has(t)) return true;
-      if (Array.isArray(extensions)) {
-        return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
-      }
-      return true;
-    });
-    session.setActiveToolsByName(activeTools);
-  } else if (disallowedSet) {
-    // Even with extensions disabled, apply denylist to built-in tools
-    const activeTools = session.getActiveToolNames().filter(t => !disallowedSet.has(t));
-    session.setActiveToolsByName(activeTools);
-  }
-
   // Bind extensions so that session_start fires and extensions can initialize
-  // (e.g. loading credentials, setting up state). Placed after tool filtering
-  // so extension-provided skills/prompts from extendResourcesFromExtensions()
-  // respect the active tool set. All ExtensionBindings fields are optional.
+  // (e.g. loading credentials, setting up state). Tool gating already happened
+  // at session construction via the `tools:` allowlist above — no separate
+  // post-bind filter is needed. All ExtensionBindings fields are optional.
   await session.bindExtensions({
     onError: (err) => {
       options.onToolActivity?.({

package/src/agent-types.ts

@@ -5,11 +5,21 @@
  * 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";
 import type { AgentConfig } from "./types.js";
 
-/** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES: string[] = ["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: string[] = [
+  ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
+];
 
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
@@ -112,8 +122,9 @@ export function getToolNamesForType(type: string): string[] {
   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. */

package/src/custom-agents.ts

@@ -50,11 +50,14 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
 
     const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(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),
@@ -107,6 +110,25 @@ function csvList(val: unknown, defaults: string[]): string[] {
   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: unknown): { builtinToolNames: string[]; extSelectors: string[] | undefined } {
+  const entries = csvList(val, BUILTIN_TOOL_NAMES);
+  const isWildcard = (e: string) => 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/src/index.ts

@@ -16,7 +16,7 @@ import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type Exten
 import { Container, Key, matchesKey, type SettingItem, 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 { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -28,6 +28,7 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } 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 {
   type AgentActivity,
@@ -118,16 +119,6 @@ function getStatusLabel(status: string, error?: string): string {
   }
 }
 
-/** Parenthetical status note for completed agent result text. */
-function getStatusNote(status: string): string {
-  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: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -154,7 +145,7 @@ function formatTaskNotification(record: AgentRecord, resultMaxLen: number): stri
     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>`,
@@ -651,7 +642,7 @@ export default function (pi: ExtensionAPI) {
     : "";
 
   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.
 
@@ -772,7 +763,7 @@ Terse command-style prompts produce shallow, generic work.
         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: AgentDetails) => {
         const parts: string[] = [];
         if (d.modelName) parts.push(d.modelName);
@@ -1188,7 +1179,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.",
@@ -1236,7 +1227,7 @@ Terse command-style prompts produce shallow, generic work.
 
       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") {
@@ -1268,7 +1259,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 " +
@@ -1491,7 +1482,11 @@ Terse command-style prompts produce shallow, generic work.
 
     await ctx.ui.custom<undefined>(
       (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,

package/src/prompts.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).
@@ -72,7 +75,12 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\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

package/src/status-note.ts

@@ -0,0 +1,25 @@
+/**
+ * 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: string): string {
+  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/src/types.ts

@@ -26,6 +26,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 */

package/src/ui/agent-widget.ts

@@ -100,12 +100,12 @@ export 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 function formatSessionTokens(
   tokens: number,
@@ -120,15 +120,15 @@ export function formatSessionTokens(
     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: number, maxTurns?: number | null): string {
-  return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+  return maxTurns != null ? `↻${turnCount}≤${maxTurns}` : `↻${turnCount}`;
 }
 
 /** Format milliseconds as human-readable duration. */