@2kw/ai 6.3.0 → 6.4.0-dev.10

package/dist/agent-config/schema.d.ts

@@ -221,6 +221,25 @@ export declare const agentSchema: {
                 };
             };
         };
+        readonly bashTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.bash";
+                };
+                readonly approval: {
+                    readonly enum: readonly ["sandbox", "pause"];
+                };
+                readonly outputs: {
+                    readonly enum: readonly ["immediate", "held"];
+                };
+                readonly annotations: {
+                    readonly $ref: "#/$defs/annotations";
+                };
+            };
+        };
         readonly functionTool: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -335,6 +354,18 @@ export declare const agentSchema: {
                 readonly then: {
                     readonly $ref: "#/$defs/skillTool";
                 };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/bashTool";
+                };
             }, {
                 readonly if: {
                     required: string[];

package/dist/agent-config/schema.js

@@ -25,6 +25,8 @@ export const NON_AUTHORABLE_TOOL_TYPES = {
     "backbone.skills_apply": "it is added at run time for callers allowed to author skills",
     // #1241: injected while the conversation's outputs are held; an authored copy is dropped.
     "backbone.deliver": "it is added at run time while sandbox outputs are held",
+    // #1244: injected wherever backbone.bash is advertised; an authored copy is dropped.
+    "backbone.view_image": "it is added at run time wherever the sandboxed shell is",
     web_search: "it has no executor and is skipped",
 };
 const BUILTIN_TYPES = [
@@ -33,6 +35,7 @@ const BUILTIN_TYPES = [
     "backbone.document_convert",
     "backbone.todo",
     "backbone.skill",
+    "backbone.bash",
     "function",
 ];
 const typeIs = (t) => ({ required: ["type"], properties: { type: { const: t } } });
@@ -159,6 +162,19 @@ export const agentSchema = {
                 skills: { type: "array", minItems: 1, maxItems: 20, uniqueItems: true, items: { type: "string", pattern: SKILL_REF } },
             },
         },
+        // The envelope BashToolEntryValidator accepts: no name, no requiresConfirmation, and none of
+        // the egress of the withdrawn per-agent network design (#925).
+        bashTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: {
+                type: { const: "backbone.bash" },
+                approval: { enum: ["sandbox", "pause"] },
+                outputs: { enum: ["immediate", "held"] },
+                annotations: { $ref: "#/$defs/annotations" },
+            },
+        },
         functionTool: {
             type: "object",
             additionalProperties: false,
@@ -192,6 +208,7 @@ export const agentSchema = {
                 { if: typeIs("backbone.document_convert"), then: { $ref: "#/$defs/documentConvertTool" } },
                 { if: typeIs("backbone.todo"), then: { $ref: "#/$defs/todoTool" } },
                 { if: typeIs("backbone.skill"), then: { $ref: "#/$defs/skillTool" } },
+                { if: typeIs("backbone.bash"), then: { $ref: "#/$defs/bashTool" } },
                 { if: typeIs("function"), then: { $ref: "#/$defs/functionTool" } },
                 {
                     // The validator reports these with the reason from NON_AUTHORABLE_TOOL_TYPES; this keeps the published schema honest.

package/dist/agent-config/template.js

@@ -33,6 +33,8 @@ tools: []
 #   - type: backbone.todo
 #   - type: backbone.skill
 #     skills: [skill-name@latest]
+#   - type: backbone.bash
+#     approval: sandbox
 #   - type: function
 #     name: lookup_order
 #     description: Look up an order by number

package/dist/commands/ai.js

@@ -106,11 +106,11 @@ export function makeAiCommand() {
         .option("--agent <id>", "Invoke a stored agent by id or name, optionally with @label")
         .option("--model <id>", "Model in provider/model format; with --agent, one of the agent's models to run this request on")
         .option("--conversation <id>", "Conversation ID this response belongs to")
-        .option("--stream", "Stream the response (not supported by the server yet, #148)")
+        .option("--stream", "Stream the response (not supported by the CLI yet)")
         .action(async (input, opts, command) => {
         await runAction(command, async () => {
             if (opts.stream) {
-                throw new CliUsageError("Streaming is not supported by the server yet (#148). Run without --stream.");
+                throw new CliUsageError("Streaming is not supported by the CLI yet. Run without --stream.");
             }
             const model = resolveModel(opts);
             const inputText = input ?? readStdinInput();

package/dist/commands/convert.js

@@ -1,9 +1,8 @@
 import { Command } from "commander";
 import { readFileSync, writeFileSync } from "node:fs";
 import chalk from "chalk";
-import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
-import { resolveConfig, isJsonOutput } from "../lib/config.js";
-import { BackboneApiError } from "../lib/errors.js";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
 import { formatDetail, withSpinner } from "../lib/output.js";
 import { fileToBlob, getMimeType } from "../lib/multipart.js";
 function mapFormat(format) {
@@ -136,34 +135,19 @@ function buildFormData(paths, opts) {
     formData.append("options", new Blob([JSON.stringify(pipelineOptions)], { type: "application/json" }));
     return formData;
 }
+/**
+ * POST the multipart body through the typed client. The generated type describes `files` as string[],
+ * which FormData cannot match, so the placeholder body satisfies the type and bodySerializer sends the
+ * real parts; the client's auth and error middleware apply.
+ */
 async function multipartConvert(command, formData, endpoint, pipeline) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = pipeline
-        ? `${baseUrl}${endpoint}?pipeline=${encodeURIComponent(pipeline)}`
-        : `${baseUrl}${endpoint}`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST(endpoint, {
+        params: { query: { pipeline } },
+        body: { files: [] },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data;
 }
 export function makeConvertCommand() {
     const cmd = new Command("convert").description("Convert documents");

package/dist/commands/experiments.js

@@ -16,8 +16,18 @@ function formatComparisonCell(result) {
         return chalk.red("ERROR");
     const scores = result.scores ?? [];
     if (scores.length > 0) {
-        const avg = scores.reduce((sum, s) => sum + (s.score ?? 0), 0) / scores.length;
-        return avg.toFixed(2);
+        // A SKIP carries a placeholder 0.0 that is not a rating, and a comment-only
+        // score has no number; neither takes part in the average (#693).
+        const rated = scores.filter((s) => s.label !== "SKIP" && s.score != null);
+        if (rated.length > 0) {
+            return (rated.reduce((sum, s) => sum + s.score, 0) / rated.length).toFixed(2);
+        }
+        // A label-only verdict (#1163) has no number; show its label, as the console does.
+        const verdict = scores.find((s) => s.label && s.label !== "SKIP");
+        if (verdict)
+            return String(verdict.label);
+        if (scores.every((s) => s.label === "SKIP"))
+            return chalk.dim("skipped");
     }
     return result.durationMs != null ? `${result.durationMs}ms` : chalk.dim("done");
 }
@@ -392,8 +402,14 @@ export function makeExperimentsCommand() {
                 console.log(chalk.dim(`Page ${(page.number ?? 0) + 1} of ${page.totalPages ?? 0} (${page.totalElements ?? 0} total)`));
             }
             if (aggregates.length > 0) {
+                const skippedOf = (agg) => Object.entries((agg.skippedEvaluatorCounts ?? {}))
+                    .filter(([, n]) => n > 0)
+                    .map(([evaluatorId, n]) => `${evaluatorId}: ${n}`)
+                    .join(", ");
+                // Only when something was skipped, so a clean run keeps its narrow table (#693).
+                const showSkipped = aggregates.some((agg) => skippedOf(agg) !== "");
                 const aggTable = new Table({
-                    head: ["Variant", "Items", "Avg Duration", "Avg Tokens", "Total Cost"].map((h) => chalk.cyan(h)),
+                    head: ["Variant", "Items", "Avg Duration", "Avg Tokens", "Total Cost", ...(showSkipped ? ["Skipped"] : [])].map((h) => chalk.cyan(h)),
                     wordWrap: true,
                 });
                 for (const agg of aggregates) {
@@ -403,6 +419,7 @@ export function makeExperimentsCommand() {
                         agg.avgDurationMs != null ? `${Math.round(agg.avgDurationMs)}ms` : "—",
                         agg.avgTokens != null ? Math.round(agg.avgTokens) : "—",
                         agg.totalCost != null ? `$${agg.totalCost}` : "—",
+                        ...(showSkipped ? [skippedOf(agg) || "—"] : []),
                     ]);
                 }
                 console.log(chalk.bold("\nAggregates:"));

package/dist/commands/knowledge.js

@@ -37,7 +37,7 @@ export function makeKnowledgeCommand() {
         .description("Create a knowledge base and its first configuration version")
         .requiredOption("-n, --name <name>", "Knowledge base name")
         .requiredOption("--slug <slug>", "Unique slug")
-        .requiredOption("--embedding-provider <id>", "Embedding provider ID")
+        .requiredOption("--embedding-provider <id>", "Embedding provider: a provider ID, or builtin for the platform's built-in models (text-embedding-3-small, text-embedding-3-large; charged per input token)")
         .requiredOption("--embedding-model <model>", "Embedding model")
         .requiredOption("--embedding-dim <n>", "Embedding dimension", parseInt)
         .option("-d, --description <text>", "Description")
@@ -77,7 +77,7 @@ export function makeKnowledgeCommand() {
         .argument("<id>", "Knowledge base ID")
         .option("-n, --name <name>", "New name")
         .option("-d, --description <text>", "New description")
-        .option("--embedding-provider <id>", "New embedding provider ID")
+        .option("--embedding-provider <id>", "New embedding provider ID, or builtin. Re-embeds nothing: stored vectors stay comparable only if the new provider serves the same model at the same width; the safe move is a new knowledge base with the documents uploaded again")
         .option("--embedding-model <model>", "New embedding model")
         .option("--chunking-strategy <strategy>", "New chunking strategy (AUTO, FIXED, HIERARCHICAL, CUSTOM)")
         .option("--chunk-size <n>", "New chunk size", parseInt)
@@ -178,7 +178,7 @@ export function makeKnowledgeCommand() {
     cmd
         .command("embedding-models")
         .description("List embedding models a provider serves that fit a provisioned dimension")
-        .argument("<providerId>", "Provider ID")
+        .argument("<providerId>", "Provider ID, or builtin for the platform's built-in embedding models")
         .action(async (providerId, _opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);

package/dist/commands/skills.js

@@ -149,18 +149,16 @@ export function makeSkillsCommand() {
                 }
                 ({ blob, filename } = fileToBlob(path));
             }
-            const config = resolveConfig(command);
-            const authHeader = await resolveAuthHeader(config);
             const formData = new FormData();
             formData.append("file", blob, filename);
+            const client = getClient(command);
             const data = await withSpinner("Importing skill...", async () => {
-                const res = await fetch(`${config.baseUrl.replace(/\/+$/, "")}/v1/skills/import`, {
-                    method: "POST",
-                    headers: { Authorization: authHeader },
-                    body: formData,
+                // Placeholder body for the generated type; bodySerializer sends the real part.
+                const result = await client.POST("/v1/skills/import", {
+                    body: { file: "" },
+                    bodySerializer: () => formData,
                 });
-                await checkResponse(res);
-                return res.json();
+                return result.data;
             });
             formatDetail(data, command);
         });

package/dist/commands/transcribe.js

@@ -1,10 +1,9 @@
 import { Command } from "commander";
-import { resolveAuthHeader } from "../lib/client.js";
-import { resolveConfig, isJsonOutput } from "../lib/config.js";
+import { getClient } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
 import { handleError } from "../lib/errors.js";
 import { formatDetail, withSpinner } from "../lib/output.js";
 import { fileToBlob } from "../lib/multipart.js";
-import { BackboneApiError } from "../lib/errors.js";
 export function makeTranscribeCommand() {
     const cmd = new Command("transcribe")
         .description("Transcribe an audio file")
@@ -17,8 +16,6 @@ export function makeTranscribeCommand() {
         .action(async (file, opts, command) => {
         const json = isJsonOutput(command);
         try {
-            const config = resolveConfig(command);
-            const authHeader = await resolveAuthHeader(config);
             const { blob, filename } = fileToBlob(file);
             const formData = new FormData();
             formData.append("file", blob, filename);
@@ -31,30 +28,15 @@ export function makeTranscribeCommand() {
                 formData.append("response_format", opts.format);
             if (opts.temperature)
                 formData.append("temperature", opts.temperature);
-            const baseUrl = config.baseUrl.replace(/\/+$/, "");
-            const url = `${baseUrl}/v1/audio/transcriptions`;
+            const client = getClient(command);
             const data = await withSpinner("Transcribing...", async () => {
-                const res = await fetch(url, {
-                    method: "POST",
-                    headers: { Authorization: authHeader },
-                    body: formData,
+                // The generated type describes "file" as a binary string, which FormData cannot match;
+                // the placeholder satisfies it and bodySerializer sends the real parts.
+                const result = await client.POST("/v1/audio/transcriptions", {
+                    body: { file: "", model: opts.model },
+                    bodySerializer: () => formData,
                 });
-                if (!res.ok) {
-                    let body;
-                    try {
-                        body = await res.json();
-                    }
-                    catch {
-                        body = {
-                            error: res.statusText,
-                            message: `HTTP ${res.status}: ${res.statusText}`,
-                            status: res.status,
-                            timestamp: new Date().toISOString(),
-                        };
-                    }
-                    throw new BackboneApiError(body);
-                }
-                return res.json();
+                return result.data;
             });
             formatDetail(data, command);
         }

package/dist/lib/agent-run.d.ts

@@ -116,6 +116,9 @@ export declare function parseAgentModel(model?: string): {
  * clipboard. Newlines and tabs stay. JSON output is never passed through this.
  */
 export declare function stripControl(s: string): string;
+export declare function hasInvisible(s: string): boolean;
+/** Replaces each hidden code point with a visible `<U+XXXX>`, so approving a diff means having seen it. */
+export declare function revealInvisible(s: string): string;
 export declare function shellQuote(value: string): string;
 /** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
 export declare function connectionsSentence(connections: PendingConnection[]): string;

package/dist/lib/agent-run.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { DEFAULT_CHAT_URL } from "./config.js";
 import { connectCallIds, connectionsPhrase, pendingConnectionsOf } from "./connect-pause.js";
 import { CliUsageError } from "./errors.js";
+import { previewIsIncomplete, previewLines } from "./skills-apply-preview.js";
 export const CONVERSATION_MODES = ["plan", "ask", "auto"];
 /** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
 export const MODE_OPTION_HELP = "Conversation mode: plan (read-only), ask (no automatic approver; calls that need approval wait for you), " +
@@ -88,6 +89,39 @@ const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
 export function stripControl(s) {
     return s.replace(CONTROL_CHARS, "");
 }
+/**
+ * Code points that print as nothing, or reorder what surrounds them, yet reach the model: Unicode
+ * tags, zero-width characters, directional marks, embeddings, overrides and isolates, the word
+ * joiner and the byte-order mark (#1027). As numbers, not an escaped regex, so no tool can fold
+ * them into the source. Kept in step with `surface/src/core/skills-apply-preview.ts`.
+ */
+const INVISIBLE_RANGES = [
+    [0xe0000, 0xe007f],
+    [0x200b, 0x200f],
+    [0x202a, 0x202e],
+    [0x2060, 0x2060],
+    [0x2066, 0x2069],
+    [0x061c, 0x061c],
+    [0xfeff, 0xfeff],
+];
+function isInvisible(codePoint) {
+    return INVISIBLE_RANGES.some(([low, high]) => codePoint >= low && codePoint <= high);
+}
+export function hasInvisible(s) {
+    for (const char of s)
+        if (isInvisible(char.codePointAt(0)))
+            return true;
+    return false;
+}
+/** Replaces each hidden code point with a visible `<U+XXXX>`, so approving a diff means having seen it. */
+export function revealInvisible(s) {
+    let out = "";
+    for (const char of s) {
+        const codePoint = char.codePointAt(0);
+        out += isInvisible(codePoint) ? `<U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}>` : char;
+    }
+    return out;
+}
 export function shellQuote(value) {
     if (/^[A-Za-z0-9._@/:-]+$/.test(value))
         return value;
@@ -119,9 +153,27 @@ function relayDecideCommand(ref, responseId, calls, withApprovals) {
     return (`2kw agents decide ${shellQuote(ref)} --response ${shellQuote(responseId)}${outputs.join("")}` +
         (withApprovals ? " --approve-all" : ""));
 }
+/**
+ * A connector tool's open approval, decoded from the standard `mcp_approval_request` item (#949). The item
+ * is the MCP twin of `backbone:approval_request` (#805): it names the server and the tool, carries no call
+ * id, policy class or status, and exists only while the decision is open, so its id doubles as the call id
+ * and the tool is named as the approval row stores it, `mcp__<server_label>__<tool>`.
+ */
+function connectorApproval(i) {
+    return {
+        approvalId: String(i.id),
+        callId: String(i.id),
+        tool: `mcp__${String(i.server_label)}__${String(i.name)}`,
+        arguments: parseArguments(i.arguments),
+        policyClass: "unknown",
+        reason: null,
+        preview: null,
+    };
+}
 /**
  * Output item types the envelope decodes, or that never hold a run: text, reasoning and finished
- * connector calls. A pause on anything else (a connector approval's `mcp_approval_request`) is named.
+ * connector calls. A pause on anything else is named.
+ * `backbone:tool_image` is an image a finished `ViewImage` call attached (#1244): it never holds a run.
  */
 const DECODED_ITEM_TYPES = new Set([
     "message",
@@ -130,6 +182,8 @@ const DECODED_ITEM_TYPES = new Set([
     "function_call_output",
     "backbone:approval_request",
     "backbone:connector_auth_request",
+    "backbone:tool_image",
+    "mcp_approval_request",
     "mcp_call",
     "mcp_list_tools",
 ]);
@@ -153,18 +207,21 @@ export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
         String(i.call_id),
         i.status === "incomplete" ? "incomplete" : "completed",
     ]));
-    const pendingApprovals = output
-        // Only an open request is pending; judge- or grant-decided requests (#634, #629) carry another status.
-        .filter((i) => i.type === "backbone:approval_request" && (i.status === undefined || i.status === "in_progress"))
-        .map((i) => ({
-        approvalId: String(i.id),
-        callId: String(i.call_id),
-        tool: String(i.tool),
-        arguments: parseArguments(i.arguments),
-        policyClass: String(i.policy_class),
-        reason: typeof i.reason === "string" && i.reason ? i.reason : null,
-        preview: i.preview && typeof i.preview === "object" && !Array.isArray(i.preview) ? i.preview : null,
-    }));
+    const pendingApprovals = [
+        ...output
+            // Only an open request is pending; judge- or grant-decided requests (#634, #629) carry another status.
+            .filter((i) => i.type === "backbone:approval_request" && (i.status === undefined || i.status === "in_progress"))
+            .map((i) => ({
+            approvalId: String(i.id),
+            callId: String(i.call_id),
+            tool: String(i.tool),
+            arguments: parseArguments(i.arguments),
+            policyClass: String(i.policy_class),
+            reason: typeof i.reason === "string" && i.reason ? i.reason : null,
+            preview: i.preview && typeof i.preview === "object" && !Array.isArray(i.preview) ? i.preview : null,
+        })),
+        ...output.filter((i) => i.type === "mcp_approval_request").map(connectorApproval),
+    ];
     // The one decoding rule (#1086): only an open request with its id, call id, label and host.
     const connectRequests = pendingConnectionsOf(output);
     const pendingConnections = connectRequests.map(({ serverLabel, host, reason, destinations }) => ({
@@ -221,6 +278,13 @@ export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
                 : decide;
         }
     }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingApprovals.length > 0 && ref && responseId) {
+        // A continuation must decide every pending approval (400 incomplete_tool_outputs otherwise), so
+        // `--continue` would fail; decide answers them and the engine re-checks access itself (#949 review).
+        next =
+            `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${THEN_RUN}` +
+                `2kw agents decide ${shellQuote(ref)} --response ${shellQuote(responseId)} --approve-all`;
+    }
     else if (status === "requires_tool_output" && pendingConnections.length > 0 && responseId) {
         // `agents run --continue` needs no input: the continuation re-checks access itself.
         const resume = ref
@@ -269,8 +333,15 @@ export function printRunText(env) {
         console.log(chalk.dim(`   tools: ${env.toolCalls.map((c) => `${s(c.tool)} ${c.status === "incomplete" ? "✗" : "✓"}`).join("  ")}`));
     const printApprovals = () => env.pendingApprovals.forEach((a, i) => {
         console.log(`  ${i + 1}. ${s(a.tool)} [${s(a.policyClass)}] ${s(a.approvalId)}`);
-        // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
-        console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
+        // A SkillsApply change reads as its diff (#1028), like the interactive prompt; an incomplete
+        // preview keeps the arguments, the one place a member can read what would persist.
+        if (a.preview)
+            for (const line of previewLines(a.preview))
+                console.log(chalk.dim(`     ${s(line)}`));
+        if (!a.preview || previewIsIncomplete(a.preview)) {
+            // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
+            console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
+        }
         if (a.reason)
             console.log(chalk.dim(`     reason: ${s(a.reason)}`));
     });

package/dist/lib/approval-prompt.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import chalk from "chalk";
-import { stripControl } from "./agent-run.js";
+import { hasInvisible, revealInvisible, stripControl } from "./agent-run.js";
 import { REMEMBER_NOTE, previewIsIncomplete, previewLines } from "./skills-apply-preview.js";
 /** Raised when the prompt's input closes (EOF, Ctrl+C, Ctrl+D) before an answer arrives. */
 export class PromptAbortedError extends Error {
@@ -50,9 +50,11 @@ export function readlineAsk(input = process.stdin, output = process.stderr) {
 }
 export async function promptApprovals(pending, ask, write = (line) => console.error(line)) {
     const answers = new Map();
-    const s = stripControl;
+    const s = (value) => revealInvisible(stripControl(value));
     for (const [index, a] of pending.entries()) {
-        const destructive = a.policyClass.toLowerCase() === "destructive";
+        // A connector approval carries no policy class (#949): "unknown" may be destructive, so it is never
+        // offered a standing grant here; the server drops one for a destructive row anyway.
+        const destructive = ["destructive", "unknown"].includes(a.policyClass.toLowerCase());
         write(chalk.yellow(`\nApproval ${index + 1}/${pending.length}: ${s(a.tool)} [${s(a.policyClass)}]`));
         // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
         const request = () => write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
@@ -60,7 +62,12 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
             // A SkillsApply change reads as its diff (#782, spec §10). When the preview leaves changes
             // out, the full arguments follow it: this prompt never runs with --json, so it is the only
             // place the member can read what would persist (spec D7).
-            for (const line of previewLines(a.preview))
+            const lines = previewLines(a.preview);
+            // Hidden characters are shown as <U+XXXX> below; the warning says why (#1027, spec D7).
+            if (lines.some(hasInvisible)) {
+                write(chalk.yellow("Hidden characters found: shown as <U+XXXX>. A model reads them; you would not see them. Check each marked line before you approve."));
+            }
+            for (const line of lines)
                 write(colourPreviewLine(s(line)));
             if (previewIsIncomplete(a.preview)) {
                 write(chalk.dim("Full request (the preview leaves changes out):"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.3.0",
+  "version": "6.4.0-dev.10",
   "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
   "keywords": [
     "cli",