toolcraft 0.0.136 → 0.0.138

package/composition.json

@@ -36,6 +36,11 @@
       "version": "0.0.1",
       "license": "MIT"
     },
+    {
+      "name": "@poe-code/user-error",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
     {
       "name": "auth-store",
       "version": "0.0.1",
@@ -108,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.136",
+      "version": "0.0.138",
       "license": "MIT"
     },
     {
@@ -118,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.136",
+      "version": "0.0.138",
       "license": "MIT"
     },
     {

package/dist/cli.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { validate as validateSchema } from "toolcraft-schema";
 import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderHelpTokens, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
-import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, resolveCommandSecrets } from "./index.js";
+import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, isUserError, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { writeErrorReport } from "./error-report.js";
 import { assertHumanInLoopWired, mergeApprovalsRoot } from "./human-in-loop/wiring.js";
@@ -396,6 +396,13 @@ function formatOptionFlags(field, globalLongOptionFlags) {
     }
     return [`-${field.shortFlag}`, field.optionFlag, ...field.longAliases].join(", ");
 }
+function formatMissingParameterMessage(field) {
+    const message = `Missing required parameter "${field.displayPath}".`;
+    if (field.schema.kind !== "enum") {
+        return message;
+    }
+    return `${message} Expected one of: ${field.schema.values.map((value) => String(value)).join(", ")}.`;
+}
 function formatPositionalToken(field) {
     const optionalPositional = field.optional || field.hasDefault;
     if (field.variadicPosition === true) {
@@ -1132,6 +1139,8 @@ function formatExampleRows(examples, breadcrumb, rootUsageName) {
     return examples.map((example) => `${example.title}\n  ${formatExampleCommand(breadcrumb, rootUsageName, example.params)}`);
 }
 const MAX_INLINE_OPTIONAL_PARAMETER_TOKENS = 8;
+/** Mirrors the fallback width used by the design system's column layout. */
+const DEFAULT_HELP_TOTAL_WIDTH = 100;
 function tokenizeHelpFlags(flags) {
     const tokens = [];
     let index = 0;
@@ -1208,9 +1217,13 @@ function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
         .map((field) => createCommandParameterToken(formatCommandParameterFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
         .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
 }
-function collapseOptionalParameterTokens(parameterTokens) {
+function collapseOptionalParameterTokens(parameterTokens, inlineWidthBudget = Number.POSITIVE_INFINITY) {
     const optionalCount = parameterTokens.filter((token) => token.optional).length;
-    if (optionalCount <= MAX_INLINE_OPTIONAL_PARAMETER_TOKENS) {
+    if (optionalCount === 0) {
+        return parameterTokens;
+    }
+    const inlineWidth = parameterTokens.reduce((total, token) => total + token.text.length + 1, 0);
+    if (optionalCount <= MAX_INLINE_OPTIONAL_PARAMETER_TOKENS && inlineWidth <= inlineWidthBudget) {
         return parameterTokens;
     }
     const required = parameterTokens.filter((token) => !token.optional);
@@ -1231,8 +1244,11 @@ function collapseOptionalParameterTokens(parameterTokens) {
 function formatCommandRowNameTokens(node, casing, globalLongOptionFlags) {
     const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
     const nameTokens = [{ text: baseName, role: "command" }];
+    // formatCommandList indents rows by two columns, so anything wider than the rest of the
+    // terminal wraps onto continuation lines and makes the command list unreadable.
+    const inlineWidthBudget = Math.max(0, (process.stdout.columns ?? DEFAULT_HELP_TOTAL_WIDTH) - 2 - baseName.length);
     const parameterTokens = node.kind === "command"
-        ? collapseOptionalParameterTokens(formatCommandParameterTokens(node, casing, globalLongOptionFlags))
+        ? collapseOptionalParameterTokens(formatCommandParameterTokens(node, casing, globalLongOptionFlags), inlineWidthBudget)
         : [];
     for (const token of parameterTokens) {
         nameTokens.push({ text: " ", role: "literal" }, ...token.tokens);
@@ -1285,10 +1301,10 @@ function formatGlobalOptionsLine(ctx) {
     if (ctx.showVersion) {
         flags.push("--version");
     }
-    return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
+    return flags.length > 0 ? `${text.section("Global Options:")} ${flags.join("  ")}` : "";
 }
 function formatLeafGlobalOptionsLine(ctx) {
-    return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+    return ctx.controls.verbose ? `${text.section("Global Options:")} -v, --verbose` : "";
 }
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
     const seen = new Map();
@@ -1331,21 +1347,16 @@ function formatHelpOptionList(rows) {
         : formatOptionList(rows);
 }
 function sortLeafHelpOptionFields(fields) {
-    const positionals = [];
     const required = [];
     const optional = [];
     for (const field of fields) {
-        if (field.positionalIndex !== undefined) {
-            positionals.push(field);
-            continue;
-        }
         if (!field.optional && !field.hasDefault) {
             required.push(field);
             continue;
         }
         optional.push(field);
     }
-    return [...positionals, ...required, ...optional];
+    return [...required, ...optional];
 }
 function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const visibleBreadcrumb = breadcrumb.filter((segment) => segment.length > 0);
@@ -1388,13 +1399,13 @@ function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUs
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
     const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags, globalOptions.controls.help);
     if (commandRows.length > 0) {
-        sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
+        sections.push(`${text.section("Commands:")}\n${formatHelpCommandList(commandRows)}`);
     }
     if (isRoot) {
         const schemaGlobalRows = collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags);
         const builtInLine = formatGlobalOptionsLine(globalOptions);
         if (schemaGlobalRows.length > 0) {
-            sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(schemaGlobalRows)}\n${builtInLine}`);
+            sections.push(`${text.section("Options:")}\n${formatHelpOptionList(schemaGlobalRows)}\n${builtInLine}`);
         }
         else {
             sections.push(builtInLine);
@@ -1417,11 +1428,19 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
-    const optionRows = sortLeafHelpOptionFields(fields.filter((field) => field.global !== true))
-        .map((field) => createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field)))
+    const localFields = fields.filter((field) => field.global !== true);
+    const toHelpRow = (field) => createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field));
+    const argumentRows = localFields
+        .filter((field) => field.positionalIndex !== undefined)
+        .map(toHelpRow);
+    const optionRows = sortLeafHelpOptionFields(localFields.filter((field) => field.positionalIndex === undefined))
+        .map(toHelpRow)
         .concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
+    if (argumentRows.length > 0) {
+        sections.push(`${text.section("Arguments:")}\n${formatHelpOptionList(argumentRows)}`);
+    }
     if (optionRows.length > 0) {
-        sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
+        sections.push(`${text.section("Options:")}\n${formatHelpOptionList(optionRows)}`);
     }
     const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
     if (builtInLine.length > 0) {
@@ -1429,10 +1448,10 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     }
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
-        sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
+        sections.push(`${text.section("Secrets (environment):")}\n${formatHelpOptionList(secretRows)}`);
     }
     if (command.examples.length > 0) {
-        sections.push(`${text.sectionHeader("Examples")}\n${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`);
+        sections.push(`${text.section("Examples:")}\n${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`);
     }
     const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
     const usageSuffix = positionalFields.length > 0
@@ -1599,7 +1618,12 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
         }
         for (const field of fields) {
             if (field.positionalIndex !== undefined) {
-                command.argument(formatPositionalToken(field));
+                // Positionals are declared optional so resolveParams stays the single owner of argument
+                // validation: Commander would otherwise report a missing positional in its own words
+                // before prompts, defaults, and presets have had a chance to supply the value.
+                command.argument(field.variadicPosition === true
+                    ? `[${field.displayPath}...]`
+                    : `[${field.displayPath}]`);
                 continue;
             }
             for (const option of createOption(field, globalLongOptionFlags)) {
@@ -2540,10 +2564,10 @@ function isHumanInLoopPending(result) {
         typeof result.message === "string" &&
         typeof result.enqueuedAt === "string");
 }
-function renderHumanInLoopPending(pending) {
+function renderHumanInLoopPending(pending, rootUsageName) {
     process.stdout.write(`✓ Queued for human approval (id: ${pending.approvalId})\n` +
         `  Message: ${pending.message}\n` +
-        `  Track:   toolcraft approvals show ${pending.approvalId}\n`);
+        `  Track:   ${rootUsageName} approvals show --approval-id ${pending.approvalId}\n`);
 }
 function renderApprovalDeclined(error) {
     const logger = createLogger();
@@ -2638,7 +2662,7 @@ function parseOptionFieldValue(field, value, errors) {
         return { ok: true, value: parsedValue };
     }
     catch (error) {
-        if (error instanceof UserError || error instanceof InvalidArgumentError) {
+        if (isUserError(error) || error instanceof InvalidArgumentError) {
             errors.push({
                 path: field.displayPath,
                 message: error.message
@@ -3150,7 +3174,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             }
             errors.push({
                 path: field.displayPath,
-                message: `Missing required parameter "${field.displayPath}".`
+                message: formatMissingParameterMessage(field)
             });
             continue;
         }
@@ -3193,7 +3217,7 @@ function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
+async function executeCommand(state, rootUsageName, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
     const logger = createLogger(outputEmitter);
     const optionValues = state.actionCommand.optsWithGlobals();
     const resolvedFlags = optionValues;
@@ -3334,7 +3358,7 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
                 writeRichHeader(`${state.command.name} (fixture)`);
             }
             if (isHumanInLoopPending(result)) {
-                renderHumanInLoopPending(result);
+                renderHumanInLoopPending(result, rootUsageName);
                 return;
             }
             const renderStatus = renderCLIResult(state.command, state.commandPath, result, output, primitives, outputFormats, outputEmitter === undefined
@@ -3571,7 +3595,7 @@ function renderHttpError(error, options) {
 async function handleRunError(error, options) {
     const logger = createLogger(options.outputEmitter);
     await withOutputFormat(options.output, async () => {
-        if (error instanceof UserError) {
+        if (isUserError(error)) {
             renderCliErrorPattern(options.userErrorPattern === "definition"
                 ? {
                     kind: "definition",
@@ -3870,12 +3894,9 @@ function getDefaultCommanderCommandName(command) {
 function configureCommanderSuggestionOutput(command) {
     command.exitOverride();
     command.configureOutput({
-        outputError: (message, write) => {
-            if (message.includes("unknown command") || message.includes("unknown option")) {
-                return;
-            }
-            write(message);
-        }
+        // Every Commander error throws through exitOverride and is rendered once by handleRunError
+        // in the design-system error pattern; writing it here as well double-reports one mistake.
+        outputError: () => { }
     });
     command.commands.forEach((child) => configureCommanderSuggestionOutput(child));
 }
@@ -3941,7 +3962,7 @@ export async function runCLI(roots, options = {}) {
         const execute = async (state) => {
             lastActionCommand = state.actionCommand;
             resolvedCommandPath = formatCliCommandPath(state.commandPath);
-            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, humanInLoop, options.env, options.fs, options.outputEmitter, controls.outputFormats, {
+            await executeCommand(state, rootUsageName, servicesWithBuiltIns, requirementOptions, runtimeFetch, humanInLoop, options.env, options.fs, options.outputEmitter, controls.outputFormats, {
                 input: options.promptInput,
                 output: options.promptOutput
             }, {

package/dist/composition.json

@@ -36,6 +36,11 @@
       "version": "0.0.1",
       "license": "MIT"
     },
+    {
+      "name": "@poe-code/user-error",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
     {
       "name": "auth-store",
       "version": "0.0.1",
@@ -108,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.136",
+      "version": "0.0.138",
       "license": "MIT"
     },
     {
@@ -118,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.136",
+      "version": "0.0.138",
       "license": "MIT"
     },
     {

package/dist/human-in-loop/approvals-commands.js

@@ -3,12 +3,14 @@ import { S } from "toolcraft-schema";
 import { hasOwnErrorCode } from "../error-codes.js";
 import { UserError, defineCommand, defineGroup } from "../index.js";
 import { ensureApprovalList } from "./approval-tasks.js";
+import { approvalStateMachine } from "./state-machine.js";
 import { runApproval } from "./runner.js";
 const approvalsGroupSymbol = Symbol("toolcraft.humanInLoop.approvalsBuiltIn");
 const listScope = ["cli", "mcp", "sdk"];
 const runScope = ["cli"];
+const approvalStateValues = approvalStateMachine.states;
 const listParams = S.Object({
-    state: S.Optional(S.String())
+    state: S.Optional(S.Array(S.Enum(approvalStateValues)))
 });
 const showParams = S.Object({
     approvalId: S.String()
@@ -51,18 +53,12 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             scope: listScope,
             params: showParams,
             handler: async ({ params, humanInLoop }) => {
-                try {
+                return withMissingApprovalError(params.approvalId, async () => {
                     const { tasks } = await ensureApprovalList(humanInLoop.runtimeOptions, {
                         create: false
                     });
                     return tasks.get(params.approvalId);
-                }
-                catch (error) {
-                    if (isMissingStateError(error)) {
-                        throw new TaskNotFoundError(`Task "approvals/${params.approvalId}" not found.`);
-                    }
-                    throw error;
-                }
+                });
             },
             render: {
                 rich: (result, primitives) => renderApprovalDetails(result, primitives),
@@ -76,7 +72,7 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             scope: runScope,
             params: runParams,
             handler: async ({ params, humanInLoop, root }) => {
-                return runApproval(params.approvalId, humanInLoop.runtimeOptions, root);
+                return withMissingApprovalError(params.approvalId, async () => runApproval(params.approvalId, humanInLoop.runtimeOptions, root));
             },
             render: {
                 rich: (result, primitives) => {
@@ -115,8 +111,7 @@ function isApprovalsBuiltIn(node) {
     return (node.kind === "group" &&
         node[approvalsGroupSymbol] === true);
 }
-async function loadApprovals(tasks, stateFilter) {
-    const states = splitStateFilter(stateFilter);
+async function loadApprovals(tasks, states = []) {
     if (states.length === 0) {
         return tasks.all();
     }
@@ -136,22 +131,6 @@ async function loadApprovals(tasks, stateFilter) {
     }
     return approvals;
 }
-function splitStateFilter(stateFilter) {
-    if (stateFilter === undefined) {
-        return [];
-    }
-    const seen = new Set();
-    const states = [];
-    for (const value of stateFilter.split(",")) {
-        const trimmed = value.trim();
-        if (trimmed.length === 0 || seen.has(trimmed)) {
-            continue;
-        }
-        seen.add(trimmed);
-        states.push(trimmed);
-    }
-    return states;
-}
 function renderApprovalList(result, { logger, renderTable, getTheme }) {
     if (result.length === 0) {
         logger.message("No approvals found.");
@@ -227,6 +206,17 @@ function stringifyValue(value) {
 function escapeMarkdownCell(value) {
     return value.replaceAll("|", "\\|");
 }
+async function withMissingApprovalError(approvalId, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof TaskNotFoundError || isMissingStateError(error)) {
+            throw new UserError(`Approval "${approvalId}" not found. Run approvals list to see queued approvals.`);
+        }
+        throw error;
+    }
+}
 function isMissingStateError(error) {
     return hasOwnErrorCode(error, "ENOENT");
 }

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import type { AnySchema, ObjectSchema, Static } from "toolcraft-schema";
 import type { LoggerOutput, RenderTableOptions, ThemePalette } from "toolcraft-design";
 import { ApprovalDeclinedError } from "./human-in-loop/types.js";
 import type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntime } from "./human-in-loop/types.js";
-import { ToolcraftBugError, UserError } from "./user-error.js";
+import { ToolcraftBugError, UserError, isUserError } from "./user-error.js";
 import type { RuntimeLogger } from "./runtime-logging.js";
 import type { StreamStatusEvent, ToolcraftStream } from "./stream.js";
 export { createManagedStream } from "./stream.js";
@@ -227,7 +227,8 @@ export declare function hasMcpProxyConfig(group: Group<any>): boolean;
 export { S, toJsonSchema } from "./schema.js";
 export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
 export type { HttpErrorRequest, HttpErrorResponse } from "./http-errors.js";
-export { ApprovalDeclinedError, ToolcraftBugError, UserError };
+export { ApprovalDeclinedError, ToolcraftBugError, UserError, isUserError };
+export { suggest } from "./suggest.js";
 export { createRuntimeLogger, isLogLevel, shouldEmitDiagnostic } from "./runtime-logging.js";
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";
 export type { PackageMetadata } from "./package-metadata.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { ApprovalDeclinedError } from "./human-in-loop/types.js";
 import { mergeHumanInLoopFromGroup, validateHumanInLoopOnDefine } from "./human-in-loop/config.js";
-import { ToolcraftBugError, UserError } from "./user-error.js";
+import { ToolcraftBugError, UserError, isUserError } from "./user-error.js";
 import { suggest } from "./suggest.js";
 export { createManagedStream } from "./stream.js";
 const commandConfigSymbol = Symbol("toolcraft.command.config");
@@ -500,6 +500,7 @@ export function hasMcpProxyConfig(group) {
 }
 export { S, toJsonSchema } from "./schema.js";
 export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
-export { ApprovalDeclinedError, ToolcraftBugError, UserError };
+export { ApprovalDeclinedError, ToolcraftBugError, UserError, isUserError };
+export { suggest } from "./suggest.js";
 export { createRuntimeLogger, isLogLevel, shouldEmitDiagnostic } from "./runtime-logging.js";
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";

package/dist/renderer.js

@@ -142,6 +142,9 @@ function compactUrl(value) {
         return value;
     }
 }
+function stackedList(value) {
+    return value.map((entry) => displayScalar(entry)).join("\n") || "—";
+}
 function displayRowValue(value) {
     return isUrl(value) ? compactUrl(value) : displayScalar(value);
 }
@@ -176,7 +179,7 @@ function renderObjectCard(result, primitives, title) {
     const arrayObjectSections = directArrayObjectSections(result);
     const listRows = Object.entries(result)
         .filter(([, value]) => Array.isArray(value) && !isNonEmptyArrayOfObjects(value))
-        .map(([key, value]) => ({ label: humanizeKey(key), value: displayScalar(value) }));
+        .map(([key, value]) => ({ label: humanizeKey(key), value: stackedList(value) }));
     return renderDetailCard({
         theme: primitives.getTheme(),
         title,

package/dist/user-error.d.ts

@@ -1,6 +1,14 @@
 export declare class UserError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (for example `@poe-code/user-error`, thrown by packages that do
+ * not depend on toolcraft) is still rendered as guidance where `instanceof`
+ * would fail - while a genuine `UserError` stays one even if its name was
+ * overwritten.
+ */
+export declare function isUserError(error: unknown): error is Error;
 export declare class ToolcraftBugError extends Error {
     constructor(message: string);
 }

package/dist/user-error.js

@@ -4,6 +4,16 @@ export class UserError extends Error {
         this.name = "UserError";
     }
 }
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (for example `@poe-code/user-error`, thrown by packages that do
+ * not depend on toolcraft) is still rendered as guidance where `instanceof`
+ * would fail - while a genuine `UserError` stays one even if its name was
+ * overwritten.
+ */
+export function isUserError(error) {
+    return error instanceof UserError || (error instanceof Error && error.name === "UserError");
+}
 export class ToolcraftBugError extends Error {
     constructor(message) {
         super(message);

package/node_modules/@poe-code/agent-defs/README.md

@@ -4,7 +4,8 @@ Shared catalog of supported coding-agent definitions.
 
 This package owns the declarative agent metadata used by CLI, SDK, spawn,
 configuration, and UI surfaces: stable ids, labels, aliases, config paths,
-binary names, API-shape support, OTEL capture wiring, and brand colors.
+binary names, API-shape support, OTEL capture wiring, brand colors, and the
+capability matrix that says which commands accept each agent.
 
 ## Usage
 
@@ -24,6 +25,18 @@ const codex = allAgents.find((agent) => agent.id === "codex");
 - `formatAgentSpecifier(specifier)`: formats an agent specifier.
 - `normalizeAgentId(input)`: normalizes the agent part through the registry.
 - Agent definition exports such as `codexAgent`, `claudeCodeAgent`, `geminiCliAgent`, and `piAgent`.
+- `listAgentsWithCapability(capability, options?)`: ids supporting a capability, optionally including aliases.
+- `agentSupportsCapability(input, capability)`: resolves aliases, then checks the matrix.
+- `formatAgentCapabilityError({ agent, capability })`: the shared message for a rejected agent argument.
+
+## Capability Matrix
+
+Each `AgentDefinition` declares its `capabilities` (`spawn`, `configure`,
+`install`, `test`, `skill`, `mcp`). This is the single published source for every
+command's allow-list, so `spawn`/`configure`/`install`/`test`/`skill` cannot
+drift apart. `src/cli/commands/agent-capability-matrix.test.ts` pins each
+capability to the registry that implements it, and fails if a registry gains or
+loses an agent without the matrix being updated.
 
 ## Config Options
 

package/node_modules/@poe-code/agent-defs/dist/agents/claude-code.js

@@ -12,6 +12,7 @@ export const claudeCodeAgent = {
         }
     },
     configPath: "~/.claude.json",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#C15F3C",

package/node_modules/@poe-code/agent-defs/dist/agents/claude-desktop.js

@@ -9,6 +9,7 @@ export const claudeDesktopAgent = {
         linux: "~/.config/Claude/claude_desktop_config.json",
         win32: "~/AppData/Roaming/Claude/claude_desktop_config.json"
     },
+    capabilities: ["mcp"],
     branding: {
         colors: {
             dark: "#D97757",

package/node_modules/@poe-code/agent-defs/dist/agents/codex.js

@@ -16,6 +16,7 @@ export const codexAgent = {
         ]
     },
     configPath: "~/.codex/config.toml",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#D5D9DF",

package/node_modules/@poe-code/agent-defs/dist/agents/cursor.js

@@ -6,6 +6,7 @@ export const cursorAgent = {
     summary: "Cursor's CLI coding agent.",
     binaryName: "cursor-agent",
     configPath: "~/.cursor/mcp.json",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#FFFFFF",

package/node_modules/@poe-code/agent-defs/dist/agents/gemini-cli.js

@@ -7,6 +7,7 @@ export const geminiCliAgent = {
     binaryName: "gemini",
     configPath: "~/.gemini/settings.json",
     apiShapes: ["google-generations"],
+    capabilities: ["spawn", "configure", "install", "test", "skill"],
     branding: {
         colors: {
             dark: "#8AB4F8",

package/node_modules/@poe-code/agent-defs/dist/agents/goose.js

@@ -7,6 +7,7 @@ export const gooseAgent = {
     apiShapes: ["openai-chat-completions"],
     otelCapture: {},
     configPath: "~/.config/goose/config.yaml",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#FF6B35",

package/node_modules/@poe-code/agent-defs/dist/agents/kimi.js

@@ -7,6 +7,7 @@ export const kimiAgent = {
     binaryName: "kimi",
     apiShapes: ["openai-chat-completions"],
     configPath: "~/.kimi/mcp.json",
+    capabilities: ["spawn", "configure", "install", "test", "mcp"],
     branding: {
         colors: {
             dark: "#7B68EE",

package/node_modules/@poe-code/agent-defs/dist/agents/opencode.js

@@ -11,6 +11,7 @@ export const openCodeAgent = {
         }
     },
     configPath: "~/.config/opencode/opencode.json",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#4A4F55",

package/node_modules/@poe-code/agent-defs/dist/agents/pi.js

@@ -5,6 +5,7 @@ export const piAgent = {
     label: "Pi",
     summary: "Minimal AI coding agent for the terminal.",
     binaryName: "pi",
+    capabilities: ["spawn"],
     branding: {
         colors: {
             dark: "#F2F2F2",

package/node_modules/@poe-code/agent-defs/dist/agents/poe-agent.js

@@ -5,6 +5,7 @@ export const poeAgentAgent = {
     summary: "Run one-shot prompts with the built-in Poe agent runtime.",
     apiShapes: ["openai-responses", "openai-chat-completions"],
     configPath: "~/.poe-code/config.json",
+    capabilities: ["configure"],
     branding: {
         colors: {
             dark: "#A465F7",

package/node_modules/@poe-code/agent-defs/dist/capabilities.d.ts

@@ -0,0 +1,14 @@
+import type { AgentCapability } from "./types.js";
+export declare function listAgentsWithCapability(capability: AgentCapability, options?: {
+    includeAliases?: boolean;
+}): readonly string[];
+export declare function agentSupportsCapability(input: string, capability: AgentCapability): boolean;
+/**
+ * The single message for every agent argument that misses. It distinguishes a
+ * typo (unknown id, plus a did-you-mean) from a real capability gap ("pi
+ * supports: spawn"), and always names the agents the command does accept.
+ */
+export declare function formatAgentCapabilityError(input: {
+    agent: string;
+    capability: AgentCapability;
+}): string;