@wirecat/cli-core 0.596.0 → 0.598.0

package/CHANGELOG.md

@@ -5,6 +5,85 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.598.0 — 07.11.2026
+
+### Added
+
+- **`runScopeCases`** (`@wirecat/cli-core/testing`): cases that each remote command of a program runs inside
+  cli-core's run, so `--record` keeps a run named after it, and that `--timeout` ends it when the service never
+  answers. A command beside the run answers under the process run and fails. `neverAnswers` is the `fetch` for the
+  silent run.
+- **`inCommandRun(command, body)`** (`@wirecat/cli-core/cli`): runs `body` inside cli-core's run with the settings of
+  the app `run()` was given, which `run()` now hands every command (`environment.resolveSettings`).
+
+### Changed — may break callers
+
+- **`addMeetingCommands` takes `inRun`**, which `meetings sync` runs inside: pass `inCommandRun` from
+  `@wirecat/cli-core/cli`. The meetings module cannot reach cli-core's run itself.
+
+### Fixed
+
+- **The shared CRM, calendar and meetings commands run inside cli-core's run.** `sync` and the deal and lead writes
+  from `addCrmCommands`, every command from `addCalendarCommands`, and `meetings sync` answered under the process
+  run: `--record` kept no run, and `runs show` could not find the id they answered. A CLI that wrapped them in a run
+  of its own can drop that.
+- **An MCP server's `--permission` levels refuse a messenger write before it connects.** The early refusal of a change
+  on the messenger read the command's flags only, so `mcp serve --permission messages.send=deny` let the command
+  connect and left the refusal to the send guard. It now merges the server's levels as `baseContext` does.
+  `withAgentLevels(command, flags)` (`@wirecat/cli-core/cli`) is that merge, for a CLI's own resolver.
+- **An app's `mcp serve` over stdio ends when it was stopped before it listened.** `serveAppOverStdio` waited only
+  for an abort event, which a signal that had already fired never sends, so the server hung with stdin open.
+
+## 0.597.0 — 07.11.2026
+
+### Added
+
+- **`--field` by label.** CRM `create` and `update` resolve `--field <key>=<value>` by the synced field definitions:
+  a field by its code or whole label (a label two fields share is refused as `field.ambiguous` with both codes, an
+  unknown one as `field.unknown` with close candidates), a list field's option by its id or label
+  (`field.unknown-option`), and a multiple field's repeats into a list; a single field given twice is refused. A CRM
+  whose definitions are not stored takes codes as typed.
+- **`CrmWrites.alsoChecks(kind, verb)`**: a CLI's own keys a write also checks, such as `api.crm.deal.update`.
+  `crmAlsoChecks(also)` gives `commandPermissions({ alsoChecks })` every key a CRM write may check, so `--dry-run`
+  names the implied move, close and `crm.assign-others` keys and the CLI's own. A key an argument implies is a
+  `ConditionalKey` `{ key, when }`: `commandPermissions({ alsoChecks })` may return one, and the preview shows its level
+  and `when` but never refuses on it.
+- **A deal's and lead's `provider_metadata` and `assignee`.** The CRM's own field values, by code as
+  `{ label, value, option_id? }` (`CrmValue`), kept as stored in `metadata`, codes never renamed; `CrmItem.assignee`, the
+  CRM user it is assigned to, answered as the identity `<account>/user/<id>`.
+- **CRM field definitions (store version 54).** `CrmSource.fields?(kind)` lists a CRM's own fields on deals, leads,
+  contacts or companies: `CrmField` `{ code, label, type, multiple, filterable, options? }`. `syncCrm` reads them every
+  run, after the pipelines, and `store.crm.saveFields` keeps each kind's whole list in `crm_fields`: one the CRM no
+  longer lists is marked deleted, and an empty list marks them all. `store.crm.fields(account, kind)` reads them in
+  the CRM's order. Values stay in `metadata`, keyed by code. The migration adds one table; `minCompatible` stays 34.
+- **`fields list <deals|leads|people|organizations>`** in `addCrmCommands`: the synced fields of one kind, with
+  `--limit`, `--page` and `--all`, in bitrix24-cli's `fields list` shape plus `untrusted`. An unknown kind is refused
+  as `field.unknown-kind` with the allowed words.
+- **`crmSourceContract` checks `fields()`** when an adapter has it, and `crmSyncContract` checks they are stored. The
+  fake CRM has `setFields`, `calls.fields` and `SOURCE_FIELD` on its deals.
+- **A schedule's Telegram delivery is Telegram HTML.** `--to telegram-bot:<profile>/<chat>` converts the report's
+  Markdown (headings, bold, italic, code, links, lists, tables as label lines, rules) to the tags `tg` accepts and
+  sends it with `--html`; the 4096 and 1024 character limits count the converted text, and a long report's caption
+  is cut until its HTML fits. When `tg` answers `validation_error`, the send is repeated once as plain text and
+  recorded as `delivery.html-fallback`; any other failure is never resent. Email stays plain text.
+
+### Changed — may break callers
+
+- **`CrmFieldsInput.custom` is the `--field` pairs as typed** (`[name, value][]`), and `CrmFields.custom` values may be
+  a list for a multiple field.
+- **A write the CRM made whose item could not be read back is journaled as sent.** A `CrmWriter` throws it with
+  `sent: true` in the details; the error is answered with the write's `operation_id`, no longer journaled as failed.
+- **A CRM sync with `fields()` makes one more request per kind**, so a `--max-pages` budget reaches the items later.
+
+### Fixed
+
+- **A search over a read-only store no longer fails with "attempt to write a readonly database".** The message index
+  top-up and the notes, mail, events, memories and tasks index drains are skipped on a connection with `query_only`
+  (every read-only open), so `search all` in a CRM CLI answers from every source of a store only a CRM sync wrote. They
+  run on the next writable open.
+
 ## 0.596.0 — 06.11.2026
 
 ### Added

package/dist/background/deliver.d.ts

@@ -22,9 +22,13 @@ export declare const DELIVERY_REASONS: {
     readonly routeInvalid: "delivery.route-invalid";
     readonly timeout: "delivery.timeout";
     readonly failed: "delivery.failed";
+    readonly htmlFallback: "delivery.html-fallback";
 };
 export type DeliveryReason = (typeof DELIVERY_REASONS)[keyof typeof DELIVERY_REASONS];
-/** One route's outcome, kept in `last.json`. `error` is the sending CLI's error code and reason id, never its message. */
+/**
+ * One route's outcome, kept in `last.json`. `error` is the sending CLI's error code and reason id, never its message.
+ * A send that went as plain text because Telegram refused the HTML is `ok` with the `html-fallback` reason.
+ */
 export interface Delivery {
     to: string;
     ok: boolean;
@@ -46,6 +50,8 @@ export interface Parcel {
     /** A failed run: one line, no file. */
     line?: string;
 }
+/** The caption as HTML: the head is cut in Markdown, where no tag can be split, and cut shorter until its HTML fits. */
+export declare const htmlHeadOf: (title: string, report: string, limit?: number) => string;
 /** Hands the parcel to each route's CLI, one after another; a route that fails is recorded and the next one still goes. */
 export declare const deliver: (system: ServerSystem, env: NodeJS.ProcessEnv, routes: readonly string[], parcel: Parcel, { find, errorOf, locked, timeoutMs, }: {
     /** Where a program is on the run's PATH. */

package/dist/background/deliver.js

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CliError } from "@wirecat/cli-base";
 import { TIMED_OUT } from "./system.js";
+import { toTelegramHtml } from "./telegram-html.js";
 const PROGRAMS = {
     "telegram-bot": { command: "tg", prefix: "TG" },
     email: { command: "mail", prefix: "MAIL" },
@@ -36,6 +37,7 @@ export const DELIVERY_REASONS = {
     routeInvalid: "delivery.route-invalid",
     timeout: "delivery.timeout",
     failed: "delivery.failed",
+    htmlFallback: "delivery.html-fallback",
 };
 /** Telegram's limits, in UTF-16 units as JavaScript counts them: a message's text, and a file's caption. */
 export const TELEGRAM_TEXT_CHARS = 4096;
@@ -52,17 +54,61 @@ export const headOf = (title, report, limit = CAPTION_CHARS) => {
     const line = cut.lastIndexOf("\n");
     return `${title}\n${line > room / 2 ? cut.slice(0, line) : cut}${more}`;
 };
+/**
+ * `tg` answers a 400 from Telegram, which is what a refused HTML text is, as `validation_error`, and says nothing
+ * more exact. Any other code (network_error, outcome_unknown, provider_error…) may mean the message arrived.
+ */
+const REFUSED_CONTENT = "validation_error";
+const codeOf = (stderr) => {
+    for (const line of stderr.split("\n").reverse()) {
+        try {
+            const { code } = JSON.parse(line).error ?? {};
+            if (typeof code === "string")
+                return code;
+        }
+        catch { }
+    }
+};
+const textOf = (title, report) => (report.trim() ? `${title}\n${report.trim()}` : title);
+/** The same text as Telegram HTML; the length that counts against the limits is this one. */
+const htmlOf = (title, report) => toTelegramHtml(textOf(title, report));
+/** The caption as HTML: the head is cut in Markdown, where no tag can be split, and cut shorter until its HTML fits. */
+export const htmlHeadOf = (title, report, limit = CAPTION_CHARS) => {
+    let room = limit;
+    for (;;) {
+        const html = toTelegramHtml(headOf(title, report, room));
+        if (html.length <= limit || room <= title.length + 40)
+            return html.slice(0, limit);
+        room -= Math.max(html.length - limit, 1);
+    }
+};
 /**
  * The words that send along `route`. A bot sends a report that fits one message as its text, and a longer one as a
- * file with its head as the caption; mail takes the text on stdin. The text goes after `--`, so a report that starts
- * with a dash stays text.
+ * file with its head as the caption, both as Telegram HTML unless `plain`; mail takes the text on stdin. The text goes
+ * after `--`, so a report that starts with a dash stays text.
  */
-const argvOf = (program, route, title, report, copy) => {
+const argvOf = (program, route, title, report, copy, plain = false) => {
     const lead = [program, route.profile, "--json", "--no-input"];
     if (route.kind === "email")
         return [...lead, "messages", "send", "--to", route.address, "--subject", title];
-    const text = copy ? headOf(title, report) : report.trim() ? `${title}\n${report.trim()}` : title;
-    return [...lead, "bot", "messages", "send", ...(copy ? ["--file", copy] : []), "--", route.chat, text];
+    const text = plain
+        ? copy
+            ? headOf(title, report)
+            : headOf(title, report, TELEGRAM_TEXT_CHARS)
+        : copy
+            ? htmlHeadOf(title, report)
+            : htmlOf(title, report);
+    return [
+        ...lead,
+        "bot",
+        "messages",
+        "send",
+        ...(copy ? ["--file", copy] : []),
+        ...(plain ? [] : ["--html"]),
+        "--",
+        route.chat,
+        text,
+    ];
 };
 /** Hands the parcel to each route's CLI, one after another; a route that fails is recorded and the next one still goes. */
 export const deliver = async (system, env, routes, parcel, { find, errorOf, locked, timeoutMs = DELIVERY_TIMEOUT_MS, }) => {
@@ -94,7 +140,7 @@ export const deliver = async (system, env, routes, parcel, { find, errorOf, lock
             out.push(failed(to, DELIVERY_REASONS.programMissing, command));
             continue;
         }
-        const tooLong = `${parcel.title}\n${report.trim()}`.length > TELEGRAM_TEXT_CHARS;
+        const tooLong = route.kind === "telegram-bot" && htmlOf(parcel.title, report).length > TELEGRAM_TEXT_CHARS;
         // The sending CLI refuses its own and the other WireCat folders, where the report lives, so it gets a copy.
         const folder = route.kind === "telegram-bot" && parcel.file && tooLong ? mkdtempSync(join(tmpdir(), "wirecat-deliver-")) : "";
         const copy = folder && parcel.file ? join(folder, parcel.file.name) : undefined;
@@ -102,12 +148,22 @@ export const deliver = async (system, env, routes, parcel, { find, errorOf, lock
             if (copy && parcel.file)
                 copyFileSync(parcel.file.path, copy);
             const { [`${prefix}_PROFILE`]: _, ...childEnv } = env;
-            const ran = await system.run(argvOf(program, route, parcel.title, report, copy), childEnv, {
+            const options = {
                 timeoutMs,
                 ...(route.kind === "email" ? { input: report.trim() ? report : parcel.title } : {}),
-            });
-            if (ran.code === 0)
-                out.push({ to, ok: true });
+            };
+            let ran = await system.run(argvOf(program, route, parcel.title, report, copy), childEnv, options);
+            let fellBack = "";
+            if (route.kind === "telegram-bot" &&
+                ran.code !== 0 &&
+                ran.code !== TIMED_OUT &&
+                codeOf(ran.stderr) === REFUSED_CONTENT) {
+                fellBack = errorOf(ran.stderr, ran.code);
+                ran = await system.run(argvOf(program, route, parcel.title, report, copy, true), childEnv, options);
+            }
+            if (ran.code === 0) {
+                out.push(fellBack ? { to, ok: true, reason: DELIVERY_REASONS.htmlFallback, error: fellBack } : { to, ok: true });
+            }
             else if (ran.code === TIMED_OUT)
                 out.push(failed(to, DELIVERY_REASONS.timeout));
             else

package/dist/background/telegram-html.d.ts

@@ -0,0 +1,2 @@
+/** The report's common Markdown as Telegram HTML (<b>, <i>, <a>, <code>, <pre>); everything else is escaped text. */
+export declare const toTelegramHtml: (markdown: string) => string;

package/dist/background/telegram-html.js

@@ -0,0 +1,66 @@
+const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const SLOT = "\u0000";
+/** Inline Markdown to the tags Telegram's HTML accepts; code and links are set aside first so nothing inside them is touched. */
+const inline = (text) => {
+    const kept = [];
+    const keep = (html) => `${SLOT}${kept.push(html) - 1}${SLOT}`;
+    const done = esc(text.replaceAll(SLOT, ""))
+        .replace(/`([^`\n]+)`/g, (_, code) => keep(`<code>${code}</code>`))
+        .replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)"]+)\)/g, (_, label, url) => keep(`<a href="${url}">${label}</a>`))
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*|__(?=\S)(.+?)(?<=\S)__/g, (_, a, b) => `<b>${a ?? b}</b>`)
+        .replace(/(?<![\w*])\*(?=[^\s*])([^*\n]+?)(?<=[^\s*])\*(?![\w*])/g, "<i>$1</i>")
+        .replace(/(?<!\w)_(?=[^\s_])([^_\n]+?)(?<=[^\s_])_(?!\w)/g, "<i>$1</i>");
+    return done.replace(new RegExp(`${SLOT}(\\d+)${SLOT}`, "g"), (_, at) => kept[Number(at)] ?? "");
+};
+const cells = (row) => row
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|")
+    .map((cell) => cell.trim());
+const isRule = (row) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(row);
+/** A table has no Telegram form: each row becomes a bullet, its first cell the label and the rest `header: value`. */
+const tableLines = (rows) => {
+    const [head = [], ...body] = rows.filter((row) => !isRule(row)).map(cells);
+    return body.map(([first = "", ...rest]) => {
+        const parts = rest.map((cell, at) => {
+            const name = head[at + 1];
+            return name && rest.length > 1 ? `${name}: ${inline(cell)}` : inline(cell);
+        });
+        return `• ${parts.length ? `<b>${inline(first)}</b>: ${parts.join(" · ")}` : inline(first)}`;
+    });
+};
+/** The report's common Markdown as Telegram HTML (<b>, <i>, <a>, <code>, <pre>); everything else is escaped text. */
+export const toTelegramHtml = (markdown) => {
+    const out = [];
+    const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+    for (let at = 0; at < lines.length; at += 1) {
+        const line = lines[at] ?? "";
+        if (/^\s*```/.test(line)) {
+            const code = [];
+            at += 1;
+            while (at < lines.length && !/^\s*```/.test(lines[at] ?? ""))
+                code.push(lines[at++] ?? "");
+            out.push(`<pre>${esc(code.join("\n"))}</pre>`);
+        }
+        else if (/^\s*\|.*\|\s*$/.test(line)) {
+            const rows = [line];
+            while (/^\s*\|.*\|\s*$/.test(lines[at + 1] ?? "")) {
+                at += 1;
+                rows.push(lines[at] ?? "");
+            }
+            for (const row of tableLines(rows))
+                out.push(row);
+        }
+        else if (/^#{1,6}\s+\S/.test(line)) {
+            out.push(`<b>${inline(line.replace(/^#{1,6}\s+/, "").replace(/\*\*|__/g, "")).trimEnd()}</b>`);
+        }
+        else if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
+            out.push("──────");
+        }
+        else {
+            const bullet = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+            out.push(bullet ? `${bullet[1]}• ${inline(bullet[2] ?? "")}` : inline(line));
+        }
+    }
+    return out.join("\n");
+};

package/dist/calendar/cli/index.js

@@ -3,7 +3,7 @@ import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
 import { timezoneOf } from "@wirecat/cli-base/query";
 import { clockMeta } from "@wirecat/cli-base/standards";
 import { Argument, InvalidArgumentError, Option } from "commander";
-import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
+import { environmentOf, inCommandRun, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { changesStore, ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
 import { renderAnswer } from "../../cli/envelope.js";
@@ -77,17 +77,10 @@ const addCalendarCommandsDefinition = (program, options) => {
         renderAnswer(command, output, body, view ?? ((shown) => localTimesView(shown, zone(), output.color)));
     };
     /** Opens the profile for `work` and closes it before the answer prints, also when `work` fails. */
-    const within = async (command, work, view) => {
+    const within = (command, work, view) => inCommandRun(command, async () => {
         const run = await options.open(command, { readOnly: readsOnly(command) });
-        let body;
-        try {
-            body = await work(run);
-        }
-        finally {
-            await run.close?.();
-        }
-        answer(command, body, view);
-    };
+        answer(command, await work(run).finally(() => run.close?.()), view);
+    });
     const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} personal ${line}`) });
     const calendars = annotate(program.command("calendars").description("the account's calendars"), { effects: GROUP });
     withQuery(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json", "calendars list synced:true"), CALENDARS_QUERY).action(async (words, _opts, command) => {

package/dist/calendar/mcp/index.d.ts

@@ -10,13 +10,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -45,9 +45,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -58,9 +58,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -80,13 +80,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -115,9 +115,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -128,9 +128,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -150,13 +150,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -185,9 +185,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -198,9 +198,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -220,13 +220,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -255,9 +255,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -268,9 +268,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;

package/dist/cli/context.d.ts

@@ -34,6 +34,8 @@ export interface BaseEnvironment {
     answer?: (question: string) => Promise<string | null> | string | null;
     /** Set by `run()`; a command's run is recorded only when it is known whose run it is. */
     app?: AppIdentity;
+    /** Set by `run()`: the app's own, so a shared command group opens its run with the app's settings. */
+    resolveSettings?: (flags: GlobalFlags, options?: ResolveOptions) => Settings;
     /** Set by `run()` from `process.platform` unless a test hands one in: the OS a command's paths and units are for. */
     platform?: NodeJS.Platform;
     /** The local speech recognizer in place of the downloaded model; tests hand one in. */
@@ -120,6 +122,10 @@ export declare const runBudgetOf: (command: Command, requests?: number) => RunBu
 export declare const setExitCode: (command: Command, code: number) => void;
 export declare const provide: (program: Command, environment: BaseEnvironment) => void;
 export declare const environmentOf: <E extends BaseEnvironment = BaseEnvironment>(command: Command) => E;
+/** The command's flags with an MCP server's `--permission` levels first: they reach a run on its agent, never in argv. */
+export declare const withAgentLevels: <F extends {
+    permission?: string[];
+}>(command: Command, flags: F) => F;
 /**
  * The input and output `readSecret` uses for this command: the run's own, so a prompt goes where the run's other
  * output goes and a test that captures it sees it. `readSecret(prompt, { ...secretInputOf(this), echo: true })`.
@@ -166,4 +172,10 @@ export interface BaseContext {
 type Resolve = (flags: GlobalFlags, options?: ResolveOptions) => Settings;
 /** Everything a command needs that no messenger decides, resolved once. */
 export declare const baseContext: (command: Command, resolveSettings: Resolve) => BaseContext;
+/**
+ * A shared group's command inside cli-core's run, with the settings of the app `run()` was given: recorded, and ended
+ * by `--timeout` (WC-LIFE-5, WC-LIFE-15). The group's own opener still decides whether it needs a profile. A program
+ * parsed without `run()` has no run to open, so `body` just runs.
+ */
+export declare const inCommandRun: <T>(command: Command, body: (events: EventSink) => Promise<T>) => Promise<T>;
 export {};

package/dist/cli/context.js

@@ -37,6 +37,11 @@ export const provide = (program, environment) => {
     environments.set(program, environment);
 };
 export const environmentOf = (command) => (environments.get(rootOf(command)) ?? {});
+/** The command's flags with an MCP server's `--permission` levels first: they reach a run on its agent, never in argv. */
+export const withAgentLevels = (command, flags) => {
+    const overrides = environmentOf(command).agent?.overrides ?? [];
+    return overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags;
+};
 /**
  * The input and output `readSecret` uses for this command: the run's own, so a prompt goes where the run's other
  * output goes and a test that captures it sees it. `readSecret(prompt, { ...secretInputOf(this), echo: true })`.
@@ -70,9 +75,7 @@ export const outputFor = (command) => {
 export const baseContext = (command, resolveSettings) => {
     const environment = environmentOf(command);
     const env = environment.env ?? process.env;
-    const flags = command.optsWithGlobals();
-    const overrides = environment.agent?.overrides ?? [];
-    const settings = resolveSettings(overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags, { env });
+    const settings = resolveSettings(withAgentLevels(command, command.optsWithGlobals()), { env });
     const { renderer, format, color, streams, compact, full } = resolveOutput({
         ...settings,
         env,
@@ -141,6 +144,17 @@ export const baseContext = (command, resolveSettings) => {
         },
     };
 };
+/**
+ * A shared group's command inside cli-core's run, with the settings of the app `run()` was given: recorded, and ended
+ * by `--timeout` (WC-LIFE-5, WC-LIFE-15). The group's own opener still decides whether it needs a profile. A program
+ * parsed without `run()` has no run to open, so `body` just runs.
+ */
+export const inCommandRun = (command, body) => {
+    const { resolveSettings } = environmentOf(command);
+    if (!resolveSettings)
+        return body(() => { });
+    return baseContext(command, (flags, options) => resolveSettings(flags, { ...options, needsProfile: false })).run(body);
+};
 /** `messages send` — the words that name commands, never the arguments: those can be a message. */
 const commandPath = (command) => {
     const words = [];

package/dist/cli/contract-templates.js

@@ -41,6 +41,7 @@ export const sharedCommandTemplate = (app, name) => {
                 },
                 accountId: 0,
                 write: unavailable,
+                inRun: unavailable,
             });
             const meetings = root.commands.find((command) => command.name() === "meetings");
             if (!meetings)

package/dist/cli/early-refusal.js

@@ -7,7 +7,7 @@ import { SendJournal, sendsPathFor } from "../sends/journal.js";
 import { CEILING_KEY, keyForCommand, levelFor, writeOfKey } from "../sends/permissions.js";
 import { newOperationId } from "../sends/send-id.js";
 import { commandPathOf } from "./command-contract.js";
-import { environmentOf } from "./context.js";
+import { withAgentLevels } from "./context.js";
 import { changesMessenger } from "./effects.js";
 import { refuseUnknownPermissionKeys } from "./permission-keys.js";
 import { NONE_NAMED, settingsFor } from "./settings.js";
@@ -33,7 +33,7 @@ export const refuseWriteBeforeConnecting = (action, { app, env, dryRun, resolve
     const key = keyForCommand(path);
     if (!key)
         return;
-    const settings = (resolve ?? settingsFor(app).resolveSettings)(action.optsWithGlobals(), {
+    const settings = (resolve ?? settingsFor(app).resolveSettings)(withAgentLevels(action, action.optsWithGlobals()), {
         env,
         needsProfile: false,
         readOnly: true,
@@ -91,9 +91,11 @@ export const refuseByCommandPermissions = (action, permissions, { app, env, dryR
     const preview = dryRun && app.messenger === false;
     if (lock && effects?.remote === "write" && !preview)
         throw readOnlyRefusal(lock, `run ${commandPathOf(action).join(" ")}`);
-    const flags = action.optsWithGlobals();
-    const overrides = environmentOf(action).agent?.overrides ?? [];
-    const settings = resolve(overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags, { env, needsProfile: false, readOnly: true });
+    const settings = resolve(withAgentLevels(action, action.optsWithGlobals()), {
+        env,
+        needsProfile: false,
+        readOnly: true,
+    });
     refuseUnknownPermissionKeys(action, settings, app.command, permissions);
     if (dryRun || settings.sources?.profile === NONE_NAMED)
         return;

package/dist/cli/index.d.ts

@@ -66,7 +66,7 @@ export { type CompactOptions, compactText, entityRows, GENERIC_ROW, type RowColu
 export { refuseUnknownKey } from "./config-command.js";
 export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
-export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, outputFor, provide, runBudgetOf, secretInputOf, } from "./context.js";
+export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, inCommandRun, outputFor, provide, runBudgetOf, secretInputOf, withAgentLevels, } from "./context.js";
 export { addContractInfo, type ContractEvidenceOptions, contractEvidence } from "./contract-evidence.js";
 export { sharedCommandTemplate } from "./contract-templates.js";
 export { type Closeable, withDeadline } from "./deadline.js";
@@ -115,7 +115,7 @@ export { type Saving, stored } from "./messenger/stored.js";
 export { dateOrNone } from "./messenger/tasks-command.js";
 export { MODEL_CATALOGUE_QUERY, type ModelCatalogueOptions } from "./model-catalogue-command.js";
 export { positiveCount, window, withPaging } from "./paging.js";
-export { type CommandPermissions, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
+export { type CommandPermissions, type ConditionalKey, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOptions, run } from "./program.js";
 export { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } from "./project-evidence.js";

package/dist/cli/index.js

@@ -57,7 +57,7 @@ export { compactText, entityRows, GENERIC_ROW, rowShapeOf, rowsOfEntity, SHARED_
 export { refuseUnknownKey } from "./config-command.js";
 export { checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";
-export { baseContext, environmentOf, outputFor, provide, runBudgetOf, secretInputOf, } from "./context.js";
+export { baseContext, environmentOf, inCommandRun, outputFor, provide, runBudgetOf, secretInputOf, withAgentLevels, } from "./context.js";
 export { addContractInfo, contractEvidence } from "./contract-evidence.js";
 export { sharedCommandTemplate } from "./contract-templates.js";
 export { withDeadline } from "./deadline.js";

package/dist/cli/permission-keys.d.ts

@@ -14,8 +14,16 @@ export interface CommandPermissions {
     extra: readonly PermissionKey[];
     /** cli-core's built-in levels and the CLI's own; they only ever tighten. */
     defaults: Readonly<Record<PermissionKey, Level>>;
-    /** The other keys a command's real run checks, so its `--dry-run` preview shows each: gcal's `api.calendar.*`. */
-    alsoChecks?: (path: readonly string[]) => readonly PermissionKey[];
+    /**
+     * The other keys a command's real run checks, so its `--dry-run` preview shows each: gcal's `api.calendar.*`. A
+     * key with `when` is checked only for some arguments, such as a stage that closes a deal: shown, never refused.
+     */
+    alsoChecks?: (path: readonly string[]) => readonly (PermissionKey | ConditionalKey)[];
+}
+/** A key a write checks only when its arguments ask for it; `when` says which, in a few words. */
+export interface ConditionalKey {
+    key: PermissionKey;
+    when: string;
 }
 /** Either way of naming a program's keys: a messenger's per-command mapping, or a declared CLI's own. */
 export type PermissionKeySource = PermissionKeyOf | CommandPermissions;