@thenavidm/slipway 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.7, 2026-10-05: what Threads and ThriveCart needed, and what Substack and WordPress will
+
+- **`riskFor`: a write whose arguments decide its risk.** Publishing is destructive and saving a draft is a write, from the same tool. `risk` stays the highest a call can be, which is what clients see in annotations and listings; the guard, the approval and the audit log go by the call, and only a destructive call needs confirming. WordPress's post tools need it: 1.1 confirmed publishing and not drafting.
+- **`onServe`: work that belongs to a running server.** It runs once the server is answering, over stdio or HTTP, and never for a CLI command, with the context and the server's logger; a throw is logged and the server keeps serving. Threads uses it to warn that a token expires this week, and Substack's queue of scheduled Notes needs it.
+- **A tool's own consequence.** `consequence` replaces "is public or cannot be undone" in the refusal and the approval form. ThriveCart's refund said it "is public" on Slipway and now says it "moves money or ends a customer's access and cannot be undone", as its own release did.
+- **`which` lists only the close matches.** Results scoring at least half of the best one, and always the top three. On Threads, "publish a post staged earlier" printed ten lines, 1,077 characters, where three carried the answer.
+- **`<PREFIX>_TOOLSETS` is listed only when some tool has a toolset.** With none, every tool is always on and the switch does nothing, so help and `agent-context` stop offering it.
+- **Tests from the servers that moved.** ThriveCart's cases for `--select` paths that share a head and for a list of choices typed as repeated words now run here, where that code lives.
+
+## 0.1.6, 2026-10-05: what Mastodon's move needed
+
+- **`login` runs the app's own sign-in, with the words after it.** `mastodon-cli login mastodon.social --oob` hands `mastodon.social --oob` to Mastodon's flow, which registers an app on that instance and signs in. A flow given with `usage` and `help` shows them in help, `login --help` and `agent-context`, so nobody has to guess that it takes an instance.
+- **Terminal commands beside the tools.** `commands` adds commands such as `logout` to the CLI only. Each is listed in help, `agent-context` and tab completion, `slipway check` fails one named like a built-in or a tool, and an MCP client never sees it.
+- **Tuning stays out of the way.** A setting marked `tuning: true`, such as a timeout with a working default, is named on one line of help and left out of what `install` writes. On Mastodon, `install claude-code` told people to set 13 variables and now names the 6 that connect an account, and the general help is 64 tokens shorter.
+- **`httpPort` sets the default port for `--http`.** A server that shipped another default, such as 8000, keeps it after the move; `<PREFIX>_HTTP_PORT` and `--port` still override it.
+- **`doctorNetwork` calls the service on every `doctor`.** Doctor stays local unless `--network` is passed, which keeps it quick and spends no requests. Mastodon's most common failure is a token without the `write` scope, which only a request finds, and its docs have always told people to run plain `doctor` for it.
+- **The MCP binary's help names the CLI binary for the command list.** `mastodon-mcp --help` said a bare `mastodon-mcp` lists the commands, when it starts the server. Every hint that says where to list the commands now names the CLI binary.
+- **Advertised schemas leave out Zod 4's safe-integer bounds.** Zod 4 gives every whole number `maximum: 9007199254740991` and its negative unless the schema sets its own. They tell a client nothing, so they are left out of what it receives; three were in Mastodon's tool list. Validation still runs on the full schema.
+
 ## 0.1.5, 2026-10-04: what Bluesky's move found
 
 - **A request that never got an answer exits 5.** A failed fetch, a refused connection or a DNS failure mapped to exit 1, "unexpected error", so a script that retries on 5 gave up instead. Bluesky 1.2.3 exited 5 for an unreachable host, 0.1.4 made it 1, and it is 5 again.

package/README.md

@@ -213,6 +213,8 @@ The context is built on the first call that needs it, never at startup, and so i
 | `output` | Optional. Results are validated against it and sent as `structuredContent` |
 | `risk` | `read`, `write` (easy to undo) or `destructive` (public, irreversible, or both) |
 | `requireConfirm` | Defaults to true for destructive tools. Set it on a write that spends money |
+| `riskFor` | `(args) => risk`, when the arguments decide it: publishing is destructive, saving a draft is a write. `risk` stays the highest, which clients see; the guard, confirmation and audit log go by the call |
+| `consequence` | What a confirmed call does, in the tool's own words for the refusal and the approval form: "moves money and cannot be undone". Defaults to "is public or cannot be undone" |
 | `idempotent`, `openWorld` | Annotation hints. Reads are idempotent by default; every tool is open world unless it never leaves the machine |
 | `tags` | Toolsets this tool belongs to. A tool with no tags is always on |
 | `summary` | One line for the refusal message and the audit log: "delete note 7" |
@@ -388,10 +390,11 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> which <words>` | Find the command for a task, by what it does |
 | `<cli> schema <command>` | The JSON Schema an MCP client receives. `--output` for the result's |
 | `<cli> agent-context` | Commands, flags, risk, examples, exit codes and settings as JSON. `--brief` for just the commands, which ones write or need `--confirm`, and the exit codes |
-| `<cli> doctor` | Check the setup. `--network` also calls the service |
-| `<cli> login` | How to connect an account |
+| `<cli> doctor` | Check the setup. `--network` also calls the service, which an app with `doctorNetwork` does every time |
+| `<cli> login` | How to connect an account: printed steps, or the app's own sign-in flow with the words after `login` |
 | `<cli> install <client>` | Add the MCP server to a client. See [Add it to a client](#10-add-it-to-a-client) |
 | `<cli> data` | The local cache and synced lists: `sync`, `search`, `sql`, `clear` |
+| `<cli> <command>` from `commands` | A terminal command the app adds, such as `logout`. Listed in help and `agent-context`, never sent to an MCP client |
 | `<cli> completion bash` | Tab completion for bash, zsh or fish |
 
 Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
@@ -426,10 +429,12 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 | Run | Serves |
 |---|---|
 | `<mcp>` | MCP over stdio, what a client launches |
-| `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health` |
+| `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health`. The app's `httpPort` replaces 8787, for a server that shipped another default |
 
 HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
 
+Work that belongs to a running server goes in `onServe(ctx, log)`, which runs once the server is answering over either transport and never for a CLI command: a queue that publishes on time, or a warning that a token expires this week. A throw there is logged and the server keeps serving.
+
 Resources and prompts are optional and take a few lines each:
 
 ```ts
@@ -457,7 +462,7 @@ notes-cli install cursor --dry-run
 | `vscode` | `.vscode/mcp.json` | VS Code asks for each credential once and stores it securely |
 | `gemini` | `~/.gemini/settings.json`, or `.gemini/settings.json` | `${NAME}` references, which Gemini CLI needs to pass anything named like a key |
 
-A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
+A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup. A setting marked `tuning: true`, such as a timeout with a working default, stays out of the entry, so it carries only what connects an account.
 
 ## 11. Large catalogs
 
@@ -539,7 +544,7 @@ const mcp = await connect(app, { era: "modern", elicit: () => ({ action: "accept
 
 ## Environment variables
 
-Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs.
+Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs, and `install` passes on every one not marked `tuning`.
 
 | Variable | Default | What it does |
 |---|---|---|
@@ -549,10 +554,10 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | `<PREFIX>_CONFIRM` | `human` | `model` lets `confirm: true` alone confirm, for an agent with no person to ask |
 | `<PREFIX>_CACHE` | `1` | `0` never answers from the local cache |
 | `<PREFIX>_DATA_DIR` | the system's data folder | Where the local data file lives |
-| `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on |
+| `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on. Listed only when some tool has a toolset |
 | `<PREFIX>_SURFACE` | `full` | `search` lists three tools that find, describe and run the rest |
 | `<PREFIX>_TOOL_TIMEOUT_MS` | none | Give up on any tool after this long |
-| `<PREFIX>_HTTP_PORT` | `8787` | For `--http` |
+| `<PREFIX>_HTTP_PORT` | `8787`, or the app's `httpPort` | For `--http` |
 | `<PREFIX>_HTTP_HOST` | `127.0.0.1` | For `--http`. Any other address needs a token |
 | `<PREFIX>_HTTP_TOKEN` | none | Bearer token required by `--http` |
 | `<PREFIX>_DEBUG` | `0` | `1` prints debug lines on stderr |
@@ -565,6 +570,8 @@ See [CHANGELOG.md](CHANGELOG.md).
 
 | Server | Package | Covers |
 | --- | --- | --- |
+| [Bluesky](https://github.com/thenavidm/bluesky-mcp-cli) | [`@thenavidm/bluesky-mcp-cli`](https://www.npmjs.com/package/@thenavidm/bluesky-mcp-cli) 2.0.0 | Posting, threads, replies, the timeline, search, feeds, lists, notifications and the social graph |
+| [Mastodon](https://github.com/thenavidm/mastodon-mcp-cli) | [`@thenavidm/mastodon-mcp-cli`](https://www.npmjs.com/package/@thenavidm/mastodon-mcp-cli) 2.0.0 | Posting, editing, threads, timelines, search, lists, notifications and following, on any instance |
 | [Teachable](https://github.com/thenavidm/teachable-mcp-cli) | [`@thenavidm/teachable-mcp-cli`](https://www.npmjs.com/package/@thenavidm/teachable-mcp-cli) 3.0.0 | Courses, users, enrollments, pricing, coupons and transactions |
 
 Each server was measured against its previous release before it moved: startup, what a client receives, CLI exit codes, and tokens in Claude Code and Codex. Its README has the numbers.

package/dist/app.d.ts

@@ -48,6 +48,13 @@ export type ServiceSetting = {
     description: string;
     /** A credential: shown as set or unset, never printed. */
     secret?: boolean;
+    /**
+     * Tuning with a working default, such as a timeout or a retry count, or a
+     * second name for another setting. Listed in help and `agent-context`, but
+     * `install` leaves it out, so a client entry and its instructions hold only
+     * what connects an account.
+     */
+    tuning?: boolean;
 };
 export type CliIO = {
     stdout: (text: string) => void;
@@ -62,6 +69,18 @@ export type CliIO = {
     /** The folder a project-scoped `install` writes into. Defaults to the current one. */
     cwd?: string;
 };
+/** An interactive sign-in. It gets the words after `login` and returns an exit code. */
+export type LoginFlow = (io: CliIO, args: string[]) => number | Promise<number>;
+/** A terminal-only command an app adds beside its tools. */
+export type CliCommand = {
+    /** The word typed after the binary: `logout`. Must not be a tool's command or a built-in. */
+    name: string;
+    /** What it takes, as help shows it: `logout [<handle>]`. Defaults to the name. */
+    usage?: string;
+    /** One line: what it does. */
+    help: string;
+    run: (io: CliIO, args: string[]) => number | Promise<number>;
+};
 export type AppDefinition<Ctx> = {
     /** The service slug: "bluesky". Binaries default to bluesky-mcp and bluesky-cli. */
     name: string;
@@ -83,6 +102,12 @@ export type AppDefinition<Ctx> = {
     };
     /** The npm package that ships the binaries, so `install` can have a client start it with npx. */
     package?: string;
+    /**
+     * The port `--http` listens on when neither `--port` nor `<PREFIX>_HTTP_PORT`
+     * names one. 8787 when unset; a server that already shipped another default
+     * keeps it here.
+     */
+    httpPort?: number;
     /**
      * Builds what handlers need: an API client, config, accounts. Called once,
      * on the first call that needs it, so `--help` works with nothing configured.
@@ -93,12 +118,41 @@ export type AppDefinition<Ctx> = {
     prompts?: readonly PromptDefinition<Ctx>[];
     /** Whether any credentials are set. False makes `doctor` exit 10 and the server warn at startup. */
     configured?: (ctx: Ctx) => boolean | Promise<boolean>;
-    /** Service checks for `doctor`. `network` is true only when the person passed --network. */
+    /** Service checks for `doctor`. `network` is true only when the person passed --network, or `doctorNetwork` is set. */
     doctor?: (ctx: Ctx, options: {
         network: boolean;
     }) => DoctorCheck[] | Promise<DoctorCheck[]>;
-    /** How to sign in: printed instructions, or an interactive flow that returns an exit code. */
-    login?: string | ((io: CliIO) => number | Promise<number>);
+    /**
+     * Call the service on every `doctor`, not only with --network. Off by
+     * default, so doctor stays quick and spends no requests; on for a service
+     * whose most common failure only a request finds, such as a token missing
+     * a scope.
+     */
+    doctorNetwork?: boolean;
+    /**
+     * Runs once the server is answering, over stdio or HTTP, and never for a CLI
+     * command. For work that belongs to a running server, such as a queue that
+     * publishes on time, or a warning such as a token about to expire. It gets
+     * the context and the server's stderr logger; a throw is logged, never fatal.
+     */
+    onServe?: (ctx: Ctx, log: Logger) => void | Promise<void>;
+    /**
+     * How to sign in: printed instructions, or an interactive flow that returns an
+     * exit code. A flow gets the words after `login`: `mastodon-cli login mastodon.social`.
+     * A flow given with `usage` and `help` shows them in help, `login --help` and
+     * `agent-context`, so nobody has to guess that it takes an instance.
+     */
+    login?: string | LoginFlow | {
+        usage?: string;
+        help: string;
+        run: LoginFlow;
+    };
+    /**
+     * Terminal commands beyond the tools, such as `logout`, `auth` or `refresh`.
+     * An MCP client never sees them. Each is listed in help and `agent-context`,
+     * and gets the words after its name.
+     */
+    commands?: readonly CliCommand[];
     /** Values to mask in every result: API keys, tokens. */
     secrets?: (ctx: Ctx) => Array<string | undefined | null>;
     /**

package/dist/app.js

@@ -18,7 +18,7 @@ import { isContentResult } from "./result.js";
 import { formatIssues, validate } from "./schema.js";
 import { buildServer } from "./server.js";
 import { localDataTools } from "./sync.js";
-import { defineTool, isTool, summarize } from "./tool.js";
+import { defineTool, forCall, isTool, summarize } from "./tool.js";
 const SLUG = /^[a-z][a-z0-9-]{0,40}$/;
 export function stderrLogger(prefix, env) {
     const debug = /^(1|true|yes)$/i.test(env[`${prefix}_DEBUG`] ?? "");
@@ -140,7 +140,7 @@ export function slipway(definition) {
             assertVisible(tool, policy, envPrefix);
             const { confirm: _confirm, ...args } = rawArgs;
             const summary = summarize(tool, args);
-            new Guard(policy, options.surface, envPrefix).preflight(tool, summary);
+            new Guard(policy, options.surface, envPrefix).preflight(forCall(tool, args), summary);
             return summary;
         },
         async run(tool, rawArgs, options) {
@@ -152,8 +152,10 @@ export function slipway(definition) {
             const confirmedBy = options.approvedBy ?? (options.confirmed === true || confirm === true ? "flag" : undefined);
             const dryRun = options.dryRun === true;
             const summary = summarize(tool, args);
+            // What this call risks, which `riskFor` may put below the tool's declared risk.
+            const call = forCall(tool, args);
             const guard = new Guard(policy, options.surface, envPrefix);
-            guard.check(tool, { confirmedBy, dryRun, summary });
+            guard.check(call, { confirmedBy, dryRun, summary });
             const ctx = await app.context(env);
             const timeoutMs = tool.timeoutMs ?? policy.toolTimeoutMs;
             const withDeadline = () => deadlineSignal(options.signal, timeoutMs);
@@ -168,7 +170,7 @@ export function slipway(definition) {
                     surface: options.surface,
                     env,
                     dryRun,
-                    tool: { name: tool.name, risk: tool.risk },
+                    tool: { name: tool.name, risk: call.risk },
                     secrets,
                     log,
                     async progress(progress, total, message) {
@@ -182,7 +184,7 @@ export function slipway(definition) {
                 const wouldRun = tool.preview ? await tool.preview(args, toolContext) : args;
                 return { dry_run: true, tool: tool.name, summary, would_run: secrets.redactDeep(wouldRun) };
             }
-            const writes = tool.risk !== "read" || tool.requireConfirm;
+            const writes = call.risk !== "read" || call.requireConfirm;
             const cache = tool.cache && policy.cache ? { scope: app.dataScope(ctx), key: cacheKey(args), ttlSeconds: tool.cache.ttlSeconds } : undefined;
             if (cache && !options.refresh) {
                 const hit = await quietly(log, async () => (await app.localData(env)).cacheGet(cache.scope, tool.name, cache.key));
@@ -227,7 +229,7 @@ export function slipway(definition) {
                     result = await untilAborted(Promise.resolve(tool.handler(args, toolContext)), signal, timeoutMs, tool.name);
                 }
                 if (writes)
-                    guard.record(tool, summary, result?.done === false ? "started" : "done");
+                    guard.record(call, summary, result?.done === false ? "started" : "done");
                 await forget();
                 // Only data is cached. Images and files are fetched again.
                 if (cache && !isContentResult(result)) {
@@ -238,7 +240,7 @@ export function slipway(definition) {
             }
             catch (error) {
                 if (writes)
-                    guard.record(tool, summary, "failed");
+                    guard.record(call, summary, "failed");
                 await forget();
                 throw toSlipwayError(error);
             }

package/dist/check.js

@@ -50,6 +50,15 @@ export async function checkApp(app, options = {}) {
         add("warn", "schema", "ajv is not installed, so schemas were not checked against JSON Schema 2020-12. Add ajv as a dev dependency.");
     let totalBytes = 0;
     let largest;
+    for (const command of app.definition.commands ?? []) {
+        if (BUILTINS.includes(command.name) || app.find(command.name)) {
+            add("error", "names", `The terminal command '${command.name}' has the name of a built-in or a tool. Rename it.`);
+        }
+    }
+    const httpPort = app.definition.httpPort;
+    if (httpPort !== undefined && (!Number.isInteger(httpPort) || httpPort < 1 || httpPort > 65535)) {
+        add("error", "http", `httpPort is ${httpPort}, which is not a port number from 1 to 65535.`);
+    }
     for (const tool of app.allTools) {
         if (BUILTINS.includes(tool.command)) {
             add("error", "names", `'${tool.command}' is a built-in CLI command. Rename the tool.`, tool.name);
@@ -288,7 +297,7 @@ function checkDocs(app, file, add) {
             // The match may begin on the character before the binary, a newline included.
             const at = segment.offset + (match.index ?? 0) + (match[0].length - match[0].trimStart().length);
             const line = text.slice(0, at).split("\n").length;
-            if (BUILTINS.includes(command))
+            if (BUILTINS.includes(command) || app.definition.commands?.some((custom) => custom.name === command))
                 continue;
             const tool = app.find(command);
             if (!tool) {

package/dist/cli/completion.js

@@ -10,9 +10,9 @@ function globalFlags() {
 function toolFlags(tool) {
     return flagsFor(tool.jsonSchema).map((flag) => flag.flag);
 }
-function bash(bin, tools) {
+function bash(bin, tools, words) {
     const fn = `_${bin.replace(/[^A-Za-z0-9]/g, "_")}`;
-    const commands = [...tools.map((tool) => tool.command), ...BUILTINS].join(" ");
+    const commands = [...tools.map((tool) => tool.command), ...words].join(" ");
     const globals = globalFlags().join(" ");
     const cases = tools
         .map((tool) => `    ${tool.command}) COMPREPLY=( $(compgen -W "${[...toolFlags(tool), ...(tool.paginate ? ["--all", "--max-items"] : [])].join(" ")} ${globals}" -- "$cur") ) ;;`)
@@ -35,16 +35,16 @@ ${cases}
 complete -F ${fn} ${bin}
 `;
 }
-function zsh(bin, tools) {
+function zsh(bin, tools, words) {
     return `#compdef ${bin}
 # ${bin} completion for zsh, through zsh's bash compatibility layer.
 autoload -U +X bashcompinit && bashcompinit
-${bash(bin, tools)}`;
+${bash(bin, tools, words)}`;
 }
 function fishEscape(text) {
     return text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
 }
-function fish(bin, tools) {
+function fish(bin, tools, words) {
     const lines = [`# ${bin} completion for fish`, `complete -c ${bin} -f`];
     for (const tool of tools) {
         lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${tool.command}' -d '${fishEscape(tool.title)}'`);
@@ -52,20 +52,22 @@ function fish(bin, tools) {
             lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${tool.command}' -l '${flag.flag.slice(2)}' -d '${fishEscape(flag.help.slice(0, 80))}'`);
         }
     }
-    for (const builtin of BUILTINS)
-        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${builtin}'`);
+    for (const word of words)
+        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${word}'`);
     for (const flag of globalFlags())
         lines.push(`complete -c ${bin} -l '${flag.slice(2)}'`);
     return `${lines.join("\n")}\n`;
 }
 export function completionScript(app, shell, bin, env) {
     const tools = app.tools(env);
+    // The built-ins, then any terminal commands the app adds, such as logout.
+    const words = [...BUILTINS, ...(app.definition.commands ?? []).map((command) => command.name)];
     if (shell === "bash")
-        return bash(bin, tools);
+        return bash(bin, tools, words);
     if (shell === "zsh")
-        return zsh(bin, tools);
+        return zsh(bin, tools, words);
     if (shell === "fish")
-        return fish(bin, tools);
+        return fish(bin, tools, words);
     throw new UsageError(`completion expects bash, zsh or fish${shell ? `, got '${shell}'` : ""}.`, {
         hint: `Add \`source <(${bin} completion bash)\` to your shell's startup file.`,
     });

package/dist/cli/context.d.ts

@@ -24,6 +24,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     exit_codes: Record<number, string>;
     hidden_commands?: number | undefined;
     toolsets?: Record<string, string> | undefined;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         title: string;
@@ -79,6 +84,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     })[];
     toolsets?: Record<string, string> | undefined;
     hidden_commands: number;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         tool: string;

package/dist/cli/context.js

@@ -28,6 +28,13 @@ export function agentContext(app, env, bin, options = {}) {
     const names = policyEnvNames(app.envPrefix);
     const tools = app.tools(env);
     const hidden = app.allTools.length - tools.length;
+    // Terminal commands the app adds beside its tools, such as logout, and a sign-in flow that says what it takes.
+    const login = app.definition.login;
+    const extra = [...(typeof login === "object" ? [{ name: "login", ...login }] : []), ...(app.definition.commands ?? [])].map((command) => ({
+        command: command.name,
+        usage: `${bin} ${command.usage ?? command.name}`,
+        description: command.help,
+    }));
     const note = "--agent never confirms a write. A command that requires --confirm runs only when it is passed explicitly.";
     if (options.brief) {
         // Enough to pick a command: what each one is, and which write or need --confirm. The full read adds flags and settings.
@@ -38,6 +45,7 @@ export function agentContext(app, env, bin, options = {}) {
             usage: { run: `${bin} <command> [flags]`, help: `${bin} <command> --help`, note },
             exit_codes: EXIT_MEANINGS,
             ...(hidden ? { hidden_commands: hidden, ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}) } : {}),
+            ...(extra.length ? { extra_commands: extra } : {}),
             commands: tools.map((tool) => ({
                 command: tool.command,
                 title: tool.title,
@@ -71,18 +79,21 @@ export function agentContext(app, env, bin, options = {}) {
             })),
             { env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" },
             { env: names.allowDestructive, value: policy.allowDestructive, description: "allow public or irreversible writes" },
-            { env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" },
+            ...(app.allTools.some((tool) => tool.tags.length > 0)
+                ? [{ env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" }]
+                : []),
             { env: names.surface, value: policy.surface, description: "full tool list, or search for very large catalogs" },
             { env: names.auditLog, value: policy.auditLog ?? null, description: "file that records every attempted write" },
             { env: names.toolTimeoutMs, value: policy.toolTimeoutMs ?? null, description: "deadline for any tool" },
             { env: names.confirm, value: policy.confirm, description: "who confirms a confirmed call over MCP: human asks a person where the client can, model accepts confirm: true" },
-            { env: `${app.envPrefix}_HTTP_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: "port for --http, 8787 when unset" },
+            { env: `${app.envPrefix}_HTTP_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: `port for --http, ${app.definition.httpPort ?? 8787} when unset` },
             { env: `${app.envPrefix}_HTTP_HOST`, value: env[`${app.envPrefix}_HTTP_HOST`] ?? null, description: "address for --http, 127.0.0.1 when unset; any other needs a token" },
             { env: `${app.envPrefix}_HTTP_TOKEN`, set: Boolean(env[`${app.envPrefix}_HTTP_TOKEN`]), secret: true, description: "bearer token --http requires" },
             { env: `${app.envPrefix}_DEBUG`, value: /^(1|true|yes)$/i.test(env[`${app.envPrefix}_DEBUG`] ?? ""), description: "print debug lines on stderr" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
         hidden_commands: hidden,
+        ...(extra.length ? { extra_commands: extra } : {}),
         commands: tools.map((tool) => ({
             command: tool.command,
             tool: tool.name,

package/dist/cli/data.js

@@ -59,7 +59,7 @@ export async function runData(app, io, tokens, options) {
                 throw new UsageError("data sync expects the command to copy: data sync <command>.");
             const tool = app.find(command);
             if (!tool)
-                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (!tool.sync) {
                 const lists = app.allTools.filter((candidate) => candidate.sync).map((candidate) => candidate.command);
                 throw new UsageError(`${tool.command} is not a list that can be synced.`, { hint: `Lists that can: ${lists.join(", ") || "none"}.` });

package/dist/cli/help.js

@@ -191,11 +191,14 @@ export function renderGeneralHelp(app, bin) {
     // An agent often reads this first and pays for it again on every later step, so the
     // rarely needed commands share one line and Slipway's own settings say only what they do.
     const commands = [
-        [bin, "list the commands"],
+        [app.bins.cli, "list the commands"],
         [`${bin} <command> --help`, "what one takes, with examples"],
         [`${bin} which <words>`, "find the command for a task"],
-        [`${bin} doctor [--network]`, "check the setup and say what is wrong"],
-        [`${bin} login`, "how to connect an account"],
+        [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup and say what is wrong"],
+        typeof app.definition.login === "object"
+            ? [`${bin} ${app.definition.login.usage ?? "login"}`, app.definition.login.help]
+            : [`${bin} login`, "how to connect an account"],
+        ...(app.definition.commands ?? []).map((command) => [`${bin} ${command.usage ?? command.name}`, command.help]),
         [`${bin} install <client>`, "add the server to an MCP client; install --help lists them"],
         ...(cache || sync ? [[`${bin} data`, "what is kept on this machine; data clear [<command>] deletes it"]] : []),
         ...(sync
@@ -207,11 +210,14 @@ export function renderGeneralHelp(app, bin) {
             : []),
         [app.bins.mcp, "the MCP server over stdio; --http [--port N] for HTTP"],
     ];
+    // Tuning keeps a working default, so it is named on one line; agent-context says what each does.
+    const tuning = (app.definition.settings ?? []).filter((setting) => setting.tuning).map((setting) => setting.env);
     const settings = [
-        ...(app.definition.settings ?? []).map((setting) => [setting.env, setting.description]),
+        ...(app.definition.settings ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
         [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
-        [`${names.toolsets}=a,b`, "only these toolsets, or all"],
+        // With no tagged tool every tool is always on, so the switch would do nothing.
+        ...(app.allTools.some((tool) => tool.tags.length > 0) ? [[`${names.toolsets}=a,b`, "only these toolsets, or all"]] : []),
         [`${names.surface}=search`, "MCP lists three finder tools instead"],
         [`${names.auditLog}=<file>`, "log every attempted write"],
         [`${names.toolTimeoutMs}=<ms>`, "deadline for any tool"],
@@ -236,6 +242,7 @@ export function renderGeneralHelp(app, bin) {
         ``,
         `Settings:`,
         ...settings.map(row),
+        ...(tuning.length ? [`  Also: ${tuning.join(", ")}, described in agent-context.`] : []),
         ``,
         `Exit codes: ${EXIT.ok} ok, ${EXIT.error} unexpected, ${EXIT.usage} usage or refused, ${EXIT.notFound} not found, ${EXIT.auth} auth, ${EXIT.api} API, ${EXIT.rateLimited} rate limited, ${EXIT.notConfigured} not configured`,
         ``,

package/dist/cli/run.js

@@ -140,7 +140,8 @@ export async function runCli(app, argv, partial = {}) {
     const at = findCommand(argv);
     const command = at === -1 ? undefined : argv[at];
     const builtin = command !== undefined && BUILTINS.includes(command);
-    const tool = command !== undefined && !builtin ? app.find(command) : undefined;
+    const custom = command !== undefined && !builtin ? app.definition.commands?.find((candidate) => candidate.name === command) : undefined;
+    const tool = command !== undefined && !builtin && !custom ? app.find(command) : undefined;
     const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : []);
     let agent = argv.includes("--agent");
     try {
@@ -155,11 +156,16 @@ export async function runCli(app, argv, partial = {}) {
         }
         if (builtin)
             return await runBuiltin(app, io, command, rest, globals);
+        if (custom) {
+            if (globals.help)
+                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${custom.help}\n`);
+            return await custom.run(io, rest);
+        }
         if (!tool) {
-            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS];
+            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS, ...(app.definition.commands ?? []).map((c) => c.name)];
             const guess = didYouMean(command, candidates);
             throw new UsageError(`Unknown command '${command}'.${guess ? ` Did you mean '${guess}'?` : ""}`, {
-                hint: `Run \`${io.bin}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+                hint: `Run \`${app.bins.cli}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
             });
         }
         const seen = visibility(tool, app.policy(io.env));
@@ -196,6 +202,9 @@ async function runBuiltin(app, io, command, rest, globals) {
     // `<built-in> --help` explains the command instead of running it.
     if (globals.help && command === "install")
         return print(io, (await import("./install.js")).installHelp(app, io.bin));
+    const login = app.definition.login;
+    if (globals.help && command === "login" && typeof login === "object")
+        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${login.help}\n`);
     if (globals.help && command !== "help")
         return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
@@ -209,13 +218,13 @@ async function runBuiltin(app, io, command, rest, globals) {
                 return print(io, renderGeneralHelp(app, io.bin));
             const tool = app.find(target);
             if (!tool)
-                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             return print(io, renderToolHelp(tool, io.bin));
         }
         case "schema": {
             const tool = target ? app.find(target) : undefined;
             if (!tool)
-                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (rest.includes("--output")) {
                 if (!tool.output)
                     throw new UsageError(`${tool.command} declares no output schema.`);
@@ -229,20 +238,25 @@ async function runBuiltin(app, io, command, rest, globals) {
             const query = rest.filter((token) => !token.startsWith("-")).join(" ");
             if (!query)
                 throw new UsageError("which expects the words for what you want to do: which schedule a post");
-            const matches = searchTools(app.tools(io.env), query, 10);
+            // Only the close matches: on Threads the right command scored 20 and the eighth 9, and the
+            // ten-line list cost an agent more to read than the answer was worth.
+            const found = searchTools(app.tools(io.env), query, 10);
+            const best = found[0]?.score ?? 0;
+            const matches = found.filter(({ score }, index) => index < 3 || score >= best / 2);
             if (globals.format !== "auto") {
                 return print(io, json(globals, matches.map(({ tool, score }) => ({ command: tool.command, title: tool.title, risk: tool.risk, score: Number(score.toFixed(2)) }))));
             }
             if (!matches.length)
-                return print(io, `No command matches '${query}'. Run \`${io.bin}\` to see them all.`);
+                return print(io, `No command matches '${query}'. Run \`${app.bins.cli}\` to see them all.`);
             return print(io, matches.map(({ tool }) => toolLine(tool)).join("\n"));
         }
         case "doctor":
             return runDoctor(app, io, { network: rest.includes("--network"), json: globals.format !== "auto" });
         case "login": {
-            const login = app.definition.login;
             if (typeof login === "function")
-                return await login(io);
+                return await login(io, rest);
+            if (typeof login === "object")
+                return await login.run(io, rest);
             if (typeof login === "string")
                 return print(io, login);
             return print(io, `${app.title} reads its credentials from the environment. Run \`${io.bin} doctor\` to see what is missing.`);

package/dist/doctor.js

@@ -68,15 +68,16 @@ export async function runDoctor(app, io, options) {
             ...(configured ? {} : { fix: `Run \`${app.bins.cli} login\` to see how to connect an account.` }),
         });
     }
+    const network = options.network || app.definition.doctorNetwork === true;
     if (ctx !== undefined && app.definition.doctor) {
         try {
-            checks.push(...(await app.definition.doctor(ctx, { network: options.network })));
+            checks.push(...(await app.definition.doctor(ctx, { network })));
         }
         catch (error) {
             checks.push({ name: "Service check", ok: false, detail: app.secrets.redact(error?.message ?? String(error)) });
         }
     }
-    if (!options.network && app.definition.doctor) {
+    if (!network && app.definition.doctor) {
         checks.push({ name: "Network", ok: true, warn: true, detail: "not checked; run with --network to call the service" });
     }
     const failed = checks.filter((check) => !check.ok && !check.warn);

package/dist/guard.d.ts

@@ -43,4 +43,4 @@ export declare class Guard {
     record(tool: Tool, summary: string, outcome: GuardOutcome | "failed" | "done" | "started", confirmedBy?: ConfirmedBy): void;
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
-export declare function consequence(tool: Pick<Tool, "risk">): string;
+export declare function consequence(tool: Pick<Tool, "risk" | "consequence">): string;

package/dist/guard.js

@@ -85,5 +85,7 @@ export class Guard {
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
 export function consequence(tool) {
+    if (tool.consequence)
+        return tool.consequence;
     return tool.risk === "destructive" ? "is public or cannot be undone" : "has an effect that cannot be taken back";
 }

package/dist/install.js

@@ -207,7 +207,7 @@ export function planInstall(app, options, context) {
     }
     const launch = launchFor(app, { local: options.local, ...(context.entry ? { entry: context.entry } : {}), ...(context.platform ? { platform: context.platform } : {}) });
     const usesNpx = launch.command === "npx" || launch.args.includes("npx");
-    const settings = app.definition.settings ?? [];
+    const settings = (app.definition.settings ?? []).filter((setting) => !setting.tuning);
     const variables = settings.map((setting) => setting.env);
     const env = { forwarded: [], copied: [], toAdd: [] };
     const notes = [];

package/dist/schema.js

@@ -83,6 +83,25 @@ export const CONTROL_NAMES = ["confirm", "wait_seconds"];
 export const CONFIRM_DESCRIPTION = "Set true only when the user asked for exactly this action.";
 /** The schema already carries the range and the default, so the words only say what the number is for. */
 export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before returning it to check later.";
+/**
+ * Zod 4 gives every whole number the safe-integer bounds, `maximum:
+ * 9007199254740991` and its negative, unless the schema sets its own. They say
+ * nothing a client can use, so they are left out of what it receives.
+ * Validation still runs on the schema itself.
+ */
+function withoutSafeIntegerBounds(node) {
+    if (Array.isArray(node))
+        return node.map(withoutSafeIntegerBounds);
+    if (node === null || typeof node !== "object")
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if ((key === "maximum" && value === Number.MAX_SAFE_INTEGER) || (key === "minimum" && value === Number.MIN_SAFE_INTEGER))
+            continue;
+        out[key] = withoutSafeIntegerBounds(value);
+    }
+    return out;
+}
 /**
  * A schema as clients receive it, without the `$schema` line that names its
  * dialect. A client reads JSON Schema 2020-12 when no dialect is named, so
@@ -91,10 +110,8 @@ export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before re
 export function advertised(schema) {
     const std = schema["~standard"];
     const plain = (json) => {
-        if (!("$schema" in json))
-            return json;
         const { $schema: _dialect, ...rest } = json;
-        return rest;
+        return withoutSafeIntegerBounds(rest);
     };
     return {
         "~standard": {

package/dist/serve.d.ts

@@ -2,6 +2,7 @@
  * Serving an app over stdio, which every local client launches, or HTTP.
  */
 import { type App } from "./app.js";
+import type { Logger } from "./tool.js";
 /**
  * Serve over stdio.
  *
@@ -11,6 +12,11 @@ import { type App } from "./app.js";
  * set of tools that explain what to configure.
  */
 export declare function serveStdioApp(app: App, env: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Once the server is answering: say if nothing is configured, then run the
+ * app's `onServe`. Nothing here can hold up the handshake or stop the server.
+ */
+export declare function afterStart(app: App, env: NodeJS.ProcessEnv, log: Logger): Promise<void>;
 export type HttpOptions = {
     host: string;
     port: number;

package/dist/serve.js

@@ -27,23 +27,35 @@ export async function serveStdioApp(app, env) {
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
-    void warnIfUnconfigured(app, env, log.warn);
+    void afterStart(app, env, log);
 }
-async function warnIfUnconfigured(app, env, warn) {
+/**
+ * Once the server is answering: say if nothing is configured, then run the
+ * app's `onServe`. Nothing here can hold up the handshake or stop the server.
+ */
+export async function afterStart(app, env, log) {
+    let ctx;
     try {
-        const ctx = await app.context(env);
+        ctx = await app.context(env);
         if (app.definition.configured && !(await app.definition.configured(ctx))) {
-            warn(`Nothing is configured yet. Tools that need an account will say what is missing. Run \`${app.bins.cli} doctor\`.`);
+            log.warn(`Nothing is configured yet. Tools that need an account will say what is missing. Run \`${app.bins.cli} doctor\`.`);
         }
     }
     catch (error) {
-        warn(`Setup is incomplete: ${error.message} Run \`${app.bins.cli} doctor\`.`);
+        log.warn(`Setup is incomplete: ${error.message} Run \`${app.bins.cli} doctor\`.`);
+        return;
+    }
+    try {
+        await app.definition.onServe?.(ctx, log);
+    }
+    catch (error) {
+        log.warn(app.secrets.redact(error?.message ?? String(error)));
     }
 }
 export function httpOptions(app, env, argv) {
     const at = argv.findIndex((token) => token === "--port" || token.startsWith("--port="));
     const raw = at === -1 ? env[`${app.envPrefix}_HTTP_PORT`] : argv[at].includes("=") ? argv[at].split("=")[1] : argv[at + 1];
-    const port = Number(raw ?? 8787);
+    const port = Number(raw ?? app.definition.httpPort ?? 8787);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new UsageError(`--port expects a port number, got '${raw}'.`);
     return {
@@ -83,6 +95,7 @@ export async function serveHttpApp(app, env, options) {
     const port = address && typeof address === "object" ? address.port : options.port;
     const url = `http://${options.host.includes(":") && !options.host.startsWith("[") ? `[${options.host}]` : options.host}:${port}/mcp`;
     log.info(`listening on ${url}${options.token ? " (bearer token required)" : ""}`);
+    void afterStart(app, env, log);
     return {
         url,
         close: async () => {

package/dist/server.d.ts

@@ -8,7 +8,7 @@
 import { McpServer, type ToolAnnotations } from "@modelcontextprotocol/server";
 import type { App } from "./app.js";
 import type { Policy } from "./policy.js";
-import type { Tool } from "./tool.js";
+import { type Tool } from "./tool.js";
 /** Claude Code shows a person a permission prompt on every call to a tool carrying this, in any mode. */
 export declare const REQUIRES_USER_INTERACTION = "anthropic/requiresUserInteraction";
 /** Claude Code raises its result-size limit for a tool carrying this. */

package/dist/server.js

@@ -12,6 +12,7 @@ import { toSlipwayError, UsageError } from "./errors.js";
 import { errorResult, isPlainObject, toCallToolResult } from "./result.js";
 import { outputJsonSchema } from "./schema.js";
 import { firstSentence, searchTools } from "./search.js";
+import { forCall } from "./tool.js";
 /** Claude Code shows a person a permission prompt on every call to a tool carrying this, in any mode. */
 export const REQUIRES_USER_INTERACTION = "anthropic/requiresUserInteraction";
 /** Claude Code raises its result-size limit for a tool carrying this. */
@@ -82,14 +83,16 @@ export function buildServer(app, env) {
  * is what makes Claude Code prompt for it.
  */
 async function confirmFirst(server, app, tool, args, ctx, env, policy, listedForPerson) {
-    if (!tool.requireConfirm)
+    // A call whose arguments make it a plain write needs nobody's approval, even on a tool that can publish.
+    const call = forCall(tool, args);
+    if (!call.requireConfirm)
         return {};
     const route = confirmRoute(policy.confirm, clientView(server, ctx), listedForPerson);
     if (route === "client")
         return { approvedBy: "client" };
     if (route === "flag")
         return {};
-    const ask = await personApproval(app, tool, args, ctx, env);
+    const ask = await personApproval(app, call, args, ctx, env);
     return ask ? { ask } : { approvedBy: "person" };
 }
 function registerTool(server, app, tool, env, policy) {

package/dist/tool.d.ts

@@ -103,6 +103,20 @@ export type ToolDefinition<Ctx, I extends Schema, O extends Schema | undefined>
      * generation.
      */
     requireConfirm?: boolean;
+    /**
+     * The risk of one call, when its arguments decide it: publishing is
+     * destructive, saving a draft is a write. `risk` stays the highest a call can
+     * be, which is what clients see in annotations and listings. The guard, the
+     * confirmation and the audit log go by this, and with it only a destructive
+     * call needs confirming.
+     */
+    riskFor?: (args: InferOutput<I>) => Risk;
+    /**
+     * What a confirmed call does that cannot be taken back, as the refusal and
+     * the approval form put it: "moves money and cannot be undone". Defaults to
+     * "is public or cannot be undone" for a destructive tool.
+     */
+    consequence?: string;
     /** Toolsets this tool belongs to. A tool with no tags is always on. */
     tags?: string[];
     /** One line for the audit log and the refusal message: "post 'Hello' as @alice". */
@@ -146,6 +160,10 @@ export type Tool<Ctx = any> = {
     readonly idempotent: boolean;
     readonly openWorld: boolean;
     readonly requireConfirm: boolean;
+    /** The risk of one call, from its arguments. `forCall` applies it. */
+    readonly riskFor?: (args: any) => Risk;
+    /** What a confirmed call does that cannot be taken back, in the tool's own words. */
+    readonly consequence?: string;
     readonly tags: readonly string[];
     readonly examples: readonly ToolExample[];
     readonly positional: readonly string[];
@@ -191,4 +209,11 @@ export declare function isTool(value: unknown): value is Tool;
  * arguments have been anywhere near the handler.
  */
 export declare function summarize(tool: Pick<Tool, "summary" | "title">, args: Record<string, unknown>): string;
+/**
+ * The tool as one call sees it. With `riskFor`, the call's risk comes from its
+ * arguments, never above the declared one, and only a destructive call needs
+ * confirming. Like `summarize`, it runs before validation, so a `riskFor` that
+ * throws on odd arguments counts as the declared risk.
+ */
+export declare function forCall<Ctx>(tool: Tool<Ctx>, args: Record<string, unknown>): Tool<Ctx>;
 export {};

package/dist/tool.js

@@ -36,6 +36,12 @@ export function defineTool(definition) {
     }
     if (typeof definition.handler !== "function")
         throw new Error(`${where}: handler is required.`);
+    if (definition.riskFor !== undefined) {
+        if (typeof definition.riskFor !== "function")
+            throw new Error(`${where}: riskFor must be a function of the arguments.`);
+        if (definition.risk === "read")
+            throw new Error(`${where}: riskFor is for a write whose arguments decide how far it reaches; a read has nothing to decide.`);
+    }
     const job = definition.job;
     if (job) {
         if (definition.name.length > 57)
@@ -99,6 +105,8 @@ export function defineTool(definition) {
         idempotent: definition.idempotent ?? definition.risk === "read",
         openWorld: definition.openWorld ?? true,
         requireConfirm,
+        ...(definition.riskFor ? { riskFor: definition.riskFor } : {}),
+        ...(definition.consequence?.trim() ? { consequence: definition.consequence.trim().replace(/\.$/, "") } : {}),
         tags: Object.freeze([...(definition.tags ?? [])]),
         examples: Object.freeze([...(definition.examples ?? [])]),
         positional: Object.freeze([...(definition.positional ?? [])]),
@@ -149,3 +157,26 @@ export function summarize(tool, args) {
         return fallback;
     }
 }
+const REACH = { read: 0, write: 1, destructive: 2 };
+/**
+ * The tool as one call sees it. With `riskFor`, the call's risk comes from its
+ * arguments, never above the declared one, and only a destructive call needs
+ * confirming. Like `summarize`, it runs before validation, so a `riskFor` that
+ * throws on odd arguments counts as the declared risk.
+ */
+export function forCall(tool, args) {
+    if (!tool.riskFor)
+        return tool;
+    let risk = tool.risk;
+    try {
+        const asked = tool.riskFor(args);
+        if (asked in REACH && REACH[asked] < REACH[tool.risk])
+            risk = asked;
+    }
+    catch {
+        // The declared risk is the safe answer.
+    }
+    if (risk === tool.risk)
+        return tool;
+    return { ...tool, risk, requireConfirm: tool.requireConfirm && risk === "destructive" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
   "type": "module",
   "license": "Apache-2.0",