@2kw/ai 6.2.2 → 6.3.0-dev.106

package/dist/commands/settings.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export declare function parseSettingValue(raw: string): Record<string, unknown>;
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export declare function makeSettingsCommand(): Command;
+//# sourceMappingURL=settings.d.ts.map

package/dist/commands/settings.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail } from "../lib/output.js";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export function parseSettingValue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliUsageError(`Setting value is not valid JSON: ${raw}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError('Setting value must be a JSON object, e.g. \'{"agentId":"agt_123"}\'');
+    }
+    return parsed;
+}
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export function makeSettingsCommand() {
+    const cmd = new Command("settings").description("Organization and member settings (e.g. agents.default)");
+    cmd
+        .command("get <key>")
+        .description("Show a setting: the effective value, its source and both tiers")
+        .action(async (key, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/settings/{key}", {
+                params: { path: { key } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("set <key> <json>")
+        .description("Set your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Write the organization's value instead of your own")
+        .action(async (key, json, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = { value: parseSettingValue(json) };
+            const { data } = opts.org
+                ? await client.PUT("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                    body,
+                })
+                : await client.PUT("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                    body,
+                });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("unset <key>")
+        .description("Clear your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Clear the organization's value instead of your own")
+        .action(async (key, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = opts.org
+                ? await client.DELETE("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                })
+                : await client.DELETE("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                });
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=settings.js.map

package/dist/commands/skill-versions.js

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail } from "../lib/output.js";
@@ -48,6 +48,32 @@ export function makeSkillVersionsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("restore")
+        .description("Restore a version as a new version; latest moves to it (the newest version is reused when it already has the content)")
+        .argument("<id>", "Skill ID")
+        .argument("<versionNumber>", "Version number to restore", parseVersionNumber)
+        .action(async (id, versionNumber, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data, response } = await client.POST("/v1/skills/{id}/versions/{versionNumber}/restore", {
+                params: { path: { id, versionNumber } },
+            });
+            // 200, not 201: the newest version already had the content and latest moved to it.
+            if (response.status === 200 && data) {
+                console.error(`No new version: v${data.versionNumber} already has the content of v${versionNumber}; latest now points at v${data.versionNumber}.`);
+            }
+            formatDetail(data, command);
+        });
+    });
     return cmd;
 }
+/** A restore names an existing version by number; refuse anything else before calling the API (#783). */
+function parseVersionNumber(value) {
+    const n = Number(value);
+    if (!/^\d+$/.test(value) || n < 1) {
+        throw new InvalidArgumentError("Version number must be a positive integer.");
+    }
+    return n;
+}
 //# sourceMappingURL=skill-versions.js.map

package/dist/commands/skills.js

@@ -21,6 +21,17 @@ async function checkResponse(res) {
         timestamp: body.timestamp ?? new Date().toISOString(),
     });
 }
+const MIN_ROLES = ["user", "viewer", "member", "admin", "owner"];
+/** A role word as the API's `Role`, or null for `none` (#785). */
+function parseMinRole(word) {
+    const lower = word.trim().toLowerCase();
+    if (lower === "none")
+        return null;
+    if (MIN_ROLES.includes(lower)) {
+        return lower.toUpperCase();
+    }
+    throw new Error(`Role must be one of: ${MIN_ROLES.join(", ")}, none`);
+}
 /** Manage skills, versions and labels (#642). */
 export function makeSkillsCommand() {
     const cmd = new Command("skills").description("Manage skills");
@@ -75,6 +86,24 @@ export function makeSkillsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("min-role")
+        .description("Set the minimum organization role that sees this skill in agent runs (admin only); none removes it")
+        .argument("<id>", "Skill ID")
+        .argument("<role>", "user, viewer, member, admin, owner or none")
+        .action(async (id, role, _opts, command) => {
+        await runAction(command, async () => {
+            const minRole = parseMinRole(role);
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/skills/{id}/min-role", {
+                params: { path: { id } },
+                // The spec publishes minRole without null (springdoc marks no record component
+                // nullable); the operation documents null as "remove the minimum", and it is sent as such.
+                body: { minRole: minRole },
+            });
+            formatDetail(data, command);
+        });
+    });
     cmd
         .command("delete")
         .description("Delete a skill")
@@ -157,7 +186,8 @@ export function makeSkillsCommand() {
                 const { data } = await client.GET("/v1/skills/{id}", { params: { path: { id } } });
                 if (!data?.name)
                     throw new Error("Skill name missing; specify an output path with -o.");
-                outputPath = `${basename(data.name)}-v${versionNumber}.zip`;
+                // #788: ":" (a plugin skill) becomes "." before basename, which on Windows reads "a:" as a drive.
+                outputPath = `${basename(data.name.replace(/:/g, "."))}-v${versionNumber}.zip`;
             }
             const config = resolveConfig(command);
             const authHeader = await resolveAuthHeader(config);

package/dist/commands/tracing.js

@@ -1,10 +1,11 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
 import { formatDetail, formatList } from "../lib/output.js";
+import { tracingSettingsBody } from "../lib/tracing-settings.js";
 export function makeTracingCommand() {
     const cmd = new Command("tracing").description("Traces and per-org tracing settings (prompt / completion capture)");
     // ── settings ──────────────────────────────────────────────────
-    const settings = new Command("settings").description("Manage per-org tracing settings (includePrompts / includeCompletions)");
+    const settings = new Command("settings").description("Manage per-org tracing settings (PII capture and trace retention)");
     settings
         .command("get")
         .description("Show current tracing settings")
@@ -20,6 +21,7 @@ export function makeTracingCommand() {
         .description("Update tracing settings. Both toggles control PII capture — default is false for both.")
         .option("--include-prompts <bool>", "Retain prompt content on ingested spans (true/false)")
         .option("--include-completions <bool>", "Retain completion content on ingested spans (true/false)")
+        .option("--retention-days <days>", 'Trace retention in days, at most your plan\'s limit, or "plan" to follow the plan. Shortening deletes older traces at the next daily sweep.')
         .action(async (opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);
@@ -27,17 +29,8 @@ export function makeTracingCommand() {
             // resetting the other. Otherwise an unset flag defaults to false
             // and silently disables capture the admin had already enabled.
             const { data: current } = await client.GET("/v1/tracing/settings");
-            const body = {
-                includePrompts: opts.includePrompts !== undefined
-                    ? opts.includePrompts === "true"
-                    : (current?.includePrompts ?? false),
-                includeCompletions: opts.includeCompletions !== undefined
-                    ? opts.includeCompletions === "true"
-                    : (current?.includeCompletions ?? false),
-            };
-            const { data } = await client.PUT("/v1/tracing/settings", {
-                body,
-            });
+            const body = tracingSettingsBody(current, opts);
+            const { data } = await client.PUT("/v1/tracing/settings", { body });
             formatDetail(data, command);
         });
     });

package/dist/index.js

@@ -21,6 +21,8 @@ import { makeDocsCommand } from "./commands/docs.js";
 import { makeContextCommand } from "./commands/context.js";
 import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
+import { makeSettingsCommand } from "./commands/settings.js";
+import { makeMemoryCommand } from "./commands/memory.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -29,6 +31,8 @@ import { makeConversationsCommand } from "./commands/conversations.js";
 import { makeKnowledgeCommand } from "./commands/knowledge.js";
 import { makeFilesCommand } from "./commands/files.js";
 import { makeInstallationsCommand } from "./commands/installations.js";
+import { makeConnectorsCommand } from "./commands/connectors.js";
+import { makeRelaysCommand } from "./commands/relays.js";
 import { checkForUpdates } from "./lib/update-notifier.js";
 const updater = checkForUpdates(pkg.version);
 const program = new Command();
@@ -60,11 +64,15 @@ program.addCommand(makeEvaluatorsCommand());
 program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
+program.addCommand(makeSettingsCommand());
+program.addCommand(makeMemoryCommand());
 program.addCommand(makeAgentsCommand());
 program.addCommand(makeConversationsCommand());
 program.addCommand(makeKnowledgeCommand());
 program.addCommand(makeFilesCommand());
 program.addCommand(makeInstallationsCommand());
+program.addCommand(makeConnectorsCommand());
+program.addCommand(makeRelaysCommand());
 program.addCommand(makeDocsCommand());
 program.parseAsync().then(() => updater.notify());
 //# sourceMappingURL=index.js.map

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

@@ -1,6 +1,6 @@
 import type { components } from "../generated/openapi.js";
 import type { ApiClient } from "./agent-lookup.js";
-import type { ResponsesResult } from "./agent-run.js";
+import { type ConversationMode, type ResponsesResult } from "./agent-run.js";
 export type ApprovalRow = components["schemas"]["ToolApprovalDTO"];
 export interface DecideOptions {
     approve?: string[];
@@ -36,6 +36,7 @@ export declare function toApprovalItems(decisions: Decision[]): Record<string, s
  * server resolves the continuation's tools, instructions and model from this reference, so both must match
  * the run's or the continuation drops to another version or the agent's default model.
  * Never the echoed `name@<versionNumber>` (it would 404 as a label).
+ * With `mode`, the `backbone:mode` item follows the decisions (#656 D7); without it, nothing is added (D2).
  */
-export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, decisions: Decision[], label?: string, model?: string): Promise<ResponsesResult>;
+export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, decisions: Decision[], label?: string, model?: string, mode?: ConversationMode): Promise<ResponsesResult>;
 //# sourceMappingURL=agent-decide.d.ts.map

package/dist/lib/agent-decide.js

@@ -1,3 +1,4 @@
+import { modeItem } from "./agent-run.js";
 import { CliUsageError } from "./errors.js";
 import { paginationParams } from "./pagination.js";
 const MAX_PAGES = 50;
@@ -113,13 +114,15 @@ export function toApprovalItems(decisions) {
  * server resolves the continuation's tools, instructions and model from this reference, so both must match
  * the run's or the continuation drops to another version or the agent's default model.
  * Never the echoed `name@<versionNumber>` (it would 404 as a label).
+ * With `mode`, the `backbone:mode` item follows the decisions (#656 D7); without it, nothing is added (D2).
  */
-export async function continueWithDecisions(client, agentId, responseId, decisions, label, model) {
+export async function continueWithDecisions(client, agentId, responseId, decisions, label, model, mode) {
+    const approvals = toApprovalItems(decisions);
     const body = {
         model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
         previous_response_id: responseId,
         stream: false,
-        input: toApprovalItems(decisions),
+        input: mode ? [...approvals, modeItem(mode)] : approvals,
     };
     // The generated body type does not model backbone: extension items, hence the cast.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

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

@@ -1,5 +1,8 @@
+import type { components } from "../generated/openapi.js";
 type AnyRecord = Record<string, any>;
 export type RunStatus = "completed" | "requires_approval" | "requires_tool_output" | "incomplete";
+/** A built-in SkillsApply approval's preview (#781, spec §6); the generated type, fields all optional. */
+export type SkillsApplyPreview = components["schemas"]["SkillsApplyPreview"];
 export interface PendingApproval {
     approvalId: string;
     callId: string;
@@ -8,6 +11,8 @@ export interface PendingApproval {
     policyClass: string;
     /** Why the automatic approver escalated this request to a human (#634); null when it did not. */
     reason: string | null;
+    /** What a built-in SkillsApply change does (#781); null for every other approval. Keyed on presence, not on the tool name (#948). */
+    preview: SkillsApplyPreview | null;
 }
 export interface ToolCallSummary {
     tool: string;
@@ -20,10 +25,43 @@ export interface PendingToolCall {
     callId: string;
     arguments: unknown;
 }
+/**
+ * A connector the run waits for the user to connect, allow or reconnect in chat.2kw.ai: an open
+ * `backbone:connector_auth_request` (#807 R12). The caller never answers the connect call; the
+ * continuation re-checks access itself.
+ */
+export interface PendingConnection {
+    serverLabel: string;
+    host: string;
+    /** `connect`, `allow` or `reconnect`. */
+    reason: string;
+    /** The egress difference an allow is re-asked for; absent otherwise. */
+    destinations?: string[];
+}
+/** The end user's conversation mode (epic &59); the server matches these three values exactly. */
+export type ConversationMode = "plan" | "ask" | "auto";
+export declare const CONVERSATION_MODES: readonly ConversationMode[];
+/** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
+export declare const MODE_OPTION_HELP: string;
+/**
+ * The `--mode` value, checked before any request is sent: anything but the three exact values is a
+ * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ */
+export declare function parseModeOption(raw: string | undefined): ConversationMode | undefined;
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export declare function modeItem(mode: ConversationMode): {
+    type: "backbone:mode";
+    mode: ConversationMode;
+};
+/**
+ * The mode the response ran under (`conversation_mode`, #656). An absent key (a server before #656)
+ * and any value other than the three read as null, which also means "none set".
+ */
+export declare function responseMode(result: ResponsesResult | undefined): ConversationMode | null;
 export interface RunEnvelope {
     status: RunStatus;
-    /** Reserved for the server-side conversation mode (#656); always null until then. */
-    mode: null;
+    /** The conversation mode the request ran under (`conversation_mode`); null when none is set. */
+    mode: ConversationMode | null;
     agent: string | null;
     version: number | null;
     responseId: string | null;
@@ -32,6 +70,7 @@ export interface RunEnvelope {
     toolCalls: ToolCallSummary[];
     pendingApprovals: PendingApproval[];
     pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
     incompleteReason: string | null;
     usage: {
         inputTokens: number;
@@ -56,6 +95,7 @@ export interface ResponsesResult {
     incomplete_details?: {
         reason?: string;
     } | null;
+    conversation_mode?: string | null;
 }
 export declare const EXIT_CODES: Record<RunStatus, number>;
 /** The assistant's text: every `output_text` part of every `message` item, in order. */
@@ -76,7 +116,13 @@ export declare function parseAgentModel(model?: string): {
  */
 export declare function stripControl(s: string): string;
 export declare function shellQuote(value: string): string;
-export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string): RunEnvelope;
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export declare function connectionsSentence(connections: PendingConnection[]): string;
+/**
+ * @param chatUrl the chat web host of the API the run went to ({@link chatUrlFor}); a connect pause's
+ *   `next` sends the user to its Connectors page.
+ */
+export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string, chatUrl?: string): RunEnvelope;
 /** Human-readable rendering of an envelope on stdout. Every value printed is passed through {@link stripControl}. */
 export declare function printRunText(env: RunEnvelope): void;
 export {};

package/dist/lib/agent-run.js

@@ -1,4 +1,36 @@
 import chalk from "chalk";
+import { DEFAULT_CHAT_URL } from "./config.js";
+import { CliUsageError } from "./errors.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), " +
+    "auto (the operator's policy as written). Without it, the conversation keeps its mode";
+function isConversationMode(value) {
+    return typeof value === "string" && CONVERSATION_MODES.includes(value);
+}
+/**
+ * The `--mode` value, checked before any request is sent: anything but the three exact values is a
+ * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ */
+export function parseModeOption(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (isConversationMode(raw))
+        return raw;
+    throw new CliUsageError(`Invalid --mode '${raw}': use plan, ask or auto.`);
+}
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export function modeItem(mode) {
+    return { type: "backbone:mode", mode };
+}
+/**
+ * The mode the response ran under (`conversation_mode`, #656). An absent key (a server before #656)
+ * and any value other than the three read as null, which also means "none set".
+ */
+export function responseMode(result) {
+    const raw = result?.conversation_mode;
+    return isConversationMode(raw) ? raw : null;
+}
 export const EXIT_CODES = {
     completed: 0,
     requires_approval: 3,
@@ -60,7 +92,78 @@ export function shellQuote(value) {
         return value;
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-export function buildRunEnvelope(result, agentRef) {
+/** An open connector consent request; a continuation's projection carries another status. */
+function pendingConnectionsOf(output) {
+    return output
+        .filter((i) => i.type === "backbone:connector_auth_request" && (i.status === undefined || i.status === "in_progress"))
+        .map((i) => ({
+        serverLabel: String(i.server_label),
+        host: String(i.host),
+        reason: String(i.reason),
+        ...(Array.isArray(i.destinations) && i.destinations.length > 0
+            ? { destinations: i.destinations.map((d) => String(d)) }
+            : {}),
+    }));
+}
+/**
+ * The call ids a connect pause withholds from the caller: the call each request names, and every
+ * `mcp__<label>__connect` call for a pending connector (the model may call it more than once; one
+ * request stands for all of them).
+ */
+function connectCallIds(output, connections) {
+    const connectNames = new Set(connections.map((c) => `mcp__${c.serverLabel}__connect`));
+    const ids = new Set();
+    for (const item of output) {
+        if (item.type === "backbone:connector_auth_request" && (item.status === undefined || item.status === "in_progress")) {
+            ids.add(String(item.call_id));
+        }
+        else if (item.type === "function_call" && connectNames.has(String(item.name))) {
+            ids.add(String(item.call_id));
+        }
+    }
+    return ids;
+}
+function connectionPhrase(c) {
+    const target = `${c.serverLabel} (${c.host})`;
+    if (c.reason === "allow")
+        return `allow the agent to use ${target}`;
+    if (c.reason === "reconnect")
+        return `reconnect ${target}`;
+    return `connect ${target}`;
+}
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export function connectionsSentence(connections) {
+    const phrases = connections.map(connectionPhrase);
+    const joined = phrases.length > 1 ? `${phrases.slice(0, -1).join(", ")} and ${phrases.at(-1)}` : phrases[0] ?? "";
+    return joined.charAt(0).toUpperCase() + joined.slice(1);
+}
+/** Joins a connect pause's instruction to the command that continues it; {@link printRunText} breaks the line there. */
+const THEN_RUN = ", then run: ";
+/**
+ * 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.
+ */
+const DECODED_ITEM_TYPES = new Set([
+    "message",
+    "reasoning",
+    "function_call",
+    "function_call_output",
+    "backbone:approval_request",
+    "backbone:connector_auth_request",
+    "mcp_call",
+    "mcp_list_tools",
+]);
+function undecodedPause(output) {
+    const types = [...new Set(output.map((i) => String(i.type)).filter((t) => !DECODED_ITEM_TYPES.has(t)))];
+    return types.length > 0
+        ? `This CLI cannot show or answer ${types.join(", ")}.`
+        : "This CLI cannot tell what the run waits for.";
+}
+/**
+ * @param chatUrl the chat web host of the API the run went to ({@link chatUrlFor}); a connect pause's
+ *   `next` sends the user to its Connectors page.
+ */
+export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
     const output = result?.output ?? [];
     const { agent, version } = parseAgentModel(result?.model);
     // call_id → status of its tool output; a failed server-side tool run is marked `incomplete`.
@@ -80,8 +183,10 @@ export function buildRunEnvelope(result, agentRef) {
         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 withheldCallIds = new Set(pendingApprovals.map((a) => a.callId));
+    const pendingConnections = pendingConnectionsOf(output);
+    const withheldCallIds = new Set([...pendingApprovals.map((a) => a.callId), ...connectCallIds(output, pendingConnections)]);
     const toolCalls = [];
     const pendingToolCalls = [];
     for (const item of output) {
@@ -105,19 +210,38 @@ export function buildRunEnvelope(result, agentRef) {
             status = "incomplete";
             break;
         case "requires_action":
-            status = pendingToolCalls.length > 0 || pendingApprovals.length === 0 ? "requires_tool_output" : "requires_approval";
+            // A connect pause keeps exit 4 (§8, CLI agents D14): the CLI cannot answer it either.
+            status =
+                pendingToolCalls.length > 0 || pendingConnections.length > 0 || pendingApprovals.length === 0
+                    ? "requires_tool_output"
+                    : "requires_approval";
             break;
         default:
             throw new Error(`Unexpected response status: ${result?.status}`);
     }
     const responseId = result?.id ?? null;
     const ref = agentRef ?? agent;
-    const next = status === "requires_approval" && ref && responseId
-        ? `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`
-        : null;
+    let next = null;
+    if (status === "requires_approval" && ref && responseId) {
+        next = `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingToolCalls.length === 0 && responseId) {
+        // Not with a relayed call beside it: a continuation without that call's output is refused.
+        // `agents run --continue` needs no input: the continuation re-checks access itself.
+        const resume = ref
+            ? `${THEN_RUN}2kw agents run ${shellQuote(ref)} --continue ${shellQuote(responseId)}`
+            : `, then run the agent again with --continue ${shellQuote(responseId)}`;
+        next = `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${resume}`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length === 0 && pendingToolCalls.length === 0 && responseId) {
+        // Paused on nothing the envelope decodes: say so, rather than exit 4 without a word.
+        next =
+            `${undecodedPause(output)} Response ${responseId} stays paused: answer it in ${chatUrl}/ ` +
+                "or from a client that continues it by previous_response_id.";
+    }
     return {
         status,
-        mode: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,
@@ -126,6 +250,7 @@ export function buildRunEnvelope(result, agentRef) {
         toolCalls,
         pendingApprovals,
         pendingToolCalls,
+        pendingConnections,
         incompleteReason: result?.incomplete_details?.reason ?? null,
         usage: result?.usage
             ? { inputTokens: result.usage.input_tokens ?? 0, outputTokens: result.usage.output_tokens ?? 0 }
@@ -160,8 +285,26 @@ export function printRunText(env) {
             console.log(`\nDecide with:\n  ${s(env.next)}`);
     }
     else if (env.status === "requires_tool_output") {
-        console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
-        env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        if (env.pendingConnections.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs you to connect in chat:"));
+            env.pendingConnections.forEach((c) => {
+                console.log(`  - ${s(connectionsSentence([c]))}`);
+                if (c.destinations?.length)
+                    console.log(chalk.dim(`    new destinations: ${s(c.destinations.join(", "))}`));
+            });
+            // The continue command on its own line, ready to copy.
+            if (env.next)
+                console.log(`\n${s(env.next.replace(THEN_RUN, ", then run:\n  "))}`);
+        }
+        if (env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
+            env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        }
+        if (!env.pendingConnections.length && !env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused on something this CLI cannot show:"));
+            if (env.next)
+                console.log(`  ${s(env.next)}`);
+        }
     }
     else if (env.status === "incomplete") {
         console.log(chalk.yellow(`\nIncomplete: ${s(env.incompleteReason ?? "unknown reason")}`));

package/dist/lib/approval-prompt.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import chalk from "chalk";
 import { 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 {
     constructor() {
@@ -54,7 +55,23 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
         const destructive = a.policyClass.toLowerCase() === "destructive";
         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.
-        write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        const request = () => write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        if (a.preview) {
+            // 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))
+                write(colourPreviewLine(s(line)));
+            if (previewIsIncomplete(a.preview)) {
+                write(chalk.dim("Full request (the preview leaves changes out):"));
+                request();
+            }
+            if (!destructive)
+                write(chalk.dim(REMEMBER_NOTE));
+        }
+        else {
+            request();
+        }
         if (a.reason)
             write(chalk.dim(`reason: ${s(a.reason)}`));
         const question = destructive ? "[a]pprove / [r]eject? " : "[a]pprove / [r]eject / approve and [R]emember? ";
@@ -81,4 +98,17 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
     }
     return answers;
 }
+/** Diff lines sit indented six spaces under their file; only those are coloured. */
+function colourPreviewLine(line) {
+    if (!line.startsWith("      "))
+        return line;
+    const body = line.slice(6);
+    if (body.startsWith("+"))
+        return chalk.green(line);
+    if (body.startsWith("-"))
+        return chalk.red(line);
+    if (body.startsWith("@@"))
+        return chalk.cyan(line);
+    return chalk.dim(line);
+}
 //# sourceMappingURL=approval-prompt.js.map