mu-harness 0.16.7 → 0.16.9

package/esm/harness/npm/src/agents/index.d.ts

@@ -1,4 +1,4 @@
-export type { Agent } from './types.js';
-export { type AgentRegistry, createAgentRegistry } from './registry.js';
+export type { Agent, ToolDecision, ToolGrants } from './types.js';
+export { type AgentRegistry, createAgentRegistry, toolDecision, toolNames } from './registry.js';
 export { parseAgent } from './parser.js';
 export { loadAgents } from './loader.js';

package/esm/harness/npm/src/agents/index.js

@@ -1,3 +1,3 @@
-export { createAgentRegistry } from './registry.js';
+export { createAgentRegistry, toolDecision, toolNames } from './registry.js';
 export { parseAgent } from './parser.js';
 export { loadAgents } from './loader.js';

package/esm/harness/npm/src/agents/parser.js

@@ -1,10 +1,22 @@
 import { parseFrontmatter, str } from '../common/index.js';
-const parseToolList = (raw) => {
-    if (Array.isArray(raw)) {
-        return raw.filter((entry) => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+const DECISIONS = new Set(['allow', 'ask', 'deny']);
+const parseStringList = (raw) => (Array.isArray(raw) ? raw : raw.split(','))
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+const parseTools = (raw) => {
+    if (Array.isArray(raw) || typeof raw === 'string') {
+        const list = parseStringList(raw);
+        return list.length > 0 ? list : undefined;
+    }
+    if (raw && typeof raw === 'object') {
+        const out = {};
+        for (const [tool, decision] of Object.entries(raw)) {
+            if (typeof decision === 'string' && DECISIONS.has(decision))
+                out[tool] = decision;
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
     }
-    if (typeof raw === 'string')
-        return raw.split(',').map((part) => part.trim()).filter(Boolean);
     return undefined;
 };
 export const parseAgent = (source, fallbackName) => {
@@ -13,7 +25,7 @@ export const parseAgent = (source, fallbackName) => {
         name: str(fields.name) ?? fallbackName,
         description: str(fields.description) ?? '',
         prompt: body,
-        tools: parseToolList(fields.tools),
+        tools: parseTools(fields.tools),
         model: str(fields.model),
         color: str(fields.color),
         extends: str(fields.extends),

package/esm/harness/npm/src/agents/registry.d.ts

@@ -1,6 +1,8 @@
-import type { Agent } from './types.js';
+import type { Agent, ToolDecision } from './types.js';
 export interface AgentRegistry {
     list(): Agent[];
     get(name: string): Agent | undefined;
 }
+export declare const toolDecision: (agent: Agent, tool: string) => ToolDecision;
+export declare const toolNames: (agent: Agent) => string[] | undefined;
 export declare const createAgentRegistry: (agents?: Agent[]) => AgentRegistry;

package/esm/harness/npm/src/agents/registry.js

@@ -1,3 +1,24 @@
+const asMap = (tools) => {
+    if (!tools)
+        return undefined;
+    if (Array.isArray(tools))
+        return Object.fromEntries(tools.map((tool) => [tool, 'allow']));
+    return tools;
+};
+export const toolDecision = (agent, tool) => {
+    const map = asMap(agent.tools);
+    if (!map)
+        return 'allow';
+    return map[tool] ?? map['*'] ?? 'deny';
+};
+export const toolNames = (agent) => {
+    const map = asMap(agent.tools);
+    if (!map)
+        return undefined;
+    if (map['*'] && map['*'] !== 'deny')
+        return ['*'];
+    return Object.entries(map).filter(([, decision]) => decision !== 'deny').map(([tool]) => tool);
+};
 const merge = (base, child) => ({
     name: child.name,
     description: child.description || base.description,

package/esm/harness/npm/src/agents/types.d.ts

@@ -1,8 +1,10 @@
+export type ToolDecision = 'allow' | 'ask' | 'deny';
+export type ToolGrants = string[] | Record<string, ToolDecision>;
 export interface Agent {
     name: string;
     description: string;
     prompt: string;
-    tools?: string[];
+    tools?: ToolGrants;
     model?: string;
     color?: string;
     extends?: string;

package/esm/harness/npm/src/harness/create.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import process from 'node:process';
-import { createAgentRegistry, loadAgents } from '../agents/index.js';
+import { createAgentRegistry, loadAgents, toolDecision, toolNames } from '../agents/index.js';
 import { createAgentsCommand, createCommandRegistry, createHelpCommand, createSessionsCommand, createSkillsCommand, } from '../commands/index.js';
 import { createHarnessConfig } from '../config/index.js';
 import { mergeHooks } from '../hooks/index.js';
@@ -18,7 +18,7 @@ const TITLE_AGENT = {
     tools: [],
 };
 export const createHarness = async (options) => {
-    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], title, titleModel, scheduler: enableScheduler = false, ...sessionDefaults } = options;
+    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
     const cwd = options.cwd ?? process.cwd();
     const config = createHarnessConfig({ hostName, xdg });
     const models = createModelRegistry({ providers, default: model });
@@ -42,17 +42,28 @@ export const createHarness = async (options) => {
     const runs = createSubAgentRegistry();
     const store = createSessionStore({ dir: join(config.dataDir, 'sessions') });
     const sessionTools = (extra = []) => [...(sessionDefaults.tools ?? []), ...extra, ...skillTools, ...schedulerTools];
+    const approvalHook = (getAgent) => approvals
+        ? approvals.manager.hooksFor({
+            decide: (call) => {
+                const agent = getAgent();
+                if (!agent)
+                    return 'allow';
+                return approvals.decide ? approvals.decide(agent, call) : toolDecision(agent, call.name);
+            },
+            agent: () => getAgent()?.name,
+        })
+        : undefined;
     const persona = (agent, opts) => createAgentSession({
         tools: opts.tools,
         plugins: sessionDefaults.plugins,
         system: agent.prompt,
-        hooks: opts.hooks ?? allowList(agent.tools),
+        hooks: opts.hooks ?? allowList(toolNames(agent)),
         ...models.resolve(opts.model ?? agent.model),
         id: newId(),
     });
     const spawn = (agent) => persistTo(store, persona(agent, {
         tools: sessionTools(),
-        hooks: mergeHooks([sessionDefaults.hooks, allowList(agent.tools)]),
+        hooks: mergeHooks([sessionDefaults.hooks, allowList(toolNames(agent)), approvalHook(() => agent)]),
     }));
     const scheduler = enableScheduler && tasks
         ? createScheduler({
@@ -61,6 +72,8 @@ export const createHarness = async (options) => {
                 try {
                     if (!task.agent)
                         throw new Error('scheduled task is missing an agent');
+                    if (!task.skill)
+                        throw new Error('scheduled task is missing a skill');
                     const output = await runSkill({ skills, agents, spawn, runs, parentId: task.id }, {
                         skill: task.skill,
                         task: task.prompt,
@@ -98,6 +111,7 @@ export const createHarness = async (options) => {
         },
         revive: ({ id, model: ref, messages }) => createAgentSession({
             ...sessionDefaults,
+            hooks: mergeHooks([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent())]),
             tools: sessionTools([createSubAgentTool({ registry: agents, spawn, runs, parentId: id })]),
             ...models.resolve(ref),
             id,

package/esm/harness/npm/src/harness/types.d.ts

@@ -1,7 +1,8 @@
 import type { Provider } from 'mu-core';
-import type { Agent, AgentRegistry } from '../agents/index.js';
+import type { Agent, AgentRegistry, ToolDecision } from '../agents/index.js';
 import type { CommandRegistry } from '../commands/index.js';
 import type { HarnessConfig, HarnessConfigOptions } from '../config/index.js';
+import type { ApprovalManager } from '../permissions/index.js';
 import type { PluginStore } from '../plugin/index.js';
 import type { Scheduler, TaskStore } from '../scheduler/index.js';
 import type { AgentSessionConfig, SessionManager } from '../session/index.js';
@@ -17,6 +18,14 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
     titleModel?: string;
     cwd?: string;
     scheduler?: boolean;
+    approvals?: {
+        manager: ApprovalManager;
+        activeAgent: () => Agent | undefined;
+        decide?: (agent: Agent, call: {
+            name: string;
+            input: unknown;
+        }) => ToolDecision;
+    };
 };
 export interface Harness {
     readonly config: HarnessConfig;

package/esm/harness/npm/src/permissions/approval-manager.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSessionHooks } from '../hooks/index.js';
+export type ApprovalAction = 'approve' | 'approve_always' | 'deny';
+export type ApprovalDecision = 'allow' | 'ask' | 'deny';
+export interface PendingApproval {
+    id: string;
+    name: string;
+    input: unknown;
+    agent?: string;
+}
+export interface ApprovalManager {
+    hooks: AgentSessionHooks;
+    hooksFor(opts: {
+        decide(call: {
+            name: string;
+            input: unknown;
+        }): ApprovalDecision;
+        agent?(): string | undefined;
+    }): AgentSessionHooks;
+    pending(): PendingApproval[];
+    resolve(id: string, action: ApprovalAction): boolean;
+    subscribe(listener: (req: PendingApproval) => void): () => void;
+}
+export interface ApprovalManagerOptions {
+    needsApproval?: (call: {
+        name: string;
+        input: unknown;
+    }) => boolean;
+    askTools?: string[];
+    newId?: () => string;
+}
+export declare const createApprovalManager: (options?: ApprovalManagerOptions) => ApprovalManager;

package/esm/harness/npm/src/permissions/approval-manager.js

@@ -0,0 +1,55 @@
+import { requireApproval } from './approval.js';
+const denied = (name) => [{ type: 'text', text: `Denied: ${name}` }];
+export const createApprovalManager = (options = {}) => {
+    const askTools = options.askTools ? new Set(options.askTools) : undefined;
+    const alwaysAllow = new Set();
+    const newId = options.newId ?? (() => crypto.randomUUID());
+    const keyOf = (agent, tool) => `${agent ?? ''}:${tool}`;
+    const waiters = new Map();
+    const listeners = new Set();
+    const request = (id, name, input, agent) => new Promise((resolve) => {
+        const req = { id, name, input, agent };
+        waiters.set(id, { resolve, req, key: keyOf(agent, name) });
+        for (const listener of listeners)
+            listener(req);
+    });
+    const defaultNeeds = options.needsApproval ?? (({ name }) => (askTools ? askTools.has(name) : true));
+    const hooks = requireApproval({
+        needsApproval: (call) => defaultNeeds(call) && !alwaysAllow.has(keyOf(undefined, call.name)),
+        newId,
+        prompt: (call) => request(call.id, call.name, call.input, undefined),
+    });
+    const hooksFor = ({ decide, agent }) => ({
+        beforeToolCall: async (call) => {
+            const decision = decide(call);
+            if (decision === 'allow')
+                return;
+            const agentName = agent?.();
+            if (decision === 'deny')
+                return denied(call.name);
+            if (alwaysAllow.has(keyOf(agentName, call.name)))
+                return;
+            const allow = await request(newId(), call.name, call.input, agentName);
+            return allow ? undefined : denied(call.name);
+        },
+    });
+    return {
+        hooks,
+        hooksFor,
+        pending: () => [...waiters.values()].map((w) => w.req),
+        resolve: (id, action) => {
+            const waiter = waiters.get(id);
+            if (!waiter)
+                return false;
+            waiters.delete(id);
+            if (action === 'approve_always')
+                alwaysAllow.add(waiter.key);
+            waiter.resolve(action !== 'deny');
+            return true;
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+};

package/esm/harness/npm/src/permissions/index.d.ts

@@ -1,3 +1,4 @@
 export { allowList, filterTools } from './allow-list.js';
 export { type ApprovalCall, requireApproval, type RequireApprovalOptions } from './approval.js';
+export { type ApprovalAction, type ApprovalDecision, type ApprovalManager, type ApprovalManagerOptions, createApprovalManager, type PendingApproval, } from './approval-manager.js';
 export { matchesAnyGlob } from './glob.js';

package/esm/harness/npm/src/permissions/index.js

@@ -1,3 +1,4 @@
 export { allowList, filterTools } from './allow-list.js';
 export { requireApproval } from './approval.js';
+export { createApprovalManager, } from './approval-manager.js';
 export { matchesAnyGlob } from './glob.js';

package/esm/harness/npm/src/plugin/import-ts.js

@@ -1,4 +1,3 @@
-import { transformSync } from '@swc/wasm-typescript';
 import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -62,6 +61,7 @@ const commonBase = (files) => {
 const outName = (path) => path.replace(TS_EXT, '.mjs');
 const rewriteSpecifiers = (code) => code.replace(SPECIFIER, (whole, quote, spec) => whole.replace(`${quote}${spec}${quote}`, `${quote}${outName(spec)}${quote}`));
 const transpileTree = async (entry) => {
+    const { transformSync } = await import('@swc/wasm-typescript');
     const sources = await collect(entry);
     if (sources.size === 1) {
         const { code } = transformSync(sources.get(entry), { mode: 'transform', module: true });

package/esm/harness/npm/src/scheduler/command.js

@@ -12,7 +12,7 @@ export const createTasksCommand = (tasks) => ({
                     ? `every ${t.schedule.ms}ms`
                     : 'once';
             const state = t.enabled ? when : `${when} (disabled)`;
-            return `- ${t.id} — ${t.skill} [${state}]`;
+            return `- ${t.id} — ${t.skill ?? t.agent ?? 'task'} [${state}]`;
         };
         return { ok: true, output: list.map(describe).join('\n') };
     },

package/esm/harness/npm/src/scheduler/engine/index.d.ts

@@ -1,3 +1,4 @@
-export type { Schedule, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './types.js';
+export type { Schedule, SchedulerEvent, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './types.js';
 export { createTaskStore } from './store.js';
+export { createMemoryTaskStore } from './memory-store.js';
 export { createScheduler, type Scheduler } from './scheduler.js';

package/esm/harness/npm/src/scheduler/engine/index.js

@@ -1,2 +1,3 @@
 export { createTaskStore } from './store.js';
+export { createMemoryTaskStore } from './memory-store.js';
 export { createScheduler } from './scheduler.js';

package/esm/harness/npm/src/scheduler/engine/memory-store.d.ts

@@ -0,0 +1,2 @@
+import type { Task, TaskStore } from './types.js';
+export declare const createMemoryTaskStore: (initial?: Task[]) => TaskStore;

package/esm/harness/npm/src/scheduler/engine/memory-store.js

@@ -0,0 +1,23 @@
+export const createMemoryTaskStore = (initial = []) => {
+    const tasks = new Map(initial.map((task) => [task.id, task]));
+    return {
+        list: async () => [...tasks.values()],
+        get: async (id) => tasks.get(id),
+        create: async (input) => {
+            const task = { ...input, id: crypto.randomUUID(), enabled: input.enabled ?? true, createdAt: Date.now() };
+            tasks.set(task.id, task);
+            return task;
+        },
+        update: async (id, patch) => {
+            const task = tasks.get(id);
+            if (!task)
+                return undefined;
+            const next = { ...task, ...patch, id: task.id };
+            tasks.set(id, next);
+            return next;
+        },
+        remove: async (id) => {
+            tasks.delete(id);
+        },
+    };
+};

package/esm/harness/npm/src/scheduler/engine/scheduler.d.ts

@@ -1,4 +1,4 @@
-import type { Task, TaskRunner, TaskStore } from './types.js';
+import type { SchedulerEvent, Task, TaskRunner, TaskStore } from './types.js';
 export interface Scheduler {
     start(): Promise<void>;
     stop(): void;
@@ -8,5 +8,6 @@ export interface Scheduler {
 export declare const createScheduler: (deps: {
     store: TaskStore;
     run: TaskRunner;
+    onEvent?: (event: SchedulerEvent) => void;
     onError?: (error: unknown, task: Task) => void;
 }) => Scheduler;

package/esm/harness/npm/src/scheduler/engine/scheduler.js

@@ -8,14 +8,22 @@ export const createScheduler = (deps) => {
         const task = await store.get(id);
         if (!task || !task.enabled)
             return;
+        const at = Date.now();
+        deps.onEvent?.({ type: 'task_started', task, at });
         try {
             const result = await run(task);
             await store.update(id, { lastRun: Date.now(), lastResult: result });
+            const durationMs = Date.now() - at;
+            if (result.ok)
+                deps.onEvent?.({ type: 'task_completed', task, at: Date.now(), durationMs, result });
+            else
+                deps.onEvent?.({ type: 'task_failed', task, at: Date.now(), durationMs, error: result.error ?? 'task failed' });
         }
         catch (error) {
             deps.onError?.(error, task);
             const message = error instanceof Error ? error.message : String(error);
             await store.update(id, { lastRun: Date.now(), lastResult: { ok: false, error: message } });
+            deps.onEvent?.({ type: 'task_failed', task, at: Date.now(), durationMs: Date.now() - at, error: message });
         }
         if (task.schedule.kind === 'once')
             await store.update(id, { enabled: false });
@@ -33,7 +41,7 @@ export const createScheduler = (deps) => {
             return;
         const s = task.schedule;
         if (s.kind === 'cron') {
-            crons.set(task.id, new Cron(s.expr, () => void fire(task.id)));
+            crons.set(task.id, new Cron(s.expr, s.timezone ? { timezone: s.timezone } : {}, () => void fire(task.id)));
         }
         else if (s.kind === 'interval') {
             timers.set(task.id, setInterval(() => void fire(task.id), s.ms));

package/esm/harness/npm/src/scheduler/engine/types.d.ts

@@ -1,6 +1,7 @@
 export type Schedule = {
     kind: 'cron';
     expr: string;
+    timezone?: string;
 } | {
     kind: 'interval';
     ms: number;
@@ -15,7 +16,7 @@ export interface TaskResult {
 }
 export interface Task {
     id: string;
-    skill: string;
+    skill?: string;
     prompt: string;
     agent?: string;
     schedule: Schedule;
@@ -24,6 +25,23 @@ export interface Task {
     lastRun?: number;
     lastResult?: TaskResult;
 }
+export type SchedulerEvent = {
+    type: 'task_started';
+    task: Task;
+    at: number;
+} | {
+    type: 'task_completed';
+    task: Task;
+    at: number;
+    durationMs: number;
+    result: TaskResult;
+} | {
+    type: 'task_failed';
+    task: Task;
+    at: number;
+    durationMs: number;
+    error: string;
+};
 export type TaskInput = Omit<Task, 'id' | 'enabled' | 'createdAt' | 'lastRun' | 'lastResult'> & {
     enabled?: boolean;
 };

package/esm/harness/npm/src/scheduler/index.d.ts

@@ -1,4 +1,4 @@
-export type { Schedule, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './engine/index.js';
-export { createScheduler, createTaskStore, type Scheduler } from './engine/index.js';
+export type { Schedule, SchedulerEvent, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './engine/index.js';
+export { createMemoryTaskStore, createScheduler, createTaskStore, type Scheduler } from './engine/index.js';
 export { createScheduleTaskTool } from './tool.js';
 export { createTasksCommand } from './command.js';

package/esm/harness/npm/src/scheduler/index.js

@@ -1,3 +1,3 @@
-export { createScheduler, createTaskStore } from './engine/index.js';
+export { createMemoryTaskStore, createScheduler, createTaskStore } from './engine/index.js';
 export { createScheduleTaskTool } from './tool.js';
 export { createTasksCommand } from './command.js';

package/esm/harness/npm/src/scheduler/tool.js

@@ -10,8 +10,7 @@ const toSchedule = (raw) => {
 };
 export const createScheduleTaskTool = (deps) => ({
     name: 'schedule_task',
-    description: 'Persist a recurring (cron / heartbeat) or one-shot task that runs a sub-agent under a skill on a given prompt.',
-    prompt: 'Use `schedule_task` to register work that should run later or on a schedule: a `cron` expression, an `everyMs` heartbeat, or a one-shot `at` timestamp. It invokes a skill on a prompt, like `run_skill`.',
+    description: 'Persist work to run later or on a schedule: a `cron` expression, an `everyMs` heartbeat, or a one-shot `at` timestamp. It invokes a skill on a prompt (like `run_skill`) via a sub-agent.',
     parameters: {
         type: 'object',
         properties: {

package/esm/harness/npm/src/session/agent-session.js

@@ -72,6 +72,7 @@ export const createAgentSession = (config) => {
     };
     return {
         id,
+        tools,
         get messages() {
             return messages;
         },

package/esm/harness/npm/src/session/manager.js

@@ -9,6 +9,9 @@ const onFirstMessage = (session, fire) => {
         get messages() {
             return session.messages;
         },
+        get tools() {
+            return session.tools;
+        },
         send: async (input) => {
             if (pending) {
                 pending = false;

package/esm/harness/npm/src/session/persist.js

@@ -7,6 +7,9 @@ export const persistTo = (store, session, persisted = 0) => {
         get messages() {
             return session.messages;
         },
+        get tools() {
+            return session.tools;
+        },
         send: async (input) => {
             await session.send(input);
             const all = session.messages;

package/esm/harness/npm/src/session/types.d.ts

@@ -1,4 +1,4 @@
-import type { ContentPart, LoopEvent, Message } from 'mu-core';
+import type { ContentPart, LoopEvent, Message, Tool } from 'mu-core';
 export type AgentSessionEvent = {
     type: 'turn_start';
     input: Message;
@@ -11,6 +11,7 @@ export type AgentSessionEvent = {
 export interface AgentSession {
     readonly id: string;
     readonly messages: readonly Message[];
+    readonly tools: readonly Tool[];
     send(input: string | ContentPart[]): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentSessionEvent) => void): () => void;

package/esm/harness/npm/src/skills/run.js

@@ -18,8 +18,7 @@ export const runSkill = async (deps, args) => {
 };
 export const createRunSkillTool = (deps) => ({
     name: 'run_skill',
-    description: 'Invoke a sub-agent equipped with a named skill to carry out a specific task. Returns its final answer.',
-    prompt: 'To carry out a self-contained task under a skill, call `run_skill` with the skill name, the task, and the agent persona to run it as.',
+    description: 'Invoke a sub-agent equipped with a named skill to carry out a self-contained task — pass the skill name, the task, and the agent persona to run it as. Returns its final answer.',
     parameters: {
         type: 'object',
         properties: {

package/esm/harness/npm/src/skills/tool.js

@@ -1,12 +1,12 @@
 export const createSkillTool = (registry) => ({
     name: 'skill',
-    description: "Load a named skill's instructions into the conversation, then follow them.",
-    get prompt() {
+    get description() {
+        const base = "Load a named skill's instructions into the conversation, then follow them.";
         const list = registry.list();
         if (!list.length)
-            return undefined;
+            return base;
         const catalog = list.map((skill) => `- ${skill.name}${skill.description ? `: ${skill.description}` : ''}`).join('\n');
-        return `When a request matches one of these skills, call \`skill\` with its name BEFORE acting, then follow the returned instructions:\n${catalog}`;
+        return `${base} When a request matches one of these skills, call \`skill\` with its name BEFORE acting:\n${catalog}`;
     },
     parameters: {
         type: 'object',

package/esm/harness/npm/src/skills/writer.js

@@ -4,8 +4,7 @@ import { parseSkill } from './parser.js';
 const slug = (name) => name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
 export const createSkillWriterTool = (deps) => ({
     name: 'create_skill',
-    description: 'Create a reusable skill: a named set of instructions the agent can load on demand later.',
-    prompt: 'When you discover a reusable workflow worth keeping, capture it with `create_skill` (name, description, instructions). Use `scope: "local"` for a skill specific to this project, or `scope: "config"` to make it available across all projects. It can then be loaded via `skill`.',
+    description: 'Create a reusable skill (name, description, instructions) the agent can load on demand later — capture a reusable workflow worth keeping. `scope: "local"` saves it to this project, `scope: "config"` makes it available across all projects; load it later via `skill`.',
     parameters: {
         type: 'object',
         properties: {

package/esm/harness/npm/src/subAgents/tool.js

@@ -1,30 +1,36 @@
 import { runSubAgent } from './runner.js';
-export const createSubAgentTool = (deps) => ({
-    name: 'subagent',
-    description: 'Delegate an isolated task to a named sub-agent. Returns its final answer.',
-    prompt: 'Delegate self-contained research or sub-tasks to a named sub-agent with `subagent`; treat its answer as research input.',
-    parameters: {
-        type: 'object',
-        properties: {
-            agent: { type: 'string', description: 'Sub-agent name.' },
-            task: { type: 'string', description: 'The task to delegate.' },
+const BASE_PROMPT = 'Delegate an isolated, fully-specifiable task to a named sub-agent instead of doing it inline; it returns only its final answer. Pick the matching sub-agent, brief it from scratch, then verify its answer before relying on it.';
+export const createSubAgentTool = (deps) => {
+    const roster = deps.registry.list()
+        .filter((agent) => agent.name !== 'title')
+        .map((agent) => `- ${agent.name}: ${agent.description}`)
+        .join('\n');
+    return {
+        name: 'subagent',
+        description: roster ? `${BASE_PROMPT}\n\nAvailable sub-agents:\n${roster}` : BASE_PROMPT,
+        parameters: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', description: 'Sub-agent name.' },
+                task: { type: 'string', description: 'The task to delegate.' },
+            },
+            required: ['agent', 'task'],
+            additionalProperties: false,
         },
-        required: ['agent', 'task'],
-        additionalProperties: false,
-    },
-    run: async (input, ctx) => {
-        const { agent, task } = (input ?? {});
-        if (!agent || !task)
-            return [{ type: 'text', text: 'Error: subagent requires `agent` and `task`.' }];
-        const def = deps.registry.get(agent);
-        if (!def)
-            return [{ type: 'text', text: `Error: unknown sub-agent "${agent}".` }];
-        const result = await runSubAgent(def, task, {
-            spawn: deps.spawn,
-            runs: deps.runs,
-            parentId: deps.parentId,
-            signal: ctx.signal,
-        });
-        return [{ type: 'text', text: result.text }];
-    },
-});
+        run: async (input, ctx) => {
+            const { agent, task } = (input ?? {});
+            if (!agent || !task)
+                return [{ type: 'text', text: 'Error: subagent requires `agent` and `task`.' }];
+            const def = deps.registry.get(agent);
+            if (!def)
+                return [{ type: 'text', text: `Error: unknown sub-agent "${agent}".` }];
+            const result = await runSubAgent(def, task, {
+                spawn: deps.spawn,
+                runs: deps.runs,
+                parentId: deps.parentId,
+                signal: ctx.signal,
+            });
+            return [{ type: 'text', text: result.text }];
+        },
+    };
+};