@wirecat/cli-base 0.50.3 → 0.51.0

package/docs/standards/mcp.md

@@ -2,17 +2,13 @@
 
 ## Scope
 
-How a CLI serves agents over MCP: the tools it exposes, how they are built from the command tree, and what each
-permission level makes visible.
+How a CLI serves agents over MCP: the tools it exposes, how they are built from the command tree, and how permission levels control availability and execution.
 
 **MCP** (Model Context Protocol) is how an AI agent asks a program what it can do (`tools/list`) and then calls it. A
 **tool** is a name, a description, an input schema and the code that runs when it is called.
 
-This page has two parts:
-
-1. **Rules** — what is true on cli-core 0.321.0, the version these rules were checked against. Each has a `WC-MCP` id.
-2. **[Planned — not built yet](#planned--not-built-yet)** — the approved design that replaces hand-written tools. It
-   has no ids, because it is not true yet. Do not write code that expects it.
+The rules below define the MCP contract. [Tools generated from commands](#tools-generated-from-commands)
+explains how cli-core builds and filters the catalogue.
 
 Rule ids on this page are `WC-MCP-<n>`. How to read a rule, how ids work and which rule wins are in the
 [index](README.md).
@@ -86,18 +82,25 @@ Both declare the answer envelope (a list `{ items, page, … }` or one thing `{
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-MCP-6 · The profile's permissions decide what is offered and what runs
+<a id="wc-mcp-6--the-profiles-permissions-decide-what-is-offered-and-what-runs"></a>
 
-A command whose level is `deny` is not offered. Under `readonly`, writing commands are not offered. A command is also
-not offered when a key it reads, such as `messages`, is `deny`. The list is built when the server starts. The personal
-server reads the permissions again on every call, so a stricter level refuses the next call at once; a command allowed
-after start-up appears only after a restart.
+### WC-MCP-6 · Permissions change availability, not command existence
 
-- **Why:** an agent is not handed a tool that cannot work, and the owner narrows an agent without touching code.
-- **Enforced by:** `cli-core: src/mcp/mcp.test.ts`.
-- **Example:** with `{ "messages.send": "deny" }`, `tools_search` does not list `messages send`.
-- **Exceptions:** the bot server reads the permissions once, at start-up; a change needs a restart.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-772.
+CLI help and discovery retain commands regardless of profile permissions. MCP listings and searches also
+retain commands whose own permission, a required read permission or a process read-only lock prevents execution.
+They report current `availability`: `available: false`, a reason and the permission key where applicable.
+Permitted commands report `available: true`. Arguments and answer schemas remain discoverable either way.
+
+Availability is permission information, not an execution grant. Every call rechecks the current rules before
+performing work. Changes to profile levels update discovery availability without erasing commands or requiring
+agents to conclude that a capability does not exist. With a named profile, CLI help and discovery annotate the
+same local permission decision; discovery without a profile remains independent of account configuration.
+
+- **Why:** an agent must distinguish a supported capability that is currently blocked from an unknown command.
+- **Enforced by:** `cli-core: src/mcp/mcp.test.ts`; custom servers need the same contract.
+- **Example:** `{ "messages.send": "deny" }` leaves `messages send` searchable with `availability: { available: false, reason: "the profile denies messages.send", permission: "messages.send" }`; calling it returns `permission_error`.
+- **Exceptions:** transport exclusions, such as an interactive login or an unbounded process, are independent of permissions and remain documented.
+- **Applies to:** all CLIs. **Since:** cli-core 0.408.0. **Rulings:** owner, 2026-10-24.
 
 ### WC-MCP-7 · Over MCP, `ask` counts as `allow`, and no server shows a form
 
@@ -187,26 +190,22 @@ and every write goes through the write guard ([WC-PERM-13](permissions.md#wc-per
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.44.0. **Rulings:** none.
 
-## Planned — not built yet
+<a id="planned--not-built-yet"></a>
 
-The owner chose this design on 2026-10-17 (NEED-1408, NEED-1411). It is being built in cli-core. Until a cli-core
-release says it is done, the rules above describe what runs.
+## Tools generated from commands
 
-What will change:
+cli-core builds its personal and bot MCP catalogues from the command tree with `toolsFromCommands`
+(`src/mcp/agent.ts`). Permission keys limit what each profile can call, including writes.
 
 - **Tools come from commands.** The catalogue is generated from the command tree, the same data as `commands --json`.
   A call runs the command itself, in-process, and hands back the answer object. Permissions, `ask`, effects, answers
-  and errors are then the CLI's own, because they are the same code. Hand-written tools are deleted.
+  and errors are the CLI's own, because they are the same code. Calls share the CLI execution path.
 - **`mcp: false` hides a command from MCP servers.** It is set on a command or a group and covers everything below it.
   Agents that use the CLI directly are not affected.
-  - **Built today:** the field exists in cli-base's `CommandMeta` since cli-base 0.40.4, and `commands --json` shows
-    `mcp: false` on each command it reaches.
-  - **Not built today:** no MCP server reads it yet, so setting it hides nothing.
+  `commands --json` shows `mcp: false` on each command it reaches, and cli-core omits it from the catalogue.
 - **`mcp: false` on an option** leaves that option out of the tool's input. The first use is
   `messages delete --for-everyone`, because an agent never deletes for everyone ([WC-PERM-11](permissions.md)).
-  - **Built today:** cli-base's `annotateOption(option, { mcp: false })` sets it, and `commands --json` shows
-    `mcp: false` on that option alone.
-  - **Not built today:** no MCP server reads it yet, so setting it hides nothing.
+  cli-base's `annotateOption(option, { mcp: false })` sets it; cli-core omits that option from the tool input.
 - **Never offered, by rule:** a command with a `lifetime` (`persistent`, such as `serve` and `watch`, or `interactive`,
   such as `session start`). An agent call must return.
 - **One server per subtree.** The personal server is built from the program without its `bot` group; the bot server
@@ -214,7 +213,6 @@ What will change:
 - **The profile still decides at run time** what is listed (WC-MCP-6).
 - **The whole catalogue is pinned** in each CLI's `contracts/mcp-tools.json`, so a command that becomes visible to
   agents shows up as a diff in its pull request.
-- **Every surface moves**, in this order: drive, the bot servers, memo, zoom, then the tg and max personal servers.
 
 ## Sources
 

package/docs/standards/permissions.md

@@ -47,7 +47,7 @@ way for a command the owner types and for an agent over MCP. A config file that
 ### WC-PERM-2 · There are four levels: `deny`, `readonly`, `ask`, `allow`
 
 - `deny` — nothing, not even a read. The command answers `permission_error` (exit 5) before it connects, and an agent
-  is not offered the command.
+  still discovers the command, marked unavailable with its permission reason ([WC-MCP-6](mcp.md)).
 - `readonly` — reads work, writes answer `permission_error`. On a key that only writes, such as `messages.delete`, it
   is the same as `deny`.
 - `ask` — a write asks first. See WC-PERM-9 for a terminal and [WC-MCP-7](mcp.md) for an agent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.50.3",
+  "version": "0.51.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",