@wirecat/cli-core 0.539.0 → 0.540.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ shape of this file.
 
 ## Unreleased
 
+## 0.540.0 — 02.11.2026
+
+### Added
+
+- **`events export` without `--output` is a read over MCP and under the read-only lock.** It only prints the `.ics`
+  text, and MCP tools never offer `--output`. `writesFileOnlyWith(command, option)` marks a command whose only local
+  write is the file an owner-only option names: its effects stay a write (WC-CMD-17), `readsOverMcp` / `readsOverMcpAt`
+  count it as a read, and `<PREFIX>_READ_ONLY` refuses only a run that gives the option. Every MCP server now judges
+  `read` with `readsOverMcpAt`, which is `fetchesOnly` plus these; a CLI test that snapshots the catalogue with
+  `fetchesOnlyAt` should switch to it.
+- **An MCP list's `query` input names its fields.** It said "the fields are below", and no Fields section is sent
+  over MCP. It now reads cli-base's `queryDescription`: the fields, enum values, and which fields `-field:value`
+  leaves out. `events list`'s query declares `event_type` as `negatable` (cli-base), and `negatableOf(registry)`
+  gives `nativeTermLists` the same list, so the description and the filter cannot drift. `queryArgument` uses the
+  same sentence.
+- **`events list` and `events prepare` give `meta.now`, `meta.now_local` and `meta.timezone` (WC-TIME-7)**, from the
+  host's clock and zone, so an agent plans "tomorrow" from the real date.
+
+### Changed — may break callers
+
+- **cli-base 0.72.0.** `metaSchema` accepts `now` and `now_local`; a host that checks meta against an older cli-base's
+  strict schema drops the whole meta.
+
 ## 0.539.0 — 01.11.2026
 
 ### Added

package/dist/calendar/cli/index.js

@@ -1,10 +1,11 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate, 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, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
-import { ownerOnlyOption } from "../../cli/effects.js";
+import { ownerOnlyOption, writesFileOnlyWith } from "../../cli/effects.js";
 import { queryTerms, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
@@ -235,7 +236,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
         });
         print({
             ...eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }, opts.page), EVENT_ITEM_UNTRUSTED),
-            meta: await accountsMeta(deps.store, accounts, skipped, now()),
+            meta: { ...(await accountsMeta(deps.store, accounts, skipped, now())), ...clockMeta(now(), zone()) },
         }, command);
     });
     const exporter = example(withQuery(annotate(events.command("export"), { effects: deps.writeFile ? LOCAL_WRITE : LOCAL_READ }).description(`write stored events as iCalendar (.ics), at most ${EXPORT_MAX}: one with id:<id>, or those the query ` +
@@ -247,7 +248,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
         : ["events export id:42", "events export starts_at:[2026-11-02 TO 2026-11-09} NOT event_type:birthday"]));
     // Not over MCP: an agent would choose where on the owner's disk to write. It gets the text in the answer.
     if (deps.writeFile)
-        exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent"));
+        writesFileOnlyWith(exporter.addOption(ownerOnlyOption("--output <file>", "the file to write; printed in the answer when absent")), "output");
     exporter.action(async (words, opts, command) => {
         const filter = await eventsFilter(words, {
             store: deps.store,
@@ -297,7 +298,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
             ...(opts.limit === undefined ? {} : { limit: opts.limit }),
             ...(window.since === undefined ? {} : { since: window.since }),
         });
-        print({ ...prepared, meta: { ...meta, ...window.meta } }, command);
+        print({ ...prepared, meta: { ...meta, ...window.meta, ...clockMeta(now(), zone()) } }, command);
     });
     const searches = annotate(program.command("search").description("find stored things by text: events"), {
         effects: GROUP,

package/dist/calendar/mcp/index.js

@@ -30,7 +30,8 @@ export const calendarTools = [
         name: "events_list",
         description: "stored events, earliest first; `query` takes field terms joined by AND: starts_at (>=, <, or " +
             "[a TO b}), ends_at>=, changed_at>= (events new, moved or cancelled since, each with change and was), " +
-            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>; a date in the zone given, " +
+            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>, event_type:<kind>, and " +
+            "-event_type:<kind> to leave one kind out; a date in the zone given, " +
             "UTC when absent; without starts_at or ends_at, from today on",
         properties: {
             account_id: integer,

package/dist/calendar/prepare.d.ts

@@ -126,6 +126,8 @@ export declare const eventPreparation: (details: EventDetails, options: Preparat
         }[] | undefined;
         truncated?: boolean | undefined;
         timezone?: string | undefined;
+        now?: string | undefined;
+        now_local?: string | undefined;
         window?: {
             since?: string | undefined;
             until?: string | undefined;

package/dist/calendar/reads.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { dateRange, dayBoundary, queryError, queryFieldsOf, } from "@wirecat/cli-base/query";
-import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, typedQuery } from "../cli/list-query.js";
+import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, negatableOf, typedQuery, } from "../cli/list-query.js";
 import { event, eventChange, eventItem, listed, } from "../meetings/index.js";
 import { entriesOfList, fitting } from "../search/account-list.js";
 import { listContextOf } from "../services/search-kind.js";
@@ -92,6 +92,7 @@ export const EVENTS_QUERY = {
     backend: "native",
     fields: queryFieldsOf(event, {
         native: ["id", "starts_at", "ends_at", "changed_at", "overlapping", "calendar", "person", "event_type"],
+        negatable: ["event_type"],
         relations: {
             event_type: {
                 type: "enum",
@@ -156,7 +157,7 @@ export const eventsFilter = async (query, context) => {
     const { zone, now } = context;
     const span = (text) => ({ start: 0, end: text.length });
     const day = (date) => dayBoundary(date, zone, false, span(date));
-    const terms = nativeTermLists(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST, [], ["event_type"]);
+    const terms = nativeTermLists(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST, [], negatableOf(EVENTS_QUERY));
     const kinds = (nodes = []) => nodes.map(({ value }) => value.toLowerCase());
     const excluded = kinds(terms.get("-event_type"));
     if (excluded.length)

package/dist/cli/bot/mcp.js

@@ -3,7 +3,7 @@ import { CliError } from "@wirecat/cli-base";
 import { annotate, describeProgram } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { environmentOf } from "../context.js";
-import { changesAuthorityAt, fetchesOnlyAt, LOCAL_READ, REMOTE_WRITE } from "../effects.js";
+import { changesAuthorityAt, LOCAL_READ, REMOTE_WRITE, readsOverMcpAt } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
 import { serverEntry } from "../messenger/mcp-command.js";
 import { nextStep, rootOf } from "../steps.js";
@@ -37,7 +37,7 @@ export const botMcpCommand = (bot) => {
             bot,
             program: { run, commands: describeProgram(rootOf(this)) },
             authority: changesAuthorityAt(rootOf(this)),
-            fetchOnly: fetchesOnlyAt(rootOf(this)),
+            fetchOnly: readsOverMcpAt(rootOf(this)),
             settings: context.settings,
             levels: () => bot.resolveSettings(this.optsWithGlobals(), { env: context.env, kind: "bot" }).permissions,
             env: context.env,

package/dist/cli/effects.d.ts

@@ -50,6 +50,20 @@ export declare const changesStore: <T extends Command>(command: T) => T;
 export declare const fetchesOnly: (command: Command) => boolean;
 /** `fetchesOnly` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
 export declare const fetchesOnlyAt: (root: Command) => (path: readonly string[]) => boolean;
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export declare const writesFileOnlyWith: <T extends Command>(command: T, option: string) => T;
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export declare const readsOverMcp: (command: Command) => boolean;
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export declare const readsOverMcpAt: (root: Command) => (path: readonly string[]) => boolean;
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)

package/dist/cli/effects.js

@@ -1,4 +1,4 @@
-import { annotate, annotateOption, metaOf, stepTargets } from "@wirecat/cli-base/commands";
+import { annotate, annotateOption, metaOf, optionMetaOf, stepTargets, } from "@wirecat/cli-base/commands";
 import { Option } from "commander";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { keyForCommand } from "../sends/permissions.js";
@@ -93,6 +93,36 @@ export const fetchesOnlyAt = (root) => (path) => {
         at = at?.commands.find((one) => one.name() === word);
     return at !== undefined && fetchesOnly(at);
 };
+const FILE_OPTION = new WeakMap();
+/**
+ * Marks a command whose only local write is the file one owner-only option names (`events export --output`): its
+ * effects stay a write, as WC-CMD-17 asks, but a run without the option only reads. An MCP tool never offers the
+ * option, so it runs through `read`; `<PREFIX>_READ_ONLY` refuses only a run that gives it. `option` is the option's
+ * attribute name, `output`.
+ */
+export const writesFileOnlyWith = (command, option) => {
+    const flag = command.options.find((one) => one.attributeName() === option);
+    if (!flag || optionMetaOf(flag).mcp !== false)
+        throw new Error(`${command.name()}: writesFileOnlyWith needs --${option} added first, as an owner-only option`);
+    FILE_OPTION.set(command, option);
+    return command;
+};
+const writesFileNow = (command) => {
+    const option = FILE_OPTION.get(command);
+    return option === undefined || command.opts()[option] !== undefined;
+};
+/**
+ * What an MCP server runs through `read`: a command that only fetches into the store (`fetchesOnly`), and one whose
+ * only write is a file the tool cannot name (`writesFileOnlyWith`).
+ */
+export const readsOverMcp = (command) => fetchesOnly(command) || FILE_OPTION.has(command);
+/** `readsOverMcp` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export const readsOverMcpAt = (root) => (path) => {
+    let at = root;
+    for (const word of path)
+        at = at?.commands.find((one) => one.name() === word);
+    return at !== undefined && readsOverMcp(at);
+};
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)
@@ -103,7 +133,8 @@ export const isStoreChange = (command) => {
     return ((effects?.remote === "none" || STORE_WRITES.has(command)) &&
         effects?.local === "write" &&
         !KEPT_UNDER_LOCK.has(command) &&
-        !changesAuthority(command));
+        !changesAuthority(command) &&
+        writesFileNow(command));
 };
 export const STORE_CHANGE_REFUSAL = "change the message store";
 /** ` --dry-run` where the program has it, so an example of a command that calls a provider calls nothing. */

package/dist/cli/envelope.d.ts

@@ -95,6 +95,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
@@ -148,6 +150,8 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;

package/dist/cli/index.d.ts

@@ -66,7 +66,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { type CliEntry, type EntryContext, type EntryIo, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
@@ -78,7 +78,7 @@ export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIREC
 export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, type McpServerOptions, type McpServerTarget, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";

package/dist/cli/index.js

@@ -58,7 +58,7 @@ export { sharedCommandTemplate } from "./contract-templates.js";
 export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
-export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, storeChangeRefusal, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, fetchesOnly, fetchesOnlyAt, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, previewFlag, REMOTE_READ, REMOTE_WRITE, reachesOtherService, readsOverMcp, readsOverMcpAt, refuseUnderReadOnly, storeChangeRefusal, writesFileOnlyWith, } from "./effects.js";
 export { startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
@@ -70,7 +70,7 @@ export { firstScreen, installHelp, WIRECAT_TOOLS } from "./help/first-screen.js"
 export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, negatableOf, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";

package/dist/cli/list-query.d.ts

@@ -4,6 +4,8 @@ import * as v from "valibot";
 import { type ListBody, type ListInput } from "./envelope.js";
 import type { Settings } from "./settings.js";
 export declare const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export declare const QUERY_ARGUMENT = "field:value terms that narrow the list \u2014 the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -31,7 +33,9 @@ export declare const pageOf: ({ limit, page, all }: Pick<Settings, "limit" | "pa
 /** A page-numbered list's answer; under `--all` its limit is what it holds. */
 export declare const pagedList: <T>(command: string, { limit, page, all }: Pick<Settings, "limit" | "page" | "all">, { items, has_more, ...rest }: Omit<ListInput<T>, "limit" | "page" | "cursor">) => ListBody<T>;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, "field:value terms; this list filters by none yet, so any term is refused" | `field:value terms joined by AND that narrow the list; fields: ${string}; e.g. ${string}` | `field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <); fields: ${string}; e.g. ${string}`>]>, undefined>;
+export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8192, undefined>, v.DescriptionAction<string, string>]>, undefined>;
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export declare const negatableOf: (registry: QueryRegistry) => string[];
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.

package/dist/cli/list-query.js

@@ -1,9 +1,11 @@
 import { annotate } from "@wirecat/cli-base/commands";
-import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
+import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryDescription, queryError, queryFieldsOf, timezoneOf, validateQuery, } from "@wirecat/cli-base/query";
 import * as v from "valibot";
 import { queryWordsAfterOptions } from "../meetings/cli/index.js";
 import { listOf } from "./envelope.js";
 export const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
+/** `[query...]`'s help, which points at the Fields section; an MCP tool has none and says the fields instead. */
+export const QUERY_ARGUMENT = "field:value terms that narrow the list — the fields are below";
 /**
  * A list that narrows by one query: `[query...]` last, a Fields section in its help, and the fields in
  * `commands --json`. The registry is checked here, so a field whose example does not run fails at startup.
@@ -12,9 +14,7 @@ export const withQuery = (command, registry) => {
     const query = defineQuery(registry);
     annotate(command, { query, output: { entity: registry.entity } });
     const shown = askable(query);
-    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0
-        ? "field:value terms that narrow the list — the fields are below"
-        : "field:value terms; this list filters by none yet");
+    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0 ? QUERY_ARGUMENT : "field:value terms; this list filters by none yet");
     if (shown.length > 0)
         command.addHelpText("after", `\n${fieldsHelp({ ...query, fields: shown }, LIST_QUERY_GUIDE)}`);
     return command;
@@ -97,14 +97,11 @@ export const pagedList = (command, { limit, page, all }, { items, has_more, ...r
 /** The fields a list can be narrowed by: a provider list only those its source answers. */
 const askable = (registry) => registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
 /** An MCP list's `query` argument: the language the CLI list takes after its arguments. */
-export const queryArgument = (registry) => {
-    const fields = askable(registry);
-    return v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(fields.length === 0
-        ? "field:value terms; this list filters by none yet, so any term is refused"
-        : `${registry.backend === "native"
-            ? "field:value terms joined by AND that narrow the list"
-            : "field:value terms that narrow the list (Lucene: AND OR NOT, [a TO b], > <)"}; fields: ${fields.map((field) => field.name).join(", ")}; e.g. ${fields[0]?.example ?? ""}`)));
-};
+export const queryArgument = (registry) => v.optional(v.pipe(v.string(), v.maxLength(QUERY_LIMITS.bytes), v.description(queryDescription(registry))));
+/** The fields a native list can also leave out, `-field:value`: what `nativeTermLists` keeps under `-field`. */
+export const negatableOf = (registry) => askable(registry)
+    .filter((field) => field.negatable)
+    .map((field) => field.name);
 /**
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.

package/dist/mcp/agent.js

@@ -1,11 +1,13 @@
 import { Readable } from "node:stream";
 import { CliError, captureStreams, errorObjectOf } from "@wirecat/cli-base";
 import { flatten, } from "@wirecat/cli-base/commands";
+import { queryDescription } from "@wirecat/cli-base/query";
 import { writes } from "@wirecat/cli-base/standards";
 import { VOCABULARY } from "@wirecat/cli-base/standards/tables";
 import * as v from "valibot";
 import { commandAvailability } from "../cli/command-availability.js";
 import { changesMessenger } from "../cli/effects.js";
+import { QUERY_ARGUMENT } from "../cli/list-query.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
 import { newRunId } from "../runs/run.js";
 import { enclosingTraceId, inRun, traceOf } from "../runs/scope.js";
@@ -78,10 +80,17 @@ const optionField = (option, long, negated) => {
         },
     };
 };
-const argumentField = (argument) => {
+/** A list's query names its fields here: the help's Fields section, which its description points to, is not sent. */
+const argumentField = (argument, query) => {
+    const own = argument.description || argument.name;
+    const about = query && argument.name === "query"
+        ? own === QUERY_ARGUMENT
+            ? queryDescription(query)
+            : `${own}; ${queryDescription(query)}`
+        : own;
     const one = argument.choices
         ? v.pipe(v.picklist(argument.choices), v.description(argument.description))
-        : text(argument.description || argument.name);
+        : text(about);
     return {
         name: snake(argument.name),
         required: argument.required,
@@ -109,7 +118,7 @@ const stdinField = ({ name, description, json }) => ({
     argv: () => [],
 });
 const fieldsOf = (info, { omit = [], offline = false, stdin }) => {
-    const fields = info.arguments.map(argumentField);
+    const fields = info.arguments.map((argument) => argumentField(argument, info.query));
     const read = stdin?.(info.path);
     if (read)
         fields.push(stdinField(read));

package/dist/mcp/app-server.js

@@ -4,7 +4,7 @@ import { CliError, mcpErrorResult } from "@wirecat/cli-base";
 import { describeProgram } from "@wirecat/cli-base/commands";
 import { skillResource } from "@wirecat/cli-base/skill";
 import { environmentOf } from "../cli/context.js";
-import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, judgedTargets, readsOverMcpAt } from "../cli/effects.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { rootOf } from "../cli/steps.js";
 import { mcpUrlOf } from "../http/public-url.js";
@@ -46,7 +46,7 @@ export const createAppServer = (command, context, options) => {
         currentLevels: levels,
         readOnly: readOnly(),
         authority,
-        fetchOnly: fetchesOnlyAt(root),
+        fetchOnly: readsOverMcpAt(root),
         permissions: options.permissions,
     });
     const availability = (one) => () => {

package/dist/mcp/server.js

@@ -8,7 +8,7 @@ import * as v from "valibot";
 import { findCommand } from "../cli/command-contract.js";
 import { environmentOf } from "../cli/context.js";
 import { refuseWriteBeforeConnecting } from "../cli/early-refusal.js";
-import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, judgedTargets, readsOverMcpAt } from "../cli/effects.js";
 import { itemOf } from "../cli/envelope.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { recalledAccount } from "../cli/messenger/accounts.js";
@@ -127,7 +127,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         readOnly: readOnlyLockOf(app, context.env) !== undefined,
         keyOf,
         authority,
-        fetchOnly: fetchesOnlyAt(root),
+        fetchOnly: readsOverMcpAt(root),
         offline: true,
         stdin,
     }).map((one) => "sync_first" in one.input.entries && !syncAllowed(one.path)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.539.0",
+  "version": "0.540.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -251,7 +251,7 @@
     "@types/node": "^22.20.5",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "@wirecat/cli-base": "0.71.0",
+    "@wirecat/cli-base": "0.72.0",
     "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
     "commander": "15.0.0",
     "cspell": "10.4.0",
@@ -271,7 +271,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.71.0 <0.72.0",
+    "@wirecat/cli-base": ">=0.72.0 <0.73.0",
     "commander": ">=15"
   },
   "bin": {