argsbarg 7.1.0 → 7.1.2

package/src/config/validate.ts

@@ -72,15 +72,360 @@ function formatInstancePath(instanceLocation: string): string {
   return instanceLocation;
 }
 
-function formatValidationErrors(errors: { instanceLocation: string; error: string }[]): string[] {
-  return errors.map(({ instanceLocation, error }) => {
-    const path = formatInstancePath(instanceLocation);
-    return `${path}: ${error}`;
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** cfworker keywords that only wrap a deeper, more specific failure — dropped when one survives underneath. */
+const WRAPPER_KEYWORDS = new Set([
+  "$ref",
+  "$recursiveRef",
+  "properties",
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
+/** Raw cfworker validation error (the subset of `OutputUnit` this module reads). */
+interface RawError {
+  instanceLocation: string;
+  keyword: string;
+  keywordLocation: string;
+  error: string;
+}
+
+/** Walks a `keywordLocation` JSON Pointer against `root`, following `$ref` segments through `resolveJsonPointer`. */
+function schemaAtPointer(root: JsonSchema, keywordLocation: string): JsonSchema | unknown[] | undefined {
+  if (!keywordLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = keywordLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (segment === "$ref") {
+      if (typeof current !== "object" || current === null || Array.isArray(current)) {
+        return undefined;
+      }
+      const ref = (current as JsonSchema).$ref;
+      if (typeof ref !== "string") {
+        return undefined;
+      }
+      current = resolveJsonPointer(root, ref);
+      continue;
+    }
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current as JsonSchema | unknown[] | undefined;
+}
+
+/** Walks an `instanceLocation` JSON Pointer against the validated payload. */
+function instanceAtPointer(data: unknown, instanceLocation: string): unknown {
+  if (!instanceLocation.startsWith("#")) {
+    return undefined;
+  }
+  const segments = instanceLocation
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = data;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/** The parent JSON Pointer of `location` (its last `/segment` removed), or `undefined` at the root. */
+function parentPointer(location: string): string | undefined {
+  const idx = location.lastIndexOf("/");
+  if (idx < 0) {
+    return undefined;
+  }
+  return location.slice(0, idx) || "#";
+}
+
+/** A discriminator property common to every branch, with each branch's set of accepted string values. */
+interface UnionDiscriminator {
+  prop: string;
+  valuesByBranch: string[][];
+}
+
+/**
+ * Finds a property present in every branch as a string `const` or all-string `enum`, whose value sets are
+ * pairwise disjoint across branches. Prefers `kind`, then `type`, then the alphabetically first eligible name.
+ * Each branch is resolved through a bare `$ref` first — a schema built with a `definitions`/`$defs` map
+ * (e.g. ts-json-schema-generator output) typically writes `anyOf: [{ $ref: "#/definitions/A" }, …]` rather
+ * than inlining each branch, so without this every branch here would otherwise look property-less.
+ */
+function unionDiscriminator(branches: unknown[], root: JsonSchema): UnionDiscriminator | undefined {
+  const resolvedBranches = branches.map((b) => {
+    if (typeof b !== "object" || b === null || Array.isArray(b)) {
+      return b;
+    }
+    const ref = (b as JsonSchema).$ref;
+    if (typeof ref !== "string") {
+      return b;
+    }
+    return resolveJsonPointer(root, ref) ?? b;
   });
+  const objectBranches = resolvedBranches.filter(
+    (b): b is JsonSchema => typeof b === "object" && b !== null && !Array.isArray(b),
+  );
+  if (objectBranches.length === 0 || objectBranches.length !== resolvedBranches.length) {
+    return undefined;
+  }
+
+  const branchValuesFor = (prop: string): string[][] | undefined => {
+    const perBranch: string[][] = [];
+    for (const branch of objectBranches) {
+      const props = branch.properties;
+      const propSchema =
+        typeof props === "object" && props !== null && !Array.isArray(props)
+          ? (props as Record<string, JsonSchema>)[prop]
+          : undefined;
+      if (!propSchema || typeof propSchema !== "object") {
+        return undefined;
+      }
+      let values: string[] | undefined;
+      if (typeof propSchema.const === "string") {
+        values = [propSchema.const];
+      } else if (Array.isArray(propSchema.enum) && propSchema.enum.every((v) => typeof v === "string")) {
+        values = propSchema.enum as string[];
+      }
+      if (!values || values.length === 0) {
+        return undefined;
+      }
+      perBranch.push(values);
+    }
+    const seen = new Set<string>();
+    for (const values of perBranch) {
+      for (const v of values) {
+        if (seen.has(v)) return undefined;
+        seen.add(v);
+      }
+    }
+    return perBranch;
+  };
+
+  const candidateProps = new Set<string>();
+  for (const branch of objectBranches) {
+    const props = branch.properties;
+    if (typeof props === "object" && props !== null && !Array.isArray(props)) {
+      for (const key of Object.keys(props)) candidateProps.add(key);
+    }
+  }
+
+  const eligible: string[] = [];
+  for (const prop of candidateProps) {
+    if (branchValuesFor(prop)) eligible.push(prop);
+  }
+  if (eligible.length === 0) {
+    return undefined;
+  }
+  const prop = eligible.includes("kind") ? "kind" : eligible.includes("type") ? "type" : [...eligible].sort()[0]!;
+  return { prop, valuesByBranch: branchValuesFor(prop)! };
 }
 
-function decodeJsonPointerSegment(segment: string): string {
-  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+/** Sorted, comma-joined, unquoted list of values for error messages. */
+function joinSorted(values: Iterable<string>): string {
+  return [...new Set(values)].sort().join(", ");
+}
+
+/** Rewrites a single surviving cfworker error message into a terser, more actionable form. */
+function rewriteErrorMessage(err: RawError, root: JsonSchema): string {
+  const additionalPropsMatch = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+  if (additionalPropsMatch) {
+    const name = additionalPropsMatch[1]!;
+    const parentLoc = parentPointer(err.keywordLocation);
+    const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+    const props =
+      parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+        ? (parentSchema as JsonSchema).properties
+        : undefined;
+    const keys = props && typeof props === "object" && !Array.isArray(props) ? Object.keys(props as JsonSchema) : [];
+    const allowed = keys.sort().slice(0, 20).join(", ");
+    return `unknown property "${name}"${allowed ? ` (allowed: ${allowed})` : ""}`;
+  }
+
+  const requiredMatch = /^Instance does not have required property "(.+)"\.$/.exec(err.error);
+  if (requiredMatch) {
+    return `missing required property "${requiredMatch[1]}"`;
+  }
+
+  const enumMatch = /^Instance does not match any of (\[.*\])\.$/.exec(err.error);
+  if (enumMatch) {
+    try {
+      const values = JSON.parse(enumMatch[1]!) as unknown[];
+      return `must be one of: ${values.map((v) => String(v)).join(", ")}`;
+    } catch {
+      // fall through to the raw message
+    }
+  }
+
+  const typeMatch = /^Instance type "(.+)" is invalid\. Expected "(.+)"\.$/.exec(err.error);
+  if (typeMatch) {
+    return `must be ${typeMatch[2]} (got ${typeMatch[1]})`;
+  }
+
+  return err.error;
+}
+
+/** Maximum number of narrowed errors reported before collapsing the remainder into a count. */
+const MAX_NARROWED_ERRORS = 10;
+
+/**
+ * Post-processes raw cfworker errors: for each `anyOf`/`oneOf` failure with a discriminated union, keeps only
+ * the branch matching the instance's discriminator value (or reports one synthetic error naming what a valid
+ * discriminator looks like); drops wrapper keywords once a more specific error survives under them; drops the
+ * `additionalProperties`+`false` pair cfworker emits even for properties that are legitimately declared; then
+ * rewrites the remaining messages into terser, more actionable text.
+ */
+function narrowUnionErrors(errors: RawError[], root: JsonSchema, data: unknown): string[] {
+  const dropped = new Set<RawError>();
+  const synthetic: Array<{ instanceLocation: string; message: string }> = [];
+  // Locations of anyOf/oneOf errors resolved into a synthetic message rather than a kept branch — an ancestor
+  // wrapper (e.g. the `$ref` pointing at that anyOf, for the same instance) counts as "resolved deeper" too.
+  const syntheticReplacedLocations: Array<{ instanceLocation: string; keywordLocation: string }> = [];
+
+  // Stage 1: discriminated-union narrowing.
+  for (const err of errors) {
+    if (err.keyword !== "anyOf" && err.keyword !== "oneOf") continue;
+    const branches = schemaAtPointer(root, err.keywordLocation);
+    if (!Array.isArray(branches)) continue;
+    const discriminator = unionDiscriminator(branches, root);
+    if (!discriminator) continue;
+
+    // Array items reuse one schema, so keywordLocation repeats verbatim across indices — scope by
+    // instanceLocation too, or narrowing one item would wrongly swallow every other item's errors.
+    const under = errors.filter(
+      (e) =>
+        e !== err &&
+        e.keywordLocation.startsWith(`${err.keywordLocation}/`) &&
+        (e.instanceLocation === err.instanceLocation || e.instanceLocation.startsWith(`${err.instanceLocation}/`)),
+    );
+    const validValues = discriminator.valuesByBranch.flat();
+    const instance = instanceAtPointer(data, err.instanceLocation);
+
+    if (typeof instance !== "object" || instance === null || Array.isArray(instance)) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `expected an object with "${discriminator.prop}" (one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const propValue = (instance as Record<string, unknown>)[discriminator.prop];
+    if (propValue === undefined) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: err.instanceLocation,
+        message: `missing "${discriminator.prop}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const branchIndex = discriminator.valuesByBranch.findIndex(
+      (values) => typeof propValue === "string" && values.includes(propValue),
+    );
+    if (branchIndex < 0) {
+      dropped.add(err);
+      for (const e of under) dropped.add(e);
+      syntheticReplacedLocations.push({ instanceLocation: err.instanceLocation, keywordLocation: err.keywordLocation });
+      synthetic.push({
+        instanceLocation: `${err.instanceLocation}/${discriminator.prop}`,
+        message: `unknown ${discriminator.prop} "${String(propValue)}" (expected one of: ${joinSorted(validValues)})`,
+      });
+      continue;
+    }
+
+    const keepPrefix = `${err.keywordLocation}/${branchIndex}`;
+    dropped.add(err);
+    for (const e of under) {
+      if (e.keywordLocation === keepPrefix || e.keywordLocation.startsWith(`${keepPrefix}/`)) continue;
+      dropped.add(e);
+    }
+  }
+
+  // Stage 2: drop wrapper keywords once a more specific error survives under them, or once a descendant anyOf/oneOf
+  // was resolved into a synthetic message instead (which leaves no raw descendant error to detect otherwise).
+  const survivingAfterStage1 = errors.filter((e) => !dropped.has(e));
+  const nestsUnder = (candidateInstance: string, wrapperInstance: string) =>
+    candidateInstance === wrapperInstance || candidateInstance.startsWith(`${wrapperInstance}/`);
+  for (const err of survivingAfterStage1) {
+    if (!WRAPPER_KEYWORDS.has(err.keyword)) continue;
+    const prefix = `${err.keywordLocation}/`;
+    // Array items reuse one schema, so a wrapper's keywordLocation repeats across indices — scope by
+    // instanceLocation too, or one index's surviving error would mask another index's real problem.
+    const hasDeeper = survivingAfterStage1.some(
+      (other) =>
+        other !== err &&
+        !dropped.has(other) &&
+        other.keywordLocation.startsWith(prefix) &&
+        nestsUnder(other.instanceLocation, err.instanceLocation),
+    );
+    const hasSyntheticDeeper = syntheticReplacedLocations.some(
+      (s) => s.keywordLocation.startsWith(prefix) && nestsUnder(s.instanceLocation, err.instanceLocation),
+    );
+    if (hasDeeper || hasSyntheticDeeper) dropped.add(err);
+  }
+
+  // Stage 3: drop the additionalProperties+false pair cfworker emits for properties actually in `properties`.
+  const additionalPropsInstanceLocations = new Set(
+    errors.filter((e) => e.keyword === "additionalProperties").map((e) => e.instanceLocation),
+  );
+  for (const err of errors) {
+    if (dropped.has(err)) continue;
+    if (err.keyword === "additionalProperties") {
+      const match = /^Property "(.+)" does not match additional properties schema\.$/.exec(err.error);
+      const parentLoc = parentPointer(err.keywordLocation);
+      const parentSchema = parentLoc ? schemaAtPointer(root, parentLoc) : undefined;
+      const props =
+        match && parentSchema && typeof parentSchema === "object" && !Array.isArray(parentSchema)
+          ? (parentSchema as JsonSchema).properties
+          : undefined;
+      const declared =
+        match && props && typeof props === "object" && !Array.isArray(props)
+          ? Object.hasOwn(props as JsonSchema, match[1]!)
+          : false;
+      if (declared) dropped.add(err);
+      continue;
+    }
+    if (err.keyword === "false") {
+      const parent = parentPointer(err.instanceLocation);
+      if (parent !== undefined && additionalPropsInstanceLocations.has(parent)) {
+        dropped.add(err);
+      }
+    }
+  }
+
+  // Stage 4: rewrite surviving messages, merge in synthetic ones, cap the total.
+  const kept = errors
+    .filter((e) => !dropped.has(e))
+    .map((e) => `${formatInstancePath(e.instanceLocation)}: ${rewriteErrorMessage(e, root)}`);
+  const syntheticFormatted = synthetic.map((s) => `${formatInstancePath(s.instanceLocation)}: ${s.message}`);
+  const all = [...syntheticFormatted, ...kept];
+  if (all.length <= MAX_NARROWED_ERRORS) {
+    return all;
+  }
+  return [...all.slice(0, MAX_NARROWED_ERRORS), `…and ${all.length - MAX_NARROWED_ERRORS} more errors`];
 }
 
 /** Map a schema `$schema` URI to the @cfworker/json-schema draft (defaults to Draft-07). */
@@ -170,7 +515,7 @@ function validateInstance(
   if (result.valid) {
     return { valid: true, errors: [] };
   }
-  return { valid: false, errors: formatValidationErrors(result.errors) };
+  return { valid: false, errors: narrowUnionErrors(result.errors as RawError[], root, payload) };
 }
 
 function validateAgainstSchema(data: unknown, rootSchema: JsonSchema, partial: boolean): ValidateResult {

package/src/core/document-leaf.test.ts

@@ -180,6 +180,59 @@ describe("kind: document leaf", () => {
     expect(result.kind).toBe("error");
     expect(result.errorMsg).toContain("Document input must be a JSON or YAML object");
   });
+
+  /** Tests that a discriminated-union inputSchema surfaces only the matching branch's narrowed error. */
+  test("invoke surfaces a narrowed discriminated-union error end to end", async () => {
+    const stepSchema = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: { steps: { type: "array", items: { $ref: "#/definitions/Step" } } },
+      required: ["steps"],
+      additionalProperties: false,
+      definitions: {
+        Step: {
+          anyOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "alpha" }, title: { type: "string" } },
+              required: ["kind", "title"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { enum: ["beta", "bravo"] }, count: { type: "number" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { const: "gamma" }, flag: { type: "boolean" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+    } as const;
+    const program = {
+      key: "steptest",
+      version: "1.0.0",
+      description: "steps test",
+      commands: [
+        {
+          key: "run",
+          description: "run",
+          kind: "document",
+          inputSchema: stepSchema,
+          handler: (ctx) => ctx.inputsAs(),
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["run", JSON.stringify({ steps: [{ kind: "alfa" }] })], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toBe('steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)');
+  });
 });
 
 /** Tests for parseDocumentText helper function. */

package/src/core/types.ts

@@ -187,6 +187,13 @@ export interface CliMcpBundleConfig {
 export interface CliMcpServerConfig {
   /** When `true`, enables the `mcp` built-in and MCP stdio server. */
   enabled: boolean;
+  /**
+   * Returned as `initialize.result.instructions`. Claude Code adds it to the system prompt of every
+   * session; Cursor writes it to `mcps/<server>/INSTRUCTIONS.md`. Both cases cost context whether or
+   * not the agent ends up using this server, so keep it to a one- or two-line pointer (e.g. when to
+   * reach for this tool, and to read the accompanying skill first) rather than usage documentation.
+   */
+  instructions?: string;
   /** MCP error response defaults. */
   errors?: CliMcpServerErrorsConfig;
   /** Observe-only hooks for JSON-RPC messages. */
@@ -212,6 +219,25 @@ export interface CliMcpServerConfig {
   resources?: CliMcpResource[];
   /** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
   bundle?: CliMcpBundleConfig;
+  /** Overrides the default startup size warnings (see {@link CliMcpSizeLimits}). */
+  sizeLimits?: CliMcpSizeLimits;
+}
+
+/**
+ * Size limits for one MCP tool's `description` and pretty-printed definition, and for `instructions`.
+ * Set a field to `false` to disable that check. Defaults come from two client behaviors observed in the
+ * wild, not from the MCP spec itself, so they may need retuning as those clients change:
+ * Claude Code truncates a tool's `description` past `descriptionChars`; Cursor syncs each tool's full
+ * definition (`{name, description, inputSchema, outputSchema}`, pretty-printed) to a file under
+ * `mcps/<server>/tools/<tool>.json` and its agent reads that file in chunks of at most `definitionBytes`
+ * bytes or `definitionLines` lines, whichever comes first — a tool at or beyond either limit is read
+ * incompletely on the first pass.
+ */
+export interface CliMcpSizeLimits {
+  definitionBytes?: number | false;
+  definitionLines?: number | false;
+  descriptionChars?: number | false;
+  instructionsChars?: number | false;
 }
 
 /** JSON Schema for structured error responses (OpenAPI + HTTP/MCP error bodies). */
@@ -334,6 +360,13 @@ export interface CliMcpToolConfig {
    * Default: auto-generated from command path and description.
    */
   description?: string;
+  /**
+   * Overrides the leaf's `notes` in the MCP description only — CLI help always shows `notes` unchanged.
+   * `false` omits notes from the MCP description entirely; a string replaces them. Omit to use `notes` as
+   * given. Useful when a note only makes sense with `--help` in front of it (a CLI-only workflow tip), or
+   * when the full CLI notes would push a definition past a size limit (see {@link CliMcpSizeLimits}).
+   */
+  notes?: string | false;
 }
 
 /**

package/src/core/validate.ts

@@ -162,6 +162,10 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("mcpServer requires enabled: true; omit mcpServer to disable MCP");
   }
 
+  if (program.mcpServer?.instructions !== undefined && program.mcpServer.instructions.trim().length === 0) {
+    throw new CliSchemaValidationError("mcpServer.instructions must not be empty; omit it instead");
+  }
+
   if (program.httpServer !== undefined && program.httpServer.enabled !== true) {
     throw new CliSchemaValidationError("httpServer requires enabled: true; omit httpServer to disable HTTP API");
   }

package/src/docs/docs.test.ts

@@ -280,6 +280,13 @@ test("generateMcpGuide includes schema URI and .agents install", () => {
   expect(guide).not.toContain("OpenAI Codex");
 });
 
+test("generateMcpGuide includes a Tool sizes table", () => {
+  const guide = generateMcpGuide(docsFixture(true));
+  expect(guide).toContain("## Tool sizes");
+  expect(guide).toContain("| Tool | Description (chars) | Definition (bytes) | Definition (lines) | Status |");
+  expect(guide).toMatch(/\| `run` \| \d+ \| \d+ \| \d+ \| ok \|/);
+});
+
 test("docs --save writes topic file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);

package/src/docs/mcp-guide.ts

@@ -3,7 +3,15 @@ import { displayAppConfigPath } from "../config/file.ts";
 import { expectedMcpEntry } from "../configure/artifacts/mcp-config.ts";
 import { resolveClaudeDesktopMcpPath, userHome } from "../configure/artifacts/paths.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
-import { collectMcpTools, leafWireOptions, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
+import {
+  collectMcpTools,
+  DEFAULT_MCP_SIZE_LIMITS,
+  leafWireOptions,
+  type McpToolDef,
+  mcpServerId,
+  mcpSizeReport,
+  resolveMcpSchemaUri,
+} from "../mcp/tools.ts";
 import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
 import { docsEnabled, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
@@ -173,6 +181,9 @@ export function generateMcpGuide(root: CliProgram): string {
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
     `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs cli-schema\` |`,
   );
+  if (mcp.instructions) {
+    lines.push(`| \`initialize.instructions\` | ${mcp.instructions} |`);
+  }
   if (docsEnabled(root)) {
     const docs = resolveDocsConfig(root);
     for (const key of docsUserTopicKeys(docs)) {
@@ -191,6 +202,37 @@ export function generateMcpGuide(root: CliProgram): string {
     lines.push("");
   }
 
+  const sizeReport = mcpSizeReport(root);
+  if (sizeReport.tools.length > 0) {
+    const limits = { ...DEFAULT_MCP_SIZE_LIMITS, ...root.mcpServer?.sizeLimits };
+    lines.push(
+      "## Tool sizes",
+      "",
+      `Clients read tool definitions with their own limits — a definition or description past those is truncated ` +
+        `or read incompletely. Default limits here: description ${limits.descriptionChars === false ? "unchecked" : `${limits.descriptionChars.toLocaleString()} chars`}, ` +
+        `definition ${limits.definitionBytes === false ? "unchecked" : `${limits.definitionBytes.toLocaleString()} bytes`} / ` +
+        `${limits.definitionLines === false ? "unchecked" : `${limits.definitionLines.toLocaleString()} lines`} (override with \`mcpServer.sizeLimits\`).`,
+      "",
+      "| Tool | Description (chars) | Definition (bytes) | Definition (lines) | Status |",
+      "| --- | --- | --- | --- | --- |",
+    );
+    for (const t of sizeReport.tools) {
+      const over: string[] = [];
+      if (limits.descriptionChars !== false && t.descriptionChars > limits.descriptionChars) over.push("description");
+      if (
+        (limits.definitionBytes !== false && t.definitionBytes > limits.definitionBytes) ||
+        (limits.definitionLines !== false && t.definitionLines > limits.definitionLines)
+      ) {
+        over.push("definition");
+      }
+      const status = over.length === 0 ? "ok" : `over: ${over.join(", ")}`;
+      lines.push(
+        `| \`${t.name}\` | ${t.descriptionChars.toLocaleString()} | ${t.definitionBytes.toLocaleString()} | ${t.definitionLines.toLocaleString()} | ${status} |`,
+      );
+    }
+    lines.push("");
+  }
+
   lines.push(
     "## Tool arguments",
     "",

package/src/headless/tool-call.test.ts

@@ -0,0 +1,32 @@
+/* Unit tests for shared headless error text (MCP and HTTP). */
+
+import { describe, expect, test } from "bun:test";
+import { type HeadlessToolCallFailure, headlessFailureMcpMessage, headlessFailureToHttpResponse } from "./tool-call.ts";
+
+/** Builds a failed headless result with the given error message. */
+function invokeFailure(
+  /** Full error text from the leaf. */
+  message: string,
+): HeadlessToolCallFailure {
+  return {
+    exitCode: 1,
+    kind: "invoke",
+    message,
+    ok: false,
+    stderr: "",
+    stdout: "",
+  };
+}
+
+describe("headless error text", () => {
+  const multiline =
+    'cannot copy tab "Spec" losslessly (1 smart chip(s): "Ada"). Use force: true.\n' +
+    '  • node h.x: contains 1 smart chip(s) ("Ada")\n\n' +
+    "Google Docs REST API has no native tab duplication endpoint.";
+
+  test("MCP and HTTP both keep the full multi-line error", async () => {
+    expect(headlessFailureMcpMessage(invokeFailure(multiline))).toBe(multiline);
+    const body = (await headlessFailureToHttpResponse(invokeFailure(multiline)).json()) as { error: string };
+    expect(body.error).toBe(multiline);
+  });
+});

package/src/headless/tool-call.ts

@@ -6,7 +6,7 @@ import { bootstrapAppConfig } from "../config/bootstrap.ts";
 import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
 import type { CliInvocation, CliProgram, InvokeFailureKind } from "../core/types.ts";
 import { failureKindHttpStatus } from "../hooks/run.ts";
-import { apiErrorResponse, apiSuccessResponse, firstErrorLine } from "../http/result.ts";
+import { apiErrorResponse, apiSuccessResponse, stripAnsi } from "../http/result.ts";
 import { type HttpRouteDef, httpRequestToArgv } from "../http/routes.ts";
 import { obscureUnexpectedClientMessage } from "../log/emitter.ts";
 import { buildToolCallSuccessFromResponse } from "../mcp/result.ts";
@@ -188,11 +188,7 @@ export function headlessSuccessToHttpResponse(
 /** Maps a headless failure result to a JSON HTTP error Response. */
 export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure, obscureUnexpected = false): Response {
   const status = resolveHttpErrorStatus(result);
-  let message = firstErrorLine(result.message);
-  if (obscureUnexpected && result.failureKind === "unexpected") {
-    message = obscureUnexpectedClientMessage();
-  }
-  return apiErrorResponse(status, { error: message });
+  return apiErrorResponse(status, { error: formatHeadlessError(result, obscureUnexpected) });
 }
 
 function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
@@ -212,11 +208,26 @@ function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
 }
 
 /** Maps invoke failure kind to MCP tools/call error text (respects obscureUnexpected). */
-export function headlessFailureMcpMessage(result: HeadlessToolCallFailure, obscureUnexpected = false): string {
+export function headlessFailureMcpMessage(
+  /** Failed headless tool invocation. */
+  result: HeadlessToolCallFailure,
+  /** When true, unexpected failures return a generic client message. */
+  obscureUnexpected = false,
+): string {
+  return formatHeadlessError(result, obscureUnexpected);
+}
+
+/** Formats a headless failure for MCP text content and HTTP JSON `error` (full message, ANSI stripped). */
+function formatHeadlessError(
+  /** Failed headless tool invocation. */
+  result: HeadlessToolCallFailure,
+  /** When true, unexpected failures return a generic client message. */
+  obscureUnexpected: boolean,
+): string {
   if (obscureUnexpected && result.failureKind === "unexpected") {
     return obscureUnexpectedClientMessage();
   }
-  return firstErrorLine(result.message);
+  return stripAnsi(result.message).trim();
 }
 
 /** Missing-config lookup failures as MCP/HTTP pre-invoke errors. */