pi-subagents-lite 0.3.1 → 0.4.1

package/README.md

@@ -13,14 +13,14 @@ Every tool the LLM sees costs tokens — in the system prompt, and in every turn
 
 | Standard | Schema-first |
 |---|---|
-| `description: "Spawn a sub-agent"` | `description: "."` |
+| `description: "Spawn a sub-agent"` | _(removed)_ |
 | `promptSnippet` with usage examples | _(none)_ |
 | `promptGuidelines` with rules | _(none)_ |
 | Parameters with `.description()` | Bare `Type.String()` |
 
 Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
 
-**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, resume, model overrides — all with minimal token overhead.
+**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides — all with minimal token overhead.
 
 ## Features
 
@@ -32,7 +32,7 @@ Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `des
 - **Cost tracking** — input/output/cache tokens and dollar cost per agent
 - **Live widget** — persistent status bar above the editor showing running/completed agents
 - **Result viewer** — fullscreen markdown viewer with stats
-- **Steer & resume** — inject mid-execution guidance or continue a previous conversation
+- **Steer** — inject mid-execution guidance into running agents
 - **Output logs** — human-readable, `tail -f` friendly
 
 ## Install
@@ -95,7 +95,6 @@ Stop a running agent at any time via /agents command
 | `description` | ✅ | Brief description for the LLM caller |
 | `agent` | | Type name — `general-purpose`, `Explore`, or any custom type you define (see [Custom Agent Types](#custom-agent-types)). The available values are **auto-populated** from `.md` files in your agent directories — drop a file, it appears in the enum. Set `enabled: false` in frontmatter to remove a type from this list. |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
-| `resume` | | Agent ID to continue a previous conversation |
 
 > `model`, `max_turns`, `isolated`, and `thinking` are **not visible to the LLM** through tool introspection — the extension injects them at call time from agent config and frontmatter. `model` is resolved via the [Model Resolution](#model-resolution) chain; `max_turns`/`isolated`/`thinking` come from the agent's config. See [Custom Agent Types](#custom-agent-types) to set them.
 
@@ -134,7 +133,8 @@ focusing on injection flaws, auth bypasses, and insecure defaults.
 | `tools` | string[] | Built-in tool allowlist: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. If omitted, inherits all. |
 | `disallowed_tools` | string[] | Tool denylist — removes these from the agent's toolset even if allowlisted by `tools` or extensions. |
 | `extensions` | bool \| string[] | `false` = no extension tools; `true` = inherit all; `["ext-a"]` = allowlist. |
-| `skills` | bool \| string[] | `false` = no skill prompts; `true` = inherit all; `["skill-a"]` = only these. |
+| `skills` | bool \| string[] | `false` = no skills; `true` = inherit all; `["skill-a"]` = metadata-only injection (agent reads full content on-demand). |
+| `preload_skills` | string[] \| false | `["skill-a"]` = dump full SKILL.md content into system prompt (old `skills` behavior). `false`/omitted = none. |
 | `model` | string | Default model as `"provider/model-id"`. Override via `/agents` or `subagents-lite.json`. |
 | `thinking` | string | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
 | `max_turns` | number | Turn limit (soft stop with steer). |
@@ -150,8 +150,9 @@ Every tool schema and every skill snippet you inject costs tokens — in every t
 | `tools: [a, b, c]` | Which built-in tools the LLM sees | High — each tool has a schema (name, params, description) injected every turn. Fewer tools = fewer tokens. |
 | `extensions: false` | Disables all extension-provided tools | Medium — extensions can register many tools (linters, browsers, etc.). Each adds schema tokens. |
 | `extensions: ["my-ext"]` | Allowlist only specific extensions | Medium — pick only what the agent needs. |
-| `skills: false` | Prevents skill content from being injected into the system prompt | **Highest** — skill prompts are prose, not schemas. A verbose skill can be 10-50x the token cost of a tool schema. |
-| `skills: ["skill-a"]` | Inject only listed skills (preloaded inline) | Medium — you control exactly which skills appear. |
+| `skills: ["skill-a"]` | Whitelist skills — injects metadata only (name, description, location) | Low — agent reads full content on-demand via `read` tool. No prose in system prompt. |
+| `skills: false` | Disables all skills | Zero skill tokens. |
+| `preload_skills: ["skill-a"]` | Dump full SKILL.md content into system prompt | **Highest** — skill prompts are prose, not schemas. A verbose skill can be 10-50x the token cost of a tool schema. |
 | `isolated: true` | Shorthand for `extensions: false` + `skills: false` | High — zero extension tools, zero skill prompts. Useful for fast, focused agents. |
 
 **Practical example:** An `Explore` agent that only reads files doesn't need write tools, browser extensions, or git skills. Setting `tools: [read, bash, grep, find, ls]` + `extensions: false` + `skills: false` saves thousands of tokens per turn compared to inheriting everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",

package/src/agent-discovery.ts

@@ -28,6 +28,7 @@ export interface AgentConfigFromMd {
   tools?: string[];
   extensions?: boolean | string[];
   skills?: boolean | string[];
+  preload_skills?: string[] | false;
   model?: string;
   thinking?: ThinkingLevel;
   max_turns?: number;
@@ -163,6 +164,26 @@ export function parseExtensions(
   return undefined;
 }
 
+/**
+ * Parse the preload_skills field from frontmatter.
+ * Unlike parseExtensions, does NOT accept true/"true"/"all" —
+ * preload requires an explicit list of skill names.
+ */
+export function parsePreloadSkills(
+  raw: unknown,
+): string[] | false | undefined {
+  if (raw === false || raw === "false" || raw === "none") {
+    return false;
+  }
+  if (typeof raw === "string" && raw.length > 0) {
+    return splitCommaList(raw);
+  }
+  if (Array.isArray(raw)) {
+    return raw.map(String);
+  }
+  return undefined; // true/"true"/"all" not supported
+}
+
 /* ------------------------------------------------------------------ */
 /*  Frontmatter value helpers                                          */
 /* ------------------------------------------------------------------ */
@@ -253,6 +274,7 @@ export function parseAgentFile(
     tools: parseStringArray(frontmatter, "tools"),
     extensions: parseExtensions(frontmatter.extensions),
     skills: parseExtensions(frontmatter.skills),
+    preload_skills: parsePreloadSkills(frontmatter.preload_skills),
     model: parseString(frontmatter, "model"),
     thinking: parseThinkingLevel(parseString(frontmatter, "thinking")),
     max_turns: parseNumber(frontmatter, "max_turns"),
@@ -377,6 +399,7 @@ function fromMd(md: AgentConfigFromMd): Partial<AgentConfig> {
     builtinToolNames: md.tools,
     extensions: md.extensions,
     skills: md.skills,
+    preloadSkills: md.preload_skills,
     model: md.model,
     thinking: md.thinking,
     maxTurns: md.max_turns,

package/src/agent-manager.ts

@@ -15,14 +15,15 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { runAgent, type ToolActivity } from "./agent-runner.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
-import type {
-  AgentInvocation,
-  AgentRecord,
-  CompactionInfo,
-  SubagentType,
-  ThinkingLevel,
+import {
+  type AgentInvocation,
+  type AgentRecord,
+  type CompactionInfo,
+  SHORT_ID_LENGTH,
+  type SubagentType,
+  type ThinkingLevel,
 } from "./types.js";
 import { addUsage, getLifetimeTotal, type LifetimeUsage } from "./usage.js";
 import { errorMessage } from "./utils.js";
@@ -33,8 +34,10 @@ const CLEANUP_INTERVAL_MS = 60_000;
 /** Age after which a completed agent record is evicted (milliseconds). */
 const CLEANUP_AGE_CUTOFF_MS = 10 * 60_000;
 
-/** Length of short agent ID (UUID prefix). */
-const AGENT_ID_LENGTH = 17;
+/** UUID prefix length for agent IDs stored in the agents map (uniqueness). */
+const AGENT_ID_PREFIX_LENGTH = 17;
+
+
 
 /** Default per-model concurrency limit when not specified in config. */
 const DEFAULT_CONCURRENCY_LIMIT = 4;
@@ -233,7 +236,7 @@ export class AgentManager {
     prompt: string,
     options: SpawnOptions,
   ): string {
-    const id = randomUUID().slice(0, AGENT_ID_LENGTH);
+    const id = randomUUID().slice(0, AGENT_ID_PREFIX_LENGTH);
     const abortController = new AbortController();
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
@@ -381,7 +384,7 @@ export class AgentManager {
   }
 
   /**
-   * Build common record-tracking callbacks shared by startAgent and resume.
+   * Build common record-tracking callbacks shared by startAgent.
    * Updates the record's toolUses, lifetimeUsage, and compactionCount.
    * When options are provided, also forwards events to the caller.
    */
@@ -434,39 +437,6 @@ export class AgentManager {
     this.queue = this.queue.filter(e => !started.has(e.id));
   }
 
-  /**
-   * Resume an existing agent session with a new prompt.
-   */
-  async resume(
-    id: string,
-    prompt: string,
-    signal?: AbortSignal,
-  ): Promise<AgentRecord | undefined> {
-    const record = this.agents.get(id);
-    if (!record?.session) return undefined;
-
-    record.status = "running";
-    record.startedAt = Date.now();
-    record.completedAt = undefined;
-    record.result = undefined;
-    record.error = undefined;
-
-    try {
-      const responseText = await resumeAgent(record.session, prompt, {
-        ...this.createRecordCallbacks(record),
-        signal,
-      });
-      record.status = "completed";
-      record.result = responseText;
-      record.completedAt = Date.now();
-    } catch (err) {
-      record.status = "error";
-      record.error = errorMessage(err);
-      record.completedAt = Date.now();
-    }
-
-    return record;
-  }
 
   /**
    * Send a steering message to a running agent.

package/src/agent-runner.ts

@@ -28,9 +28,9 @@ import { extractText } from "./context.js";
 import type { LifetimeUsage } from "./usage.js";
 import { findModelInRegistry } from "./utils.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
-import { preloadSkills } from "./skill-loader.js";
-import type { CompactionInfo, EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+import { buildAgentPrompt, type PromptExtras, type SkillMeta } from "./prompts.js";
+import { preloadSkills, loadSkillMeta } from "./skill-loader.js";
+import { type CompactionInfo, type EnvInfo, SHORT_ID_LENGTH, type SubagentType, type ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 export const EXCLUDED_TOOL_NAMES = ["Agent"];
@@ -157,7 +157,7 @@ function usageFromAssistantMessage(msg: Record<string, unknown>): LifetimeUsage
 
 /**
  * Subscribe to shared session events (tool activity, usage, compaction)
- * used by both runAgent and resumeAgent. Returns an unsubscribe function.
+ * used by runAgent. Returns an unsubscribe function.
  */
 export function subscribeToSessionEvents(
   session: AgentSession,
@@ -264,12 +264,18 @@ export async function runAgent(
   const effectiveIsolated = options.isolated ?? agentConfig?.isolated;
   const extensions = effectiveIsolated ? false : config.extensions;
   const skills = effectiveIsolated ? false : config.skills;
+  const preloadSkillsList = effectiveIsolated ? false : agentConfig?.preloadSkills;
 
   // Build prompt extras (no memoryBlock — skills only).
-  // When skills is string[], preload their content into the prompt.
-  const extras: PromptExtras = Array.isArray(skills)
-    ? { skillBlocks: preloadSkills(skills, effectiveCwd) }
-    : {};
+  // - preloadSkills: force full content into system prompt
+  // - skills: metadata only (whitelist), agent reads on-demand
+  const extras: PromptExtras = {};
+  if (Array.isArray(preloadSkillsList)) {
+    extras.skillBlocks = preloadSkills(preloadSkillsList, effectiveCwd);
+  }
+  if (Array.isArray(skills)) {
+    extras.skillMetas = loadSkillMeta(skills, effectiveCwd);
+  }
 
   const toolNames = getToolNamesForType(type);
 
@@ -284,9 +290,11 @@ export async function runAgent(
     systemPrompt = buildAgentPrompt({ ...fallback, name: type }, effectiveCwd, env, extras);
   }
 
-  // When skills is string[], they're already preloaded into the prompt.
-  // Pass noSkills: true to prevent the skill loader from loading them again.
-  const skipSkillLoader = skills === false || Array.isArray(skills);
+  // Skip the built-in skill loader when:
+  // - skills is false (no skills)
+  // - preloadSkills is string[] (we handle preloading ourselves)
+  // - skills is string[] (we handle metadata ourselves)
+  const skipSkillLoader = skills === false || Array.isArray(skills) || Array.isArray(preloadSkillsList);
 
   const agentDir = getAgentDir();
 
@@ -330,7 +338,7 @@ export async function runAgent(
 
   const baseSessionName = agentConfig?.name ?? type;
   session.setSessionName(
-    options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
+    options.agentId ? `${baseSessionName}#${options.agentId.slice(0, SHORT_ID_LENGTH)}` : baseSessionName,
   );
 
   // Filter active tools: remove our own tools to prevent nesting,
@@ -395,32 +403,3 @@ export async function runAgent(
   const responseText = collector.getText().trim() || getLastAssistantText(session);
   return { responseText, session, aborted, steered: softLimitReached };
 }
-
-/**
- * Send a new prompt to an existing session (resume).
- */
-export async function resumeAgent(
-  session: AgentSession,
-  prompt: string,
-  options: Pick<RunOptions, "onToolActivity" | "onAssistantUsage" | "onCompaction"> & { signal?: AbortSignal } = {},
-): Promise<string> {
-  const collector = collectResponseText(session);
-  const cleanupAbort = forwardAbortSignal(session, options.signal);
-  const unsubEvents = subscribeToSessionEvents(session, options);
-
-  try {
-    await session.prompt(prompt);
-  } finally {
-    collector.unsubscribe();
-    unsubEvents();
-    cleanupAbort();
-  }
-
-  return collector.getText().trim() || getLastAssistantText(session);
-}
-
-
-
-
-
-

package/src/config-io.ts

@@ -12,6 +12,12 @@ import type { SubagentsConfig } from "./model-precedence.js";
 const CONFIG_DIR = path.join(process.env.HOME || "", ".pi", "agent");
 const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
 
+/** Default configuration — used when config file doesn't exist or is invalid. */
+export const DEFAULT_CONFIG: SubagentsConfig = {
+  agent: { default: null, forceBackground: false },
+  concurrency: { default: 4 },
+};
+
 /** Read config from disk. Returns defaults if file doesn't exist or is invalid. */
 export function loadConfig(): SubagentsConfig {
   try {
@@ -21,10 +27,7 @@ export function loadConfig(): SubagentsConfig {
     // File doesn't exist or is invalid — return defaults
   }
 
-  return {
-    agent: { default: null, forceBackground: false },
-    concurrency: { default: 4 },
-  };
+  return { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
 }
 
 /** Write config to disk with atomic rename. */

package/src/index.ts

@@ -5,8 +5,7 @@
  *
  * Stealth tool registration:
  *   - All tools register at extension init (not runtime)
- *   - description: "." (single character — tells LLM nothing)
- *   - No promptSnippet, no promptGuidelines
+ *   - No description, no promptSnippet, no promptGuidelines
  *   - Parameters without .description()
  *   - Model parameter removed from schema — injected via tool_call listener
  *
@@ -39,7 +38,7 @@ import { scanAgentFilesInDir, mergeAgents } from "./agent-discovery.js";
 import { AgentManager } from "./agent-manager.js";
 import { AgentWidget, buildStatsParts, formatMs, getDisplayName, type AgentActivity, type UICtx } from "./ui/agent-widget.js";
 import { showAgentsMainMenu } from "./menus.js";
-import { loadConfig } from "./config-io.js";
+import { loadConfig, DEFAULT_CONFIG } from "./config-io.js";
 import { executeAgentTool, toolCallListener, backgroundAgentIds, scheduleNudge } from "./tool-execution.js";
 import { executeStopAgentTool } from "./stop-agent-tool.js";
 
@@ -51,10 +50,7 @@ import { executeStopAgentTool } from "./stop-agent-tool.js";
 export let sessionOverrides: SessionModelOverrides = { default: null };
 
 /** Config cache — loaded at session_start, updated by /agents menu mutations. */
-export let __config: SubagentsConfig = {
-  agent: { default: null, forceBackground: false },
-  concurrency: { default: 4 },
-};
+export let __config: SubagentsConfig = { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
 
 /** Agent manager singleton — module-level, no globalThis access. */
 export let manager: AgentManager;
@@ -162,19 +158,21 @@ function buildStatsLine(d: Record<string, unknown>, theme: any): string {
  */
 function registerAgentTool(pi: ExtensionAPI): void {
   const types = getAvailableTypes();
+  // Use plain string to avoid verbose anyOf in prompt.
+  // Available types are listed in description for discoverability.
   const agentParam = types.length > 0
-    ? Type.Optional(Type.Union(types.map(t => Type.Literal(t))))
+    ? Type.Optional(Type.String({ description: types.join(",") }))
     : Type.Optional(Type.String());
+  // @ts-expect-error — description removed to save prompt tokens
   pi.registerTool({
     name: "Agent",
     label: "Agent",
-    description: ".",
     parameters: Type.Object({
       prompt: Type.String(),
       description: Type.String(),
       agent: agentParam,
       run_in_background: Type.Optional(Type.Boolean()),
-      resume: Type.Optional(Type.String()),
+
     }),
     execute: executeAgentTool,
 
@@ -241,10 +239,10 @@ export default function (pi: ExtensionAPI) {
   registerAgentTool(pi);
 
   // StopAgent tool — stealth schema, stop a running agent by ID
+  // @ts-expect-error — description removed to save prompt tokens
   pi.registerTool({
     name: "StopAgent",
     label: "StopAgent",
-    description: ".",
     parameters: Type.Object({
       agent_id: Type.String(),
     }),

package/src/menus.ts

@@ -8,12 +8,13 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getAgentConfig, getAvailableTypes, getAllTypes } from "./agent-types.js";
 import type { AgentRecord } from "./types.js";
+import { SHORT_ID_LENGTH } from "./types.js";
 import { ModelSelectorDialog, type ModelOption } from "./model-selector.js";
 import { ResultViewer, type ResultViewerStats } from "./result-viewer.js";
 import { getDisplayName } from "./ui/agent-widget.js";
 import { buildSnapshotMarkdown } from "./context.js";
 
-import { parseModelKey, errorMessage } from "./utils.js";
+import { parseModelKey } from "./utils.js";
 import {
   __config,
   sessionOverrides,
@@ -21,7 +22,7 @@ import {
   piInstance,
 } from "./index.js";
 import { resolveModel } from "./model-precedence.js";
-import { saveConfigAtomic } from "./config-io.js";
+import { saveConfigAtomic, DEFAULT_CONFIG } from "./config-io.js";
 
 // ============================================================================
 // Helpers
@@ -473,7 +474,6 @@ async function handleAgentBriefing(ctx: ExtensionCommandContext): Promise<void>
   lines.push("| `agent` | Which agent type to use (default: general-purpose) |");
   lines.push("| `thinking` | Optional thinking mode override (e.g., `off`, `minimal`, `low`, `medium`, `high`, `xhigh`) |");
   lines.push("| `run_in_background` | When `true`, result is auto-delivered — do NOT poll. Continue working while waiting. |");
-  lines.push("| `resume` | Agent ID to resume from; when set, `prompt` is appended to the previous conversation |");
   lines.push("");
 
   // Usage guidelines
@@ -481,7 +481,6 @@ async function handleAgentBriefing(ctx: ExtensionCommandContext): Promise<void>
   lines.push("- Agents start fresh with their config — they do NOT inherit the parent conversation");
   lines.push("- For parallel tasks, spawn multiple `run_in_background: true` agents in one turn");
   lines.push("  → Results are auto-delivered — do NOT poll, the result will arrive when ready");
-  lines.push("- Use `resume` to continue an incomplete agent's conversation");
   piInstance.sendUserMessage(lines.join("\n"));
   ctx.ui.notify("Agent briefing sent to LLM", "info");
 }
@@ -542,7 +541,7 @@ export async function showConcurrencySettingsMenu(
     // Reset all to defaults
     items.push("Reset all to defaults");
     actions.push(async () => {
-      __config.concurrency = { default: 4 };
+      __config.concurrency = { ...DEFAULT_CONFIG.concurrency };
       applyConcurrencyConfig();
       ctx.ui.notify("Concurrency reset to defaults", "info");
     });
@@ -672,7 +671,7 @@ async function showRunningAgentsMenu(
         record.status === "queued" ? "⏳" :
         record.status === "error" ? "✗" : "•";
       items.push(
-        `${statusIcon} ${record.id.slice(0, 8)}  ${record.type}  ${record.status}  ${elapsed}s`,
+        `${statusIcon} ${record.id.slice(0, SHORT_ID_LENGTH)}  ${record.type}  ${record.status}  ${elapsed}s`,
       );
 
       actions.push(async () => {
@@ -710,9 +709,9 @@ async function showResultViewer(
   text: string,
 ): Promise<void> {
   const titleSuffix = kind === "result"
-    ? record.id.slice(0, 8)
+    ? record.id.slice(0, SHORT_ID_LENGTH)
     : kind === "snapshot"
-    ? `snapshot \u00b7 ${record.id.slice(0, 8)}`
+    ? `snapshot \u00b7 ${record.id.slice(0, SHORT_ID_LENGTH)}`
     : "Error";
   const stats: ResultViewerStats = {
     lifetimeUsage: record.lifetimeUsage,
@@ -753,19 +752,11 @@ async function steerAgentById(
   const message = await ctx.ui.input(`Steer ${record.type}`);
   if (!message?.trim()) return;
 
-  try {
-    if (!record.session) {
-      if (!record.pendingSteers) {
-        record.pendingSteers = [];
-      }
-      record.pendingSteers.push(message.trim());
-      ctx.ui.notify(`Steer message queued for ${record.id.slice(0, 8)}…`, "info");
-    } else {
-      await record.session.steer(message.trim());
-      ctx.ui.notify(`Steer sent to ${record.id.slice(0, 8)}…`, "info");
-    }
-  } catch (err) {
-    ctx.ui.notify(`Steer failed: ${errorMessage(err)}`, "error");
+  const sent = await manager.steer(agentId, message.trim());
+  if (sent) {
+    ctx.ui.notify(`Steer sent to ${record.id.slice(0, SHORT_ID_LENGTH)}…`, "info");
+  } else {
+    ctx.ui.notify(`Steer failed for ${record.id.slice(0, SHORT_ID_LENGTH)}`, "error");
   }
 }
 
@@ -819,12 +810,12 @@ export async function showAgentActions(
     items.push("Stop");
     actions.push(async () => {
       manager?.abort(record.id);
-      ctx.ui.notify(`Stopped ${record.id.slice(0, 8)}`, "info");
+      ctx.ui.notify(`Stopped ${record.id.slice(0, SHORT_ID_LENGTH)}`, "info");
     });
   }
 
   if (items.length === 0) {
-    ctx.ui.notify(`Agent ${record.id.slice(0, 8)} — no actions available`, "info");
+    ctx.ui.notify(`Agent ${record.id.slice(0, SHORT_ID_LENGTH)} — no actions available`, "info");
     return;
   }
 
@@ -834,7 +825,7 @@ export async function showAgentActions(
   items.push("Back");
   actions.push(async () => {});
 
-  await runMenu(ctx, `Agent ${record.id.slice(0, 8)}`, items, actions);
+  await runMenu(ctx, `Agent ${record.id.slice(0, SHORT_ID_LENGTH)}`, items, actions);
 }
 
 async function showAgentTypes(ctx: ExtensionCommandContext): Promise<void> {

package/src/model-precedence.ts

@@ -36,7 +36,6 @@ export interface SessionModelOverrides {
   [agentType: string]: string | null | undefined;
 }
 
-/**
 /** Options for resolveModel. */
 export interface ResolveModelOptions {
   /** The type of subagent being spawned. */

package/src/output-file.ts

@@ -12,6 +12,7 @@
 import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { formatTokens } from "./usage.js";
 
 /** Max length for a truncated command in tool arg summaries. */
 const MAX_COMMAND_DISPLAY_LENGTH = 100;
@@ -254,9 +255,7 @@ export function streamToOutputFile(
 
     // Write DONE line
     const { turnCount = 0, toolUseCount = 0, totalTokens = 0, cost = 0 } = stats ?? {};
-    const tokensStr = totalTokens >= 1000
-      ? `${(totalTokens / 1000).toFixed(1)}k tokens`
-      : `${totalTokens} tokens`;
+    const tokensStr = `${formatTokens(totalTokens)} tokens`;
     const costStr = `$${cost.toFixed(3)}`;
     safeAppend(path, `${timestamp()} [DONE] ${turnCount} turns, ${toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
 

package/src/prompts.ts

@@ -6,11 +6,15 @@
  */
 
 import type { AgentConfig, EnvInfo } from "./types.js";
+import type { SkillMeta } from "./skill-loader.js";
+export type { SkillMeta };
 
 /** Extra sections to inject into the system prompt (skills only — no memoryBlock). */
 export interface PromptExtras {
-  /** Preloaded skill contents to inject. */
+  /** Preloaded skill contents to inject (full content). */
   skillBlocks?: { name: string; content: string }[];
+  /** Skill metadata for whitelist display (name, description, location only). */
+  skillMetas?: SkillMeta[];
 }
 
 /**
@@ -43,11 +47,34 @@ export function buildAgentPrompt(
 
   // Build optional extras suffix (skills only — no memoryBlock)
   const extraSections: string[] = [];
+
+  // Skill metadata whitelist (like Pi's available_skills format)
+  if (extras?.skillMetas?.length) {
+    const lines = [
+      "The following skills provide specialized instructions for specific tasks.",
+      "Use the read tool to load a skill's file when the task matches its description.",
+      "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+      "",
+      "<available_skills>",
+    ];
+    for (const skill of extras.skillMetas) {
+      lines.push("  <skill>");
+      lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+      lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+      lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+      lines.push("  </skill>");
+    }
+    lines.push("</available_skills>");
+    extraSections.push(lines.join("\n"));
+  }
+
+  // Preloaded skill contents (full dump into system prompt)
   if (extras?.skillBlocks?.length) {
     for (const skill of extras.skillBlocks) {
       extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
     }
   }
+
   const extrasSuffix = extraSections.length > 0 ? `\n\n${extraSections.join("\n")}` : "";
 
   const header = `You are a pi coding agent sub-agent.
@@ -58,4 +85,11 @@ ${envBlock}`;
   return `${activeAgentTag}${header}\n\n${config.systemPrompt}${extrasSuffix}`;
 }
 
+function escapeXml(value: string): string {
+  // Only escape < and > — enough for XML-like tags, keeps text readable for LLMs
+  return value
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
 

package/src/result-viewer.ts

@@ -45,6 +45,9 @@ export interface ResultViewerStats {
 /** Lines scrolled per PageUp/PageDown (kept at a fixed, comfortable amount). */
 const PAGE_STEP = 14;
 
+/** Render width for markdown content and separator line. */
+const RENDER_WIDTH = 78;
+
 /** Fixed non-viewport lines in the component (borders, title, spacers, hints, etc.). */
 const BASE_OVERHEAD = 10;
 
@@ -141,7 +144,7 @@ export class ResultViewer extends Container implements Component {
     // Build markdown renderer (pre-render to get total lines)
     const mdTheme = buildMarkdownTheme(theme);
     this.markdown = new Markdown(text, 0, 0, mdTheme);
-    this.renderedLines = this.markdown.render(78);
+    this.renderedLines = this.markdown.render(RENDER_WIDTH);
 
     this.buildUI(title, stats);
     this.updateViewport();
@@ -169,7 +172,7 @@ export class ResultViewer extends Container implements Component {
 
     // Separator
     this.addChild(
-      new Text(this.theme.fg("muted", "─".repeat(78)), 0, 0),
+      new Text(this.theme.fg("muted", "─".repeat(RENDER_WIDTH)), 0, 0),
     );
     this.addChild(new Spacer(1));
 
@@ -272,7 +275,7 @@ export class ResultViewer extends Container implements Component {
         this.textRef.text = newText;
         const mdTheme = buildMarkdownTheme(this.theme);
         this.markdown = new Markdown(newText, 0, 0, mdTheme);
-        this.renderedLines = this.markdown.render(78);
+        this.renderedLines = this.markdown.render(RENDER_WIDTH);
         // Preserve scroll position, clamped to new content bounds
         this.scrollOffset = Math.min(oldOffset, this.renderedLines.length - 1);
         this.updateViewport();

package/src/skill-loader.ts

@@ -32,37 +32,73 @@ interface PreloadedSkill {
   content: string;
 }
 
+export interface SkillMeta {
+  name: string;
+  description: string;
+  location: string;
+}
+
+/**
+ * Skill search roots in precedence order (project → user → legacy).
+ * Shared by preloadSkills and loadSkillMeta.
+ */
+function getSkillRoots(cwd: string): string[] {
+  return [
+    join(cwd, ".pi", "skills"),           // project — Pi standard
+    join(cwd, ".agents", "skills"),       // project — Agent Skills spec
+    join(getAgentDir(), "skills"),         // user — Pi standard
+    join(homedir(), ".agents", "skills"),  // user — Agent Skills spec
+    join(homedir(), ".pi", "skills"),      // legacy global, pre-Pi
+  ];
+}
+
 export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
   return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
 }
 
+/**
+ * Load skill metadata only (name, description, location) without full content.
+ * Used for the skills whitelist — agent can read full content on-demand.
+ */
+export function loadSkillMeta(skillNames: string[], cwd: string): SkillMeta[] {
+  return skillNames.map((name) => {
+    const location = findSkillLocation(name, cwd);
+    if (!location) {
+      return { name, description: `(Skill "${name}" not found)`, location: "" };
+    }
+    const description = extractDescription(location);
+    return { name, description, location };
+  });
+}
+
 function loadSkillContent(name: string, cwd: string): string {
   if (isUnsafeName(name)) {
     return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
-  const roots = [
-    join(cwd, ".pi", "skills"), // project — Pi standard
-    join(cwd, ".agents", "skills"), // project — Agent Skills spec
-    join(getAgentDir(), "skills"), // user — Pi standard
-    join(homedir(), ".agents", "skills"), // user — Agent Skills spec
-    join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
-  ];
-  for (const root of roots) {
-    const content = findInRoot(root, name);
+  for (const root of getSkillRoots(cwd)) {
+    const content = findInRoot(root, name, "content");
     if (content !== undefined) return content;
   }
   return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
 }
 
-function findInRoot(root: string, name: string): string | undefined {
-  if (isSymlink(root)) return undefined; // reject symlinked roots entirely
-  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
-  if (flat !== undefined) return flat;
-  return findSkillDirectory(root, name);
+function findInRoot(root: string, name: string, mode: "content" | "location"): string | undefined {
+  if (isSymlink(root)) return undefined;
+  const flatPath = join(root, `${name}.md`);
+  if (mode === "location") {
+    if (existsSync(flatPath)) return flatPath;
+  } else {
+    const content = safeReadFile(flatPath)?.trim();
+    if (content !== undefined) return content;
+  }
+  return findSkillDirectory(root, name, mode);
 }
 
-/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
-function findSkillDirectory(root: string, name: string): string | undefined {
+/**
+ * BFS under `root` for a directory named `name` containing `SKILL.md`.
+ * Pi-conforming filters. Returns either the file content or the file path.
+ */
+function findSkillDirectory(root: string, name: string, mode: "content" | "location"): string | undefined {
   if (!existsSync(root)) return undefined;
   const queue: string[] = [root];
 
@@ -91,6 +127,7 @@ function findSkillDirectory(root: string, name: string): string | undefined {
 
       if (isSkillDir) {
         if (entry.name === name) {
+          if (mode === "location") return skillMd;
           const content = safeReadFile(skillMd)?.trim();
           if (content !== undefined) return content;
         }
@@ -102,3 +139,42 @@ function findSkillDirectory(root: string, name: string): string | undefined {
   }
   return undefined;
 }
+
+/**
+ * Find skill file location without reading content.
+ * Returns the full path to the SKILL.md or .md file, or undefined if not found.
+ */
+function findSkillLocation(name: string, cwd: string): string | undefined {
+  if (isUnsafeName(name)) return undefined;
+  for (const root of getSkillRoots(cwd)) {
+    const location = findInRoot(root, name, "location");
+    if (location !== undefined) return location;
+  }
+  return undefined;
+}
+
+/** Extract description from SKILL.md frontmatter. */
+function extractDescription(filePath: string): string {
+  try {
+    const content = safeReadFile(filePath);
+    if (!content) return "(no description)";
+
+    // Simple frontmatter extraction
+    const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    if (!normalized.startsWith("---\n")) return "(no description)";
+    const endIndex = normalized.indexOf("\n---\n", 4);
+    if (endIndex === -1) return "(no description)";
+
+    const yamlString = normalized.slice(4, endIndex);
+    // Simple extraction of description field
+    const descMatch = yamlString.match(/^description:\s*["']?(.+?)["']?\s*$/m);
+    if (descMatch && descMatch[1]) {
+      // Truncate long descriptions
+      const desc = descMatch[1].trim();
+      return desc.length > 200 ? desc.slice(0, 197) + "..." : desc;
+    }
+    return "(no description)";
+  } catch {
+    return "(error reading description)";
+  }
+}

package/src/stop-agent-tool.ts

@@ -13,6 +13,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { successResult, errorResult } from "./tool-execution.js";
 import { manager } from "./index.js";
+import { SHORT_ID_LENGTH } from "./types.js";
 
 // ============================================================================
 // Running agents list helper
@@ -30,7 +31,7 @@ function formatRunningAgents(): string {
   if (agents.length === 0) return "none";
 
   return agents
-    .map((a) => `${a.type}·${a.id.slice(0, 5)}`)
+    .map((a) => `${a.type}·${a.id.slice(0, SHORT_ID_LENGTH)}`)
     .join(", ");
 }
 
@@ -69,7 +70,7 @@ export async function executeStopAgentTool(
 
   // Attempt to stop the running/queued agent
   if (manager.abort(agentId)) {
-    return successResult(`Stopped agent ${agentId.slice(0, 5)}`);
+    return successResult(`Stopped agent ${agentId.slice(0, SHORT_ID_LENGTH)}`);
   }
 
   return errorResult(`Failed to stop agent ${agentId}`);

package/src/tool-execution.ts

@@ -6,7 +6,6 @@
  */
 
 import type { ExtensionContext, ToolCallEvent } from "@earendil-works/pi-coding-agent";
-import type { Model } from "@earendil-works/pi-ai";
 
 import type { AgentRecord } from "./types.js";
 import type { SpawnOptions as AgentManagerSpawnOptions } from "./agent-manager.js";
@@ -151,7 +150,7 @@ function emitIndividualNudge(agentId: string, record?: AgentRecord): void {
   piInstance.sendMessage(
     {
       customType: "subagent-result",
-      content: record.result ?? "",
+      content: `[Subagent "${record.type}" completed]\n\n${record.result ?? ""}`,
       details,
       display: true,
     },
@@ -181,7 +180,6 @@ export async function executeAgentTool(
 
   const prompt = params.prompt as string;
   const description = params.description as string;
-  const resume = params.resume as string | undefined;
   const runInBackground = params.run_in_background as boolean | undefined;
   const isolated = params.isolated as boolean | undefined;
   const maxTurns = params.max_turns as number | undefined ?? getAgentConfig(resolvedType)?.maxTurns;
@@ -199,10 +197,6 @@ export async function executeAgentTool(
   const thinkingLevel = parseThinkingLevel(params.thinking as string | undefined)
     ?? getAgentConfig(resolvedType)?.thinking;
 
-  if (resume) {
-    return executeResumeAgent(resume, prompt);
-  }
-
   const spawnOptions: AgentManagerSpawnOptions = {
     description,
     model,
@@ -220,34 +214,23 @@ export async function executeAgentTool(
   return executeSpawnForeground(resolvedType, prompt, ctx, spawnOptions);
 }
 
-async function executeResumeAgent(
-  resume: string,
-  prompt: string,
-): Promise<any> {
-  const record = await manager.resume(resume, prompt);
-  if (!record) {
-    return errorResult(`Agent not found: ${resume}`);
-  }
-  return successResult(record.result ?? "");
-}
-
 async function executeSpawnBackground(
   resolvedType: string,
   prompt: string,
   ctx: ExtensionContext,
   spawnOptions: AgentManagerSpawnOptions,
 ): Promise<any> {
-  const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(
+  const { state, callbacks } = createActivityTracker(
     spawnOptions.maxTurns,
   );
 
   const agentId = manager.spawn(piInstance, ctx, resolvedType, prompt, {
     ...spawnOptions,
     isBackground: true,
-    ...bgCallbacks,
+    ...callbacks,
   });
   backgroundAgentIds.add(agentId);
-  agentActivity.set(agentId, bgState);
+  agentActivity.set(agentId, state);
   widget?.ensureTimer();
   widget?.update();
 
@@ -255,16 +238,11 @@ async function executeSpawnBackground(
   if (!record) {
     return errorResult("Failed to create agent");
   }
-  const bgDetails: Record<string, unknown> = { type: resolvedType, description: spawnOptions.description };
-  if (record.status === "queued") {
-    return successResult(`[Agent queued] Concurrency limit reached. It will start automatically when a slot frees up. A notification will arrive when done — User asks you not to poll, but wait for nudge.
+  const details: Record<string, unknown> = { type: resolvedType, description: spawnOptions.description };
+  const suffix = `A notification will arrive when done - User asks you not to poll or duplicate the delegated work.\n\nAgent ID: ${agentId}`;
+  const label = record.status === "queued" ? "Agent queued" : "Agent running";
 
-Agent ID: ${agentId}`, bgDetails);
-  }
-  return successResult(
-    `Agent running in background. A notification will arrive when done — User asks you not to poll, but wait for nudge.\n\nAgent ID: ${agentId}`,
-    bgDetails,
-  );
+  return successResult(`[${label}] ${suffix}`, details);
 }
 
 async function executeSpawnForeground(

package/src/types.ts

@@ -27,8 +27,10 @@ export interface AgentConfig {
   disallowedTools?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   extensions: true | string[] | false;
-  /** true = inherit all, string[] = only listed, false = none */
+  /** Whitelist of allowed skills (metadata only in system prompt). true = all, string[] = listed, false = none */
   skills: true | string[] | false;
+  /** Skills to preload with full content into system prompt. string[] = listed, false/undefined = none */
+  preloadSkills?: string[] | false;
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
@@ -95,6 +97,9 @@ export interface EnvInfo {
   platform: string;
 }
 
+/** How many characters of agent ID to show in display. */
+export const SHORT_ID_LENGTH = 8;
+
 /** Reason for a context compaction event. */
 export type CompactionReason = "manual" | "threshold" | "overflow";