@opencoven/coven-code 0.0.1

package/src/tools/builtin/painter.mjs

@@ -0,0 +1,81 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginTextToolRunResult,
+  pluginToolCallEvent,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export const TOOL_NAME = 'painter';
+
+const PAINTER_PLACEHOLDER_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M/wHwAFeAKU5XgS2wAAAABJRU5ErkJggg==',
+  'base64',
+);
+
+export async function executePromptPainterToolRequest(request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(TOOL_NAME, 'built-in', parsed)) return { output: `Tool disabled: ${TOOL_NAME}` };
+  request = { ...request, flags: normalizePainterInput(request.flags) };
+  if (!request.flags.prompt) return { output: 'painter requires --prompt' };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(TOOL_NAME, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(TOOL_NAME, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(TOOL_NAME, request.flags, toolUseID, callResult);
+  request = { ...callResult.request, flags: normalizePainterInput(callResult.request.flags) };
+  const decision = resolvePermissionDecision(TOOL_NAME, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(TOOL_NAME, decision),
+      permissionDenials: [{ tool: TOOL_NAME, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const output = writePainterArtifact(request.flags);
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(TOOL_NAME, request.flags, 'done', output, threadId, toolUseID),
+  );
+  return {
+    ...pluginTextToolRunResult(resultDecision, output),
+    toolUse: pluginToolUseBlock(TOOL_NAME, request.flags, toolUseID),
+  };
+}
+
+function normalizePainterInput(input = {}) {
+  const prompt = input.prompt ?? input.description ?? input.text ?? '';
+  const output = input.output ?? input.path ?? input.file ?? 'coven-code-painter-output.png';
+  const references = [input.reference, input.references, input.image, input.images]
+    .flat()
+    .filter(Boolean)
+    .map(String);
+  return {
+    ...input,
+    prompt: String(prompt),
+    output: String(output),
+    references,
+  };
+}
+
+function writePainterArtifact(input) {
+  const outputPath = path.resolve(process.cwd(), input.output);
+  mkdirSync(path.dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, PAINTER_PLACEHOLDER_PNG);
+  return [
+    `Generated image: ${input.output}`,
+    'media_type: image/png',
+    `prompt: ${input.prompt}`,
+    ...(input.references.length ? [`references: ${input.references.join(', ')}`] : []),
+  ].join('\n');
+}

package/src/tools/builtin/plugin-tool.mjs

@@ -0,0 +1,53 @@
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { createPluginToolContext, runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  normalizePluginToolExecuteOutput,
+  normalizePluginToolOutput,
+  permissionDeniedOutput,
+  pluginToolCallEvent,
+  pluginToolResultDecisionExitCode,
+  pluginToolResultDecisionOutput,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export async function executePromptPluginToolRequest(tool, request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(tool.name, 'plugin', parsed)) return { output: `Tool disabled: ${tool.name}` };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(tool.name, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(tool.name, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(tool.name, request.flags, toolUseID, callResult);
+  request = callResult.request;
+  const decision = resolvePermissionDecision(tool.name, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(tool.name, decision),
+      permissionDenials: [{ tool: tool.name, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const output = typeof tool.execute === 'function' ? await tool.execute(request.flags, createPluginToolContext()) : undefined;
+  const normalizedOutput = normalizePluginToolExecuteOutput(output);
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(tool.name, request.flags, 'done', normalizedOutput.raw, threadId, toolUseID),
+  );
+  const finalOutput = normalizePluginToolOutput(
+    pluginToolResultDecisionOutput(resultDecision, normalizedOutput.raw),
+  );
+  const exitCode = pluginToolResultDecisionExitCode(resultDecision);
+  return {
+    output: finalOutput.text,
+    toolResultOutput: finalOutput.raw,
+    exitCode,
+    toolUse: pluginToolUseBlock(tool.name, request.flags, toolUseID),
+  };
+}

package/src/tools/builtin/read-mcp-resource.mjs

@@ -0,0 +1,63 @@
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { listActiveMcpServerEntries } from '../../mcp/discover.mjs';
+import { readMcpResource } from '../../mcp/probe.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginTextToolRunResult,
+  pluginToolCallEvent,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export const TOOL_NAME = 'read_mcp_resource';
+
+export async function executePromptReadMcpResourceToolRequest(request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(TOOL_NAME, 'built-in', parsed)) return { output: `Tool disabled: ${TOOL_NAME}` };
+  request = { ...request, flags: normalizeReadMcpResourceInput(request.flags) };
+  if (!request.flags.server) return { output: 'read_mcp_resource requires --server' };
+  if (!request.flags.uri) return { output: 'read_mcp_resource requires --uri' };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(TOOL_NAME, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(TOOL_NAME, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(TOOL_NAME, request.flags, toolUseID, callResult);
+  request = { ...callResult.request, flags: normalizeReadMcpResourceInput(callResult.request.flags) };
+  const decision = resolvePermissionDecision(TOOL_NAME, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(TOOL_NAME, decision),
+      permissionDenials: [{ tool: TOOL_NAME, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const server = listActiveMcpServerEntries(parsed, '')
+    .find((entry) => entry.name === request.flags.server);
+  if (!server) return { output: `Unknown MCP server: ${request.flags.server}` };
+  const output = await readMcpResource(server.config, request.flags.uri, server.name);
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(TOOL_NAME, request.flags, 'done', output, threadId, toolUseID),
+  );
+  return {
+    ...pluginTextToolRunResult(resultDecision, output),
+    toolUse: pluginToolUseBlock(TOOL_NAME, request.flags, toolUseID),
+  };
+}
+
+function normalizeReadMcpResourceInput(input = {}) {
+  const server = input.server ?? input.name ?? input.mcp_server;
+  const uri = input.uri ?? input.url ?? input.resource;
+  return {
+    ...input,
+    server: server ? String(server) : '',
+    uri: uri ? String(uri) : '',
+  };
+}

package/src/tools/builtin/read-web-page.mjs

@@ -0,0 +1,72 @@
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { htmlToText } from '../../util/html.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginTextToolRunResult,
+  pluginToolCallEvent,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export const TOOL_NAME = 'read_web_page';
+
+export async function executePromptReadWebPageToolRequest(request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(TOOL_NAME, 'built-in', parsed)) return { output: `Tool disabled: ${TOOL_NAME}` };
+  request = { ...request, flags: normalizeReadWebPageInput(request.flags) };
+  if (!request.flags.url) return { output: 'read_web_page requires --url' };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(TOOL_NAME, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(TOOL_NAME, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(TOOL_NAME, request.flags, toolUseID, callResult);
+  request = { ...callResult.request, flags: normalizeReadWebPageInput(callResult.request.flags) };
+  const decision = resolvePermissionDecision(TOOL_NAME, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(TOOL_NAME, decision),
+      permissionDenials: [{ tool: TOOL_NAME, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const output = await readWebPageBuiltin(request.flags.url);
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(TOOL_NAME, request.flags, 'done', output, threadId, toolUseID),
+  );
+  return {
+    ...pluginTextToolRunResult(resultDecision, output),
+    toolUse: pluginToolUseBlock(TOOL_NAME, request.flags, toolUseID),
+  };
+}
+
+function normalizeReadWebPageInput(input = {}) {
+  const url = input.url ?? input.uri ?? input.href;
+  return {
+    ...input,
+    url: url ? String(url) : '',
+  };
+}
+
+async function readWebPageBuiltin(url) {
+  try {
+    const response = await fetch(url, {
+      headers: { 'user-agent': 'coven-code/0.0.0' },
+    });
+    if (!response.ok) return `Failed to read ${url}: HTTP ${response.status}`;
+    const contentType = response.headers.get('content-type') ?? '';
+    const body = await response.text();
+    return contentType.includes('html') || body.includes('<')
+      ? htmlToText(body)
+      : body.trimEnd();
+  } catch (error) {
+    return `Failed to read ${url}: ${error.message}`;
+  }
+}

package/src/tools/builtin/read.mjs

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginTextToolRunResult,
+  pluginToolCallEvent,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export const TOOL_NAME = 'Read';
+
+export async function executePromptReadToolRequest(request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(TOOL_NAME, 'built-in', parsed)) return { output: `Tool disabled: ${TOOL_NAME}` };
+  request = { ...request, flags: normalizeReadInput(request.flags) };
+  if (!request.flags.path) return { output: 'Read requires --path' };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(TOOL_NAME, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(TOOL_NAME, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(TOOL_NAME, request.flags, toolUseID, callResult);
+  request = { ...callResult.request, flags: normalizeReadInput(callResult.request.flags) };
+  const decision = resolvePermissionDecision(TOOL_NAME, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(TOOL_NAME, decision),
+      permissionDenials: [{ tool: TOOL_NAME, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const output = readBuiltinFile(request.flags.path).trimEnd();
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(TOOL_NAME, request.flags, 'done', output, threadId, toolUseID),
+  );
+  return {
+    ...pluginTextToolRunResult(resultDecision, output),
+    toolUse: pluginToolUseBlock(TOOL_NAME, request.flags, toolUseID),
+  };
+}
+
+function normalizeReadInput(input = {}) {
+  const filePath = input.path ?? input.file ?? input.file_path;
+  return { ...input, path: filePath ? String(filePath) : '' };
+}
+
+function readBuiltinFile(filePath) {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  return readFileSync(absolutePath, 'utf8');
+}

package/src/tools/builtin/runtime.mjs

@@ -0,0 +1,215 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+export function createToolUseID() {
+  return `toolu_${randomUUID()}`;
+}
+
+export function relativeToolPath(filePath) {
+  const relative = path.relative(process.cwd(), filePath);
+  return relative && !relative.startsWith('..') ? relative : filePath;
+}
+
+export function pluginToolCallEvent(tool, input, threadId, toolUseID = createToolUseID()) {
+  return {
+    toolUseID,
+    tool,
+    input,
+    thread: { id: threadId },
+  };
+}
+
+export function pluginToolResultEvent(tool, input, status, output, threadId, toolUseID, error) {
+  return {
+    toolUseID,
+    tool,
+    input,
+    status,
+    output,
+    ...(error ? { error } : {}),
+    thread: { id: threadId },
+  };
+}
+
+export function pluginToolUseBlock(tool, input, toolUseID) {
+  return {
+    type: 'tool_use',
+    id: toolUseID,
+    name: tool,
+    input,
+  };
+}
+
+export function pluginToolResultDecisionOutput(resultDecision = {}, fallback) {
+  validateToolResultDecision(resultDecision);
+  if (resultDecision.status === 'error') {
+    return resultDecision.error ?? resultDecision.output ?? fallback;
+  }
+  if (resultDecision.status === 'cancelled') {
+    return resultDecision.error ?? resultDecision.output ?? 'Tool cancelled';
+  }
+  return resultDecision.output !== undefined ? resultDecision.output : fallback;
+}
+
+export function pluginToolResultDecisionExitCode(resultDecision = {}, fallback = 0) {
+  validateToolResultDecision(resultDecision);
+  if (resultDecision.status === 'error' || resultDecision.status === 'cancelled') return 1;
+  if (resultDecision.status === 'done') return 0;
+  return fallback;
+}
+
+export function validateToolResultDecision(resultDecision = {}) {
+  if (!resultDecision || typeof resultDecision !== 'object' || !Object.hasOwn(resultDecision, 'status')) return;
+  if (resultDecision.status !== 'done' && resultDecision.status !== 'error' && resultDecision.status !== 'cancelled') {
+    throw new Error('plugin tool.result status must be done, error, or cancelled');
+  }
+  const allowedKeys = resultDecision.status === 'done' ? ['output', 'status'] : ['error', 'output', 'status'];
+  if (Object.keys(resultDecision).some((key) => !allowedKeys.includes(key))) {
+    throw new Error('plugin tool.result fields must match the documented union');
+  }
+  if (
+    (resultDecision.status === 'error' || resultDecision.status === 'cancelled') &&
+    resultDecision.error !== undefined &&
+    typeof resultDecision.error !== 'string'
+  ) {
+    throw new Error('plugin tool.result error must be a string');
+  }
+}
+
+export function toolResultContent(toolRun = {}) {
+  return Object.hasOwn(toolRun, 'toolResultOutput') ? toolRun.toolResultOutput : toolRun.output;
+}
+
+export function normalizePluginToolOutput(output) {
+  if (Array.isArray(output) && output.every(isPluginContentBlock)) {
+    const text = output.map(pluginContentBlockText).filter(Boolean).join('\n').trimEnd();
+    return { raw: output, text };
+  }
+  const text = String(output ?? '').trimEnd();
+  return { raw: text, text };
+}
+
+export function normalizePluginToolExecuteOutput(output) {
+  if (output === undefined || typeof output === 'string') return normalizePluginToolOutput(output);
+  if (Array.isArray(output)) {
+    if (!output.every(isPluginContentBlock)) {
+      throw new Error('plugin tool result content blocks must be text or image blocks');
+    }
+    return normalizePluginToolOutput(output);
+  }
+  throw new Error('plugin tool result must be a string, content blocks, or undefined');
+}
+
+export function isPluginContentBlock(block) {
+  if (!block || typeof block !== 'object') return false;
+  if (block.type === 'text') return typeof block.text === 'string';
+  if (block.type === 'image') return typeof block.mimeType === 'string' && typeof block.data === 'string';
+  return false;
+}
+
+export function pluginContentBlockText(block) {
+  if (block.type === 'text') return block.text;
+  return '';
+}
+
+export function applyToolCallDecision(toolName, request, callDecision = { action: 'allow' }) {
+  validateToolCallDecision(callDecision);
+  if (callDecision.action === 'allow') return { request };
+  if (callDecision.action === 'reject-and-continue') {
+    if (typeof callDecision.message !== 'string') {
+      throw new Error('plugin tool.call reject-and-continue message must be a string');
+    }
+    return {
+      output: {
+        output: callDecision.message,
+        exitCode: 0,
+      },
+    };
+  }
+  if (callDecision.action === 'synthesize') {
+    const result = callDecision.result && isPlainObject(callDecision.result)
+      ? callDecision.result
+      : callDecision;
+    if (typeof result.output !== 'string') {
+      throw new Error('plugin tool.call synthesize result.output must be a string');
+    }
+    if (result.exitCode !== undefined && !Number.isInteger(result.exitCode)) {
+      throw new Error('plugin tool.call synthesize result.exitCode must be an integer');
+    }
+    return {
+      output: {
+        output: result.output.trimEnd(),
+        exitCode: result.exitCode ?? 0,
+      },
+    };
+  }
+  if (callDecision.action === 'error') {
+    if (typeof callDecision.message !== 'string') {
+      throw new Error('plugin tool.call error message must be a string');
+    }
+    return {
+      output: {
+        output: callDecision.message,
+        exitCode: 1,
+      },
+    };
+  }
+  if (callDecision.action === 'modify') {
+    if (!isPlainObject(callDecision.input)) {
+      throw new Error('plugin tool.call modify input must be an object');
+    }
+    return { request: { ...request, flags: callDecision.input } };
+  }
+  return { request };
+}
+
+export function validateToolCallDecision(callDecision) {
+  if (!callDecision || typeof callDecision !== 'object') {
+    throw new Error('plugin tool.call result must be an object');
+  }
+  if (
+    callDecision.action !== 'allow' &&
+    callDecision.action !== 'reject-and-continue' &&
+    callDecision.action !== 'modify' &&
+    callDecision.action !== 'synthesize' &&
+    callDecision.action !== 'error'
+  ) {
+    throw new Error('plugin tool.call action must be allow, reject-and-continue, modify, synthesize, or error');
+  }
+  const allowedKeys = {
+    allow: ['action'],
+    'reject-and-continue': ['action', 'message'],
+    modify: ['action', 'input'],
+    synthesize: ['action', 'result'],
+    error: ['action', 'message'],
+  }[callDecision.action];
+  if (Object.keys(callDecision).some((key) => !allowedKeys.includes(key))) {
+    throw new Error('plugin tool.call fields must match the documented union');
+  }
+}
+
+export function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function toolCallDecisionToolRun(toolName, input, toolUseID, callResult) {
+  return {
+    ...callResult.output,
+    toolUse: pluginToolUseBlock(toolName, input, toolUseID),
+  };
+}
+
+export function pluginResultOutput(resultDecision, output) {
+  return String(pluginToolResultDecisionOutput(resultDecision, output) ?? '').trimEnd();
+}
+
+export function pluginTextToolRunResult(resultDecision, output, fallbackExitCode = 0) {
+  return {
+    output: pluginResultOutput(resultDecision, output),
+    exitCode: pluginToolResultDecisionExitCode(resultDecision, fallbackExitCode),
+  };
+}
+
+export function permissionDeniedOutput(toolName, decision) {
+  return decision.message ? `Permission denied for ${toolName}: ${decision.message}` : `Permission denied for ${toolName}`;
+}

package/src/tools/builtin/task.mjs

@@ -0,0 +1,63 @@
+import { localAgentResponse } from '../../agent/local.mjs';
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { isToolDisabled } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginTextToolRunResult,
+  pluginToolCallEvent,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  toolCallDecisionToolRun,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export const TOOL_NAME = 'Task';
+
+export async function executePromptTaskToolRequest(request, parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  if (isToolDisabled(TOOL_NAME, 'built-in', parsed)) return { output: `Tool disabled: ${TOOL_NAME}` };
+  request = { ...request, flags: normalizeTaskInput(request.flags) };
+  if (!request.flags.prompt) return { output: 'Task requires --prompt' };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(TOOL_NAME, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(TOOL_NAME, request, callDecision);
+  if (callResult.output) return toolCallDecisionToolRun(TOOL_NAME, request.flags, toolUseID, callResult);
+  request = { ...callResult.request, flags: normalizeTaskInput(callResult.request.flags) };
+  const decision = resolvePermissionDecision(TOOL_NAME, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(TOOL_NAME, decision),
+      permissionDenials: [{ tool: TOOL_NAME, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const output = localAgentResponse(request.flags.prompt, '');
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(TOOL_NAME, request.flags, 'done', output, threadId, toolUseID),
+  );
+  const finalResult = pluginTextToolRunResult(resultDecision, output);
+  return {
+    output: finalResult.output,
+    exitCode: finalResult.exitCode,
+    subagentMessages: [{ text: finalResult.output }],
+    toolResultParentToolUseId: null,
+    finalParentToolUseId: null,
+    toolUse: pluginToolUseBlock(TOOL_NAME, request.flags, toolUseID),
+  };
+}
+
+function normalizeTaskInput(input = {}) {
+  const prompt = input.prompt ?? input.task ?? input.instructions ?? input.message;
+  const description = input.description ?? input.title ?? input.name ?? 'subagent task';
+  return {
+    ...input,
+    description: String(description ?? 'subagent task'),
+    prompt: prompt ? String(prompt) : '',
+  };
+}

package/src/tools/builtin/toolbox-tool.mjs

@@ -0,0 +1,57 @@
+import { resolvePermissionDecision } from '../../commands/permissions.mjs';
+import { runPluginEventHandlers } from '../../plugins/discover.mjs';
+import { executeToolboxTool, isToolDisabled, listToolboxTools, normalizeToolName } from '../toolbox.mjs';
+import {
+  applyToolCallDecision,
+  createToolUseID,
+  permissionDeniedOutput,
+  pluginResultOutput,
+  pluginToolCallEvent,
+  pluginToolResultDecisionExitCode,
+  pluginToolResultEvent,
+  pluginToolUseBlock,
+  validateToolCallDecision,
+} from './runtime.mjs';
+
+export async function executePromptToolboxToolRequest(request, stdin = '', parsed = {}, plugins = { handlers: {} }, threadId = '') {
+  const toolboxName = normalizeToolName(request.toolName);
+  const tool = listToolboxTools(parsed).find((entry) => entry.name === toolboxName);
+  if (!tool) return { output: `Unknown tool: ${request.toolName}` };
+  if (isToolDisabled(tool.name, 'toolbox', parsed)) return { output: `Tool disabled: ${tool.name}` };
+  const toolUseID = createToolUseID();
+  const callDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.call'],
+    pluginToolCallEvent(tool.name, request.flags, threadId, toolUseID),
+    validateToolCallDecision,
+  );
+  const callResult = applyToolCallDecision(tool.name, request, callDecision);
+  if (callResult.output) {
+    return {
+      ...callResult.output,
+      toolUse: pluginToolUseBlock(tool.name, request.flags, toolUseID),
+    };
+  }
+  request.flags = callResult.request.flags;
+  const decision = resolvePermissionDecision(tool.name, request.flags, parsed, { threadId });
+  if (!parsed.dangerouslyAllowAll && decision.action !== 'allow') {
+    return {
+      output: permissionDeniedOutput(tool.name, decision),
+      permissionDenials: [{ tool: tool.name, action: decision.action, reason: 'permission' }],
+    };
+  }
+  const result = executeToolboxTool(tool, request.flags, stdin, threadId);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.status ?? 0;
+  const output = result.stdout.trimEnd();
+  const resultDecision = await runPluginEventHandlers(
+    plugins.handlers['tool.result'],
+    pluginToolResultEvent(tool.name, request.flags, (result.status ?? 0) === 0 ? 'done' : 'error', output, threadId, toolUseID),
+  );
+  const finalOutput = pluginResultOutput(resultDecision, output);
+  const exitCode = pluginToolResultDecisionExitCode(resultDecision, result.status ?? 0);
+  return {
+    output: finalOutput,
+    exitCode,
+    toolUse: pluginToolUseBlock(tool.name, request.flags, toolUseID),
+  };
+}