@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/tools/agent-vibe-tool.ts

@@ -0,0 +1,297 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import { AgentPersonaRegistry } from '../agent/persona-registry.ts';
+import {
+  discoverVibeFiles,
+  initVibeFile,
+  loadVibeImportSource,
+  resolveVibePathReference,
+  type AgentVibeFile,
+} from '../agent/vibe-file.ts';
+import {
+  vibeImportPersonaConfirmationRoutes,
+  vibeInitConfirmationRoutes,
+} from '../agent/vibe-confirmation-routes.ts';
+import type { CommandContext } from '../input/command-registry.ts';
+import { requireShellPaths } from '../input/commands/runtime-services.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+type AgentVibeAction = 'status' | 'show' | 'init' | 'import_persona';
+
+interface AgentVibeToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly scope?: unknown;
+  readonly reference?: unknown;
+  readonly path?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly force?: unknown;
+  readonly review?: unknown;
+  readonly use?: unknown;
+  readonly includeParameters?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+function output(value: unknown): { readonly success: true; readonly output: string } {
+  return {
+    success: true,
+    output: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+  };
+}
+
+function error(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || (typeof value === 'string' && ['true', 'yes', 'use', 'review', 'apply', 'run'].includes(value.trim().toLowerCase()));
+}
+
+function normalizeVibeAction(value: unknown): AgentVibeAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'list' || action === 'inspect') return 'status';
+  if (action === 'show' || action === 'file' || action === 'source' || action === 'read') return 'show';
+  if (action === 'init' || action === 'create' || action === 'new') return 'init';
+  if (action === 'import' || action === 'import_persona' || action === 'persona') return 'import_persona';
+  return null;
+}
+
+function readAction(args: AgentVibeToolArgs): AgentVibeAction {
+  return normalizeVibeAction(args.action) ?? normalizeVibeAction(args.mode) ?? 'status';
+}
+
+function readReference(args: AgentVibeToolArgs): string {
+  return readString(args.path)
+    || readString(args.reference)
+    || readString(args.target)
+    || readString(args.query)
+    || readString(args.scope)
+    || 'project';
+}
+
+function readScope(args: AgentVibeToolArgs): 'project' | 'global' {
+  return readString(args.scope).toLowerCase() === 'global' ? 'global' : 'project';
+}
+
+function requiresConfirmedUserIntent(args: AgentVibeToolArgs, action: AgentVibeAction): string | null {
+  if (!readBoolean(args.confirm)) return `vibe action:"${action}" requires confirm:true after the user asks for this personality change.`;
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  if (!explicitUserRequest) return `vibe action:"${action}" requires explicitUserRequest when confirm is true.`;
+  return null;
+}
+
+function describeVibeFile(file: AgentVibeFile): Record<string, unknown> {
+  return {
+    scope: file.scope,
+    path: file.path,
+    truncated: file.truncated,
+    name: file.frontmatter.name?.trim() || undefined,
+    description: file.frontmatter.description?.trim() || file.frontmatter.summary?.trim() || undefined,
+    bodyCharacters: file.body.length,
+  };
+}
+
+export function createAgentVibeTool(commandContext: CommandContext): Tool {
+  return {
+    definition: {
+      name: 'vibe',
+      description: 'Inspect and manage VIBE.md personality files.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'show', 'init', 'import_persona'],
+            description: 'Read status/show; confirm init or import_persona.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          scope: { type: 'string', enum: ['project', 'global'], description: 'VIBE.md scope for init/show/import.' },
+          reference: { type: 'string', description: 'project, global, or path reference.' },
+          path: { type: 'string', description: 'Path reference for show/import.' },
+          target: { type: 'string', description: 'Alias for reference.' },
+          query: { type: 'string', description: 'Alias for reference.' },
+          name: { type: 'string', description: 'Persona name when importing.' },
+          description: { type: 'string', description: 'Persona description when importing.' },
+          force: { type: 'boolean', description: 'Replace existing VIBE.md on confirmed init.' },
+          review: { type: 'boolean', description: 'Mark imported persona reviewed.' },
+          use: { type: 'boolean', description: 'Set imported persona active.' },
+          includeParameters: { type: 'boolean', description: 'Include searched paths and route details.' },
+          confirm: { type: 'boolean', description: 'Required true for init/import_persona.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing confirmed personality effects.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentVibeToolArgs;
+      const shellPaths = requireShellPaths(commandContext);
+      const action = readAction(args);
+
+      try {
+        if (action === 'status') {
+          const snapshot = discoverVibeFiles(shellPaths);
+          return output({
+            status: snapshot.blocked.length > 0 || snapshot.files.some((file) => file.truncated)
+              ? 'check'
+              : snapshot.files.length > 0
+                ? 'ready'
+                : 'recommended',
+            action: 'vibe_status',
+            applied: snapshot.files.length,
+            blocked: snapshot.blocked.length,
+            truncated: snapshot.files.filter((file) => file.truncated).length,
+            projectInitPath: snapshot.projectInitPath,
+            globalInitPath: snapshot.globalInitPath,
+            files: snapshot.files.map(describeVibeFile),
+            blockedFiles: snapshot.blocked.map((file) => ({
+              scope: file.scope,
+              path: file.path,
+              reason: previewHarnessText(file.reason, 220),
+            })),
+            routes: {
+              showProject: 'vibe action:"show" scope:"project"',
+              showGlobal: 'vibe action:"show" scope:"global"',
+              initProject: 'vibe action:"init" scope:"project" confirm:true explicitUserRequest:"..."',
+              importProjectPersona: 'vibe action:"import_persona" scope:"project" review:true use:true confirm:true explicitUserRequest:"..."',
+              promptContext: 'context action:"prompt" includeParameters:true',
+            },
+            ...(readBoolean(args.includeParameters) ? { searchedPaths: snapshot.searchedPaths } : {}),
+          });
+        }
+
+        if (action === 'show') {
+          const reference = readReference(args);
+          const source = loadVibeImportSource(shellPaths, reference);
+          return output({
+            status: 'ready',
+            action: 'vibe_show',
+            source: source.scope,
+            path: source.path,
+            name: source.name,
+            description: source.description,
+            bodyCharacters: source.body.length,
+            body: source.body,
+            policy: {
+              boundary: 'Loaded only after VIBE.md secret-looking content scan; blocked files are not returned.',
+            },
+          });
+        }
+
+        if (action === 'init') {
+          const scope = readScope(args);
+          const path = resolveVibePathReference(shellPaths, scope);
+          if (!readBoolean(args.confirm)) {
+            return output({
+              status: 'confirmation_required',
+              action: 'vibe_init',
+              scope,
+              path,
+              force: readBoolean(args.force),
+              next: 'Run with confirm:true and explicitUserRequest after the user asks to create or replace this VIBE.md file.',
+              confirmationRoutes: vibeInitConfirmationRoutes(scope, readBoolean(args.force)),
+            });
+          }
+          const intentError = requiresConfirmedUserIntent(args, 'init');
+          if (intentError) return error(intentError);
+          const result = initVibeFile(shellPaths, { scope, force: readBoolean(args.force) });
+          return output({
+            status: result.created ? 'created' : 'already_exists',
+            action: 'vibe_init',
+            scope,
+            path: result.path,
+            created: result.created,
+            next: result.created ? 'Edit this VIBE.md with the personality instructions the user wants.' : 'Use force:true only when the user asks to replace the existing file.',
+            policy: {
+              confirmation: 'confirmed',
+              explicitUserRequest: readString(args.explicitUserRequest),
+              boundary: 'Wrote only the scoped VIBE.md starter file.',
+            },
+          });
+        }
+
+        if (action === 'import_persona') {
+          const reference = readReference(args);
+          const source = loadVibeImportSource(shellPaths, reference);
+          const name = readString(args.name) || source.name;
+          const description = readString(args.description) || source.description;
+          if (!readBoolean(args.confirm)) {
+            return output({
+              status: 'confirmation_required',
+              action: 'vibe_import_persona',
+              source: source.scope,
+              path: source.path,
+              name,
+              description,
+              review: readBoolean(args.review),
+              use: readBoolean(args.use),
+              bodyCharacters: source.body.length,
+              next: 'Run with confirm:true and explicitUserRequest after the user asks to import VIBE.md into Agent-local personas.',
+              confirmationRoutes: vibeImportPersonaConfirmationRoutes({
+                reference,
+                name,
+                description,
+                review: readBoolean(args.review),
+                use: readBoolean(args.use),
+              }),
+            });
+          }
+          const intentError = requiresConfirmedUserIntent(args, 'import_persona');
+          if (intentError) return error(intentError);
+          const personaRegistry = AgentPersonaRegistry.fromShellPaths(shellPaths);
+          const created = personaRegistry.create({
+            name,
+            description,
+            body: source.body,
+            tags: ['vibe', source.scope],
+            triggers: ['vibe'],
+            source: 'imported',
+            provenance: `Imported VIBE.md (${source.scope}): ${source.path}`,
+          });
+          const reviewed = readBoolean(args.review) ? personaRegistry.markReviewed(created.id) : created;
+          const active = readBoolean(args.use) ? personaRegistry.setActive(created.id) : null;
+          return output({
+            status: 'imported',
+            action: 'vibe_import_persona',
+            source: source.scope,
+            path: source.path,
+            persona: {
+              id: reviewed.id,
+              name: reviewed.name,
+              description: reviewed.description,
+              reviewState: reviewed.reviewState,
+              active: active?.id === reviewed.id,
+            },
+            routes: {
+              inspectPersona: `agent_local_registry domain:"persona" action:"get" id:"${reviewed.id}"`,
+              promptContext: 'context action:"prompt" includeParameters:true',
+            },
+            policy: {
+              confirmation: 'confirmed',
+              explicitUserRequest: readString(args.explicitUserRequest),
+              boundary: 'Created only one Agent-local persona from secret-scanned VIBE.md content; no default Knowledge write.',
+            },
+          });
+        }
+
+        return error('Unknown VIBE.md action. Use action:"status" to inspect personality files.');
+      } catch (caught) {
+        return error(caught instanceof Error ? caught.message : String(caught));
+      }
+    },
+  };
+}
+
+export function registerAgentVibeTool(registry: ToolRegistry, commandContext: CommandContext): void {
+  if (!registry.has('vibe')) registry.register(createAgentVibeTool(commandContext));
+}

package/src/tools/agent-work-plan-tool.ts

@@ -13,27 +13,47 @@ export type AgentWorkPlanAction =
   | 'create'
   | 'update'
   | 'set_status'
+  | 'dispatch_agents'
   | 'remove'
   | 'clear_completed';
 
 export interface AgentWorkPlanToolArgs {
   readonly action?: unknown;
   readonly id?: unknown;
+  readonly ids?: unknown;
   readonly title?: unknown;
   readonly status?: unknown;
   readonly owner?: unknown;
   readonly source?: unknown;
   readonly notes?: unknown;
+  readonly template?: unknown;
+  readonly model?: unknown;
+  readonly provider?: unknown;
+  readonly reasoningEffort?: unknown;
+  readonly tools?: unknown;
+  readonly successCriteria?: unknown;
+  readonly requiredEvidence?: unknown;
+  readonly writeScope?: unknown;
+  readonly executionProtocol?: unknown;
+  readonly reviewMode?: unknown;
+  readonly communicationLane?: unknown;
+  readonly cohort?: unknown;
+  readonly agentContext?: unknown;
   readonly confirm?: unknown;
   readonly explicitUserRequest?: unknown;
 }
 
+interface AgentWorkPlanToolOptions {
+  readonly toolRegistry?: Pick<ToolRegistry, 'has' | 'execute'>;
+}
+
 const ACTIONS: readonly AgentWorkPlanAction[] = [
   'list',
   'get',
   'create',
   'update',
   'set_status',
+  'dispatch_agents',
   'remove',
   'clear_completed',
 ];
@@ -54,6 +74,12 @@ function readBoolean(value: unknown): boolean {
   return value === true || value === 'true' || value === 'yes';
 }
 
+function readStringList(value: unknown): readonly string[] {
+  if (Array.isArray(value)) return value.map(readString).filter((entry) => entry.length > 0);
+  const text = readString(value);
+  return text ? text.split(/[\n,]/).map((entry) => entry.trim()).filter((entry) => entry.length > 0) : [];
+}
+
 function failure(error: string): { readonly success: false; readonly error: string } {
   return { success: false, error };
 }
@@ -74,6 +100,11 @@ function requireTitle(args: AgentWorkPlanToolArgs): string {
   return title;
 }
 
+function dispatchIds(args: AgentWorkPlanToolArgs): readonly string[] {
+  const selected = [...readStringList(args.ids), readString(args.id)].filter((entry) => entry.length > 0);
+  return [...new Set(selected)];
+}
+
 function readOptionalStatus(value: unknown): WorkPlanItemStatus | undefined {
   if (value === undefined || value === null || readString(value) === '') return undefined;
   if (!isStatus(value)) throw new Error(`Invalid status. Valid values ${WORK_PLAN_STATUSES.join(', ')}.`);
@@ -91,6 +122,51 @@ function formatItem(item: WorkPlanItem): string {
   return `${item.id}  ${formatStatus(item.status)}${owner}${source}${completed}  ${item.title}`;
 }
 
+function routeArg(value: string): string {
+  return JSON.stringify(value);
+}
+
+function agentRoute(mode: string, agentId: string): string {
+  return `agent { mode: ${routeArg(mode)}, agentId: ${routeArg(agentId)} }`;
+}
+
+function workPlanRoute(action: string, id?: string, status?: WorkPlanItemStatus): string {
+  return [
+    `agent_work_plan action:${routeArg(action)}`,
+    id ? `id:${routeArg(id)}` : '',
+    status ? `status:${routeArg(status)}` : '',
+  ].filter(Boolean).join(' ');
+}
+
+function linkedAgentId(item: WorkPlanItem): string {
+  const value = item.linked?.agentId;
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function nextRouteLine(id: string, route: string): string {
+  return `    ${id} ${route}`;
+}
+
+function workPlanNextRouteLines(item: WorkPlanItem): readonly string[] {
+  const agentId = linkedAgentId(item);
+  const lines = [
+    '  nextRoutes',
+    nextRouteLine('inspectWorkItem', workPlanRoute('get', item.id)),
+    nextRouteLine('markDone', workPlanRoute('set_status', item.id, 'done')),
+    nextRouteLine('markBlocked', workPlanRoute('set_status', item.id, 'blocked')),
+  ];
+  if (agentId) {
+    lines.push(
+      nextRouteLine('inspectAgent', agentRoute('get', agentId)),
+      nextRouteLine('waitAgent', agentRoute('wait', agentId)),
+      nextRouteLine('messageAgent', agentRoute('message', agentId)),
+      nextRouteLine('cancelAgent', agentRoute('cancel', agentId)),
+      nextRouteLine('orchestrationDetail', `agent_harness mode:"agent_orchestration_agent" agentId:${routeArg(agentId)} includeParameters:true`),
+    );
+  }
+  return lines;
+}
+
 function formatItemDetail(item: WorkPlanItem): string {
   return [
     formatItem(item),
@@ -101,9 +177,16 @@ function formatItemDetail(item: WorkPlanItem): string {
       : 'linked (none)',
     '',
     item.notes || '(no notes)',
+    '',
+    ...workPlanNextRouteLines(item),
   ].join('\n');
 }
 
+function previewText(value: string, maxLength: number): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length > maxLength ? `${normalized.slice(0, Math.max(0, maxLength - 1))}...` : normalized;
+}
+
 function resolveItem(store: WorkPlanStore, idOrPrefix: string): WorkPlanItem {
   const needle = idOrPrefix.trim();
   if (!needle) throw new Error('id is required.');
@@ -118,6 +201,12 @@ function resolveItem(store: WorkPlanStore, idOrPrefix: string): WorkPlanItem {
   throw new Error(`Work plan item not found ${needle}`);
 }
 
+function resolveDispatchItems(store: WorkPlanStore, args: AgentWorkPlanToolArgs): readonly WorkPlanItem[] {
+  const ids = dispatchIds(args);
+  if (ids.length === 0) throw new Error('id or ids is required for dispatch_agents.');
+  return ids.map((id) => resolveItem(store, id));
+}
+
 function listOutput(store: WorkPlanStore): string {
   const plan = store.getActivePlan();
   const counts = new Map<WorkPlanItemStatus, number>(WORK_PLAN_STATUSES.map((status) => [status, 0]));
@@ -134,6 +223,7 @@ function listOutput(store: WorkPlanStore): string {
   }
   lines.push('', ...plan.items.slice(0, 20).map(formatItem));
   if (plan.items.length > 20) lines.push(`${plan.items.length - 20} more item(s) omitted.`);
+  lines.push('', 'Visible dispatch route: agent_work_plan action:"dispatch_agents" ids:["..."] confirm:true explicitUserRequest:"..."');
   return lines.join('\n');
 }
 
@@ -150,6 +240,21 @@ function requireDestructiveConfirmation(args: AgentWorkPlanToolArgs, action: str
   return null;
 }
 
+function requireConfirmedDispatch(args: AgentWorkPlanToolArgs, items: readonly WorkPlanItem[], route: string): string | null {
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  if (!explicitUserRequest) return 'explicitUserRequest is required before dispatching work plan items to visible agents.';
+  if (readBoolean(args.confirm)) return null;
+  return [
+    'Agent work plan dispatch preview',
+    '  policy visible agent dispatch requires confirm:true and an explicit user request',
+    `  request ${previewText(explicitUserRequest, 160)}`,
+    `  route ${route}`,
+    `  selected ${items.length}`,
+    ...items.map((item) => `  - ${item.id}  ${formatStatus(item.status)}  ${previewText(item.title, 120)}`),
+    '  no agents were spawned and no work-plan receipts were written',
+  ].join('\n');
+}
+
 function updatePatch(args: AgentWorkPlanToolArgs): Parameters<WorkPlanStore['updateItem']>[1] {
   const status = readOptionalStatus(args.status);
   return {
@@ -161,28 +266,181 @@ function updatePatch(args: AgentWorkPlanToolArgs): Parameters<WorkPlanStore['upd
   };
 }
 
-export function createAgentWorkPlanTool(store: WorkPlanStore): Tool {
+function optionalStringProperty(value: unknown): string | undefined {
+  return readString(value) || undefined;
+}
+
+function optionalStringListProperty(value: unknown): readonly string[] | undefined {
+  const entries = readStringList(value);
+  return entries.length > 0 ? entries : undefined;
+}
+
+function workPlanAgentContext(item: WorkPlanItem, args: AgentWorkPlanToolArgs): string {
+  return [
+    readString(args.agentContext),
+    `Work plan item id: ${item.id}`,
+    `Work plan item title: ${item.title}`,
+    item.owner ? `Work plan owner: ${item.owner}` : '',
+    item.source ? `Work plan source: ${item.source}` : '',
+    item.notes ? `Work plan notes:\n${item.notes}` : '',
+    'Keep progress visible, return evidence, and make the final status easy for the user to review.',
+  ].filter((part) => part.trim().length > 0).join('\n\n');
+}
+
+function agentTaskForItem(item: WorkPlanItem, args: AgentWorkPlanToolArgs): Record<string, unknown> {
+  return {
+    task: item.title,
+    ...(optionalStringProperty(args.template) ? { template: optionalStringProperty(args.template) } : {}),
+    ...(optionalStringProperty(args.model) ? { model: optionalStringProperty(args.model) } : {}),
+    ...(optionalStringProperty(args.provider) ? { provider: optionalStringProperty(args.provider) } : {}),
+    ...(optionalStringProperty(args.reasoningEffort) ? { reasoningEffort: optionalStringProperty(args.reasoningEffort) } : {}),
+    ...(optionalStringListProperty(args.tools) ? { tools: optionalStringListProperty(args.tools), restrictTools: true } : {}),
+    ...(optionalStringListProperty(args.successCriteria) ? { successCriteria: optionalStringListProperty(args.successCriteria) } : {}),
+    requiredEvidence: optionalStringListProperty(args.requiredEvidence) ?? ['result summary', 'verification or blocker', 'changed files or artifacts when applicable'],
+    ...(optionalStringListProperty(args.writeScope) ? { writeScope: optionalStringListProperty(args.writeScope) } : {}),
+    ...(optionalStringProperty(args.executionProtocol) ? { executionProtocol: optionalStringProperty(args.executionProtocol) } : {}),
+    ...(optionalStringProperty(args.reviewMode) ? { reviewMode: optionalStringProperty(args.reviewMode) } : {}),
+    ...(optionalStringProperty(args.communicationLane) ? { communicationLane: optionalStringProperty(args.communicationLane) } : {}),
+    context: workPlanAgentContext(item, args),
+    orchestrationNodeId: item.id,
+  };
+}
+
+function parseAgentToolOutput(outputText: string): Record<string, unknown> {
+  const parsed = JSON.parse(outputText) as unknown;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('agent tool returned non-object output.');
+  return parsed as Record<string, unknown>;
+}
+
+function agentIdsFromDispatchPayload(payload: Record<string, unknown>): readonly string[] {
+  const direct = readString(payload.agentId);
+  if (direct) return [direct];
+  if (!Array.isArray(payload.agents)) return [];
+  return payload.agents
+    .map((entry) => entry && typeof entry === 'object' ? readString((entry as Record<string, unknown>).id) || readString((entry as Record<string, unknown>).agentId) : '')
+    .filter((entry) => entry.length > 0);
+}
+
+function appendDispatchReceipt(notes: string | undefined, agentId: string, route: string, cohort: string, explicitUserRequest: string): string {
+  const receipt = [
+    `Agent dispatch receipt ${new Date().toISOString()}`,
+    `agent ${agentId}`,
+    `route ${route}`,
+    `cohort ${cohort}`,
+    `request ${previewText(explicitUserRequest, 160)}`,
+  ].join('; ');
+  return [notes?.trim() ?? '', receipt].filter((part) => part.length > 0).join('\n\n');
+}
+
+function dispatchNextRouteLines(receipts: readonly { readonly item: WorkPlanItem; readonly agentId: string }[]): readonly string[] {
+  return [
+    '  nextRoutes',
+    nextRouteLine('orchestration', 'agent_harness mode:"agent_orchestration" includeParameters:true'),
+    nextRouteLine('workPlan', 'agent_work_plan action:"list"'),
+    ...receipts.flatMap((receipt, index) => {
+      const prefix = receipts.length > 1 ? `agent${index + 1}` : 'agent';
+      return [
+        nextRouteLine(`${prefix}.inspect`, agentRoute('get', receipt.agentId)),
+        nextRouteLine(`${prefix}.wait`, agentRoute('wait', receipt.agentId)),
+        nextRouteLine(`${prefix}.message`, agentRoute('message', receipt.agentId)),
+        nextRouteLine(`${prefix}.cancel`, agentRoute('cancel', receipt.agentId)),
+        nextRouteLine(`${prefix}.workItem`, workPlanRoute('get', receipt.item.id)),
+      ];
+    }),
+  ];
+}
+
+async function dispatchAgentsFromWorkPlan(
+  store: WorkPlanStore,
+  args: AgentWorkPlanToolArgs,
+  options: AgentWorkPlanToolOptions,
+): Promise<{ readonly success: true; readonly output: string } | { readonly success: false; readonly error: string }> {
+  if (!options.toolRegistry || !options.toolRegistry.has('agent')) {
+    return failure('agent_work_plan dispatch_agents requires the first-class agent tool to be registered.');
+  }
+  const items = resolveDispatchItems(store, args);
+  const plan = store.getActivePlan();
+  const cohort = readString(args.cohort) || `workplan-${plan.id}`;
+  const route = items.length === 1 ? 'agent { mode: "spawn" }' : 'agent { mode: "batch-spawn" }';
+  const denied = requireConfirmedDispatch(args, items, route);
+  if (denied) return failure(denied);
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  const commonArgs = {
+    authoritativeTask: explicitUserRequest,
+    cohort,
+    orchestrationGraphId: `workplan:${plan.id}`,
+  };
+  const agentArgs = items.length === 1
+    ? {
+        mode: 'spawn',
+        ...commonArgs,
+        ...agentTaskForItem(items[0]!, args),
+      }
+    : {
+        mode: 'batch-spawn',
+        ...commonArgs,
+        tasks: items.map((item) => agentTaskForItem(item, args)),
+      };
+  const result = await options.toolRegistry.execute(`agent-work-plan-dispatch-${Date.now()}`, 'agent', agentArgs);
+  if (!result.success) return failure(result.error ?? 'Agent dispatch failed.');
+  const payload = parseAgentToolOutput(result.output ?? '{}');
+  const agentIds = agentIdsFromDispatchPayload(payload);
+  if (agentIds.length === 0) return failure('Agent dispatch succeeded but returned no agent ids to attach to the work plan.');
+  const receipts = items.map((item, index) => {
+    const agentId = agentIds[Math.min(index, agentIds.length - 1)]!;
+    const updated = store.updateItem(item.id, {
+      status: item.status === 'done' || item.status === 'cancelled' ? item.status : 'in_progress',
+      linked: { ...(item.linked ?? {}), agentId },
+      notes: appendDispatchReceipt(item.notes, agentId, route, cohort, explicitUserRequest),
+    });
+    return { item: updated, agentId };
+  });
+  return output([
+    'Dispatched Agent work plan items',
+    `  route ${route}`,
+    `  cohort ${cohort}`,
+    `  saved receipts ${receipts.length}`,
+    ...receipts.map((receipt) => `  - ${receipt.item.id} -> ${receipt.agentId}  ${previewText(receipt.item.title, 100)}`),
+    ...dispatchNextRouteLines(receipts),
+  ].join('\n'));
+}
+
+export function createAgentWorkPlanTool(store: WorkPlanStore, options: AgentWorkPlanToolOptions = {}): Tool {
   return {
     definition: {
       name: 'agent_work_plan',
-      description: 'Inspect or update the visible Agent-local work plan.',
+      description: 'Manage and dispatch approved visible Agent work plan items.',
       parameters: {
         type: 'object',
         properties: {
           action: { type: 'string', enum: [...ACTIONS] },
           id: { type: 'string', description: 'Work plan item id or unique id prefix for get/update/set_status/remove.' },
+          ids: { type: 'array', items: { type: 'string' }, description: 'Work plan item ids or unique prefixes for dispatch_agents.' },
           title: { type: 'string', description: 'Work plan item title for create/update.' },
           status: { type: 'string', enum: [...WORK_PLAN_STATUSES], description: 'Work plan item status.' },
           owner: { type: 'string', description: 'Optional owner label.' },
           source: { type: 'string', description: 'Optional source/provenance label.' },
           notes: { type: 'string', description: 'Optional work-plan notes.' },
-          confirm: { type: 'boolean', description: 'Required true for remove and clear_completed.' },
-          explicitUserRequest: { type: 'string', description: 'Required for destructive remove and clear_completed actions.' },
+          template: { type: 'string', description: 'Agent template for dispatch_agents.' },
+          model: { type: 'string', description: 'Provider-qualified model for dispatch_agents.' },
+          provider: { type: 'string', description: 'Provider id for dispatch_agents when model is provider-qualified.' },
+          reasoningEffort: { type: 'string', enum: ['instant', 'low', 'medium', 'high'], description: 'Reasoning effort for dispatch_agents.' },
+          tools: { type: 'array', items: { type: 'string' }, description: 'Exact tool subset for dispatched agents.' },
+          successCriteria: { type: 'array', items: { type: 'string' }, description: 'Success criteria for dispatched agents.' },
+          requiredEvidence: { type: 'array', items: { type: 'string' }, description: 'Required evidence for dispatched agents.' },
+          writeScope: { type: 'array', items: { type: 'string' }, description: 'Expected write scope for dispatched agents.' },
+          executionProtocol: { type: 'string', enum: ['direct', 'gather-plan-apply'], description: 'Execution protocol for dispatch_agents.' },
+          reviewMode: { type: 'string', enum: ['none', 'wrfc'], description: 'Review mode for dispatch_agents.' },
+          communicationLane: { type: 'string', enum: ['parent-only', 'parent-and-children', 'cohort', 'direct'], description: 'Communication lane for dispatch_agents.' },
+          cohort: { type: 'string', description: 'Agent cohort for dispatch_agents. Defaults to the work plan id.' },
+          agentContext: { type: 'string', description: 'Additional context prepended to each dispatched agent task.' },
+          confirm: { type: 'boolean', description: 'Required true for remove, clear_completed, and dispatch_agents.' },
+          explicitUserRequest: { type: 'string', description: 'Required for remove, clear_completed, and agent dispatch.' },
         },
         required: ['action'],
         additionalProperties: false,
       },
-      sideEffects: ['state'],
+      sideEffects: ['state', 'agent', 'workflow'],
     },
     execute: async (rawArgs: unknown) => {
       try {
@@ -190,6 +448,7 @@ export function createAgentWorkPlanTool(store: WorkPlanStore): Tool {
         if (!isAction(args.action)) return failure(`Unknown Agent work plan action. Valid values ${ACTIONS.join(', ')}.`);
         if (args.action === 'list') return output(listOutput(store));
         if (args.action === 'get') return output(formatItemDetail(resolveItem(store, requireId(args))));
+        if (args.action === 'dispatch_agents') return dispatchAgentsFromWorkPlan(store, args, options);
         if (args.action === 'create') {
           const item = store.addItem(requireTitle(args), {
             status: readOptionalStatus(args.status) ?? 'pending',
@@ -247,5 +506,5 @@ export function createAgentWorkPlanTool(store: WorkPlanStore): Tool {
 }
 
 export function registerAgentWorkPlanTool(registry: ToolRegistry, store: WorkPlanStore): void {
-  registry.register(createAgentWorkPlanTool(store));
+  registry.register(createAgentWorkPlanTool(store, { toolRegistry: registry }));
 }