@inetafrica/open-claudia 2.7.5 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2.8.0
+- **Per-verb manifests — the gate now knows each verb's blast radius (Phase 5).** A tool may declare its verbs in the header (`verb: <name> [args] | <tier> | <doc>` — one line per verb); `tool run` then resolves the risk tier **per invoked verb** instead of whole-tool: `spaces unread` runs freely while `spaces upload` demands `--yes`, and `prod-k8s cert-status` is read-only while `cert-renew` stays write-gated. An **undeclared verb on a manifest tool is refused outright** regardless of flags (declare it before using it), `help`/no-verb is always read-only, and manifest-less tools keep the old whole-tool gate unchanged (fully backward compatible — older runners ignore `verb:` lines). `tool scaffold --verbs "list:read-only:doc,create:write:doc"` generates the manifest lines, a dispatcher entry per verb, and a TOOL.md verbs block; `tool show` lists the declared manifest. Migrated all 8 live verb-CLIs (clickhouse, inet-central-cli, inet-ops, kazee-chat, kticket, metabase, prod-k8s, spaces — 41 declared verbs) in the tools repo.
+- **Chat approval with the EXACT payload — destructive runs escalate to inline Approve/Deny.** `--yes-destructive` acknowledged the agent's *paraphrase* of a destructive action; now an unflagged destructive top-level `tool run` inside a bot task POSTs the literal resolved command line to the requesting channel via a new loopback `approval-request` kind — the user sees `open-claudia tool run <name> <args>` verbatim with ✅ Approve / ⛔ Deny buttons (owner-only, idempotent: a second press can't overturn the first). The CLI polls the file-backed record (`core/approvals.js`) and **fails closed**: timeout (5 min) or deny = refusal at exit 3; only an explicit approve proceeds, stamped `approvedVia: "chat-approval"` with `OPEN_CLAUDIA_APPROVED_TIER=destructive` exported for composition. Every run's history entry now records the acknowledged tier — auditable forever.
+- **Source fingerprint — you can't unknowingly run changed code.** Every clean exit stamps a sha256 of the executable into `state.json` (`verifiedHash`); the runner compares before each run and warns `⚠ unverified since change` when the source differs from the last green run (never blocks — the next successful run re-verifies). Surfaced in the per-turn tool condition line too.
+- **Tooling-mode switch (`/toolmode`, `open-claudia tooling-mode`).** Strict (default, fail-safe) = tool-first prompt + deny-gate blocks raw prod-surface commands. Relaxed = the older model: scripting permitted, deny-gate logs (`relaxed-pass` events keep the audit/KPI honest) without blocking, prompt block swaps to "tools preferred, not forced". Owner-only chat command with inline buttons; risk-tier gate and credential confinement apply in BOTH modes. Instant effect (mode file re-read per hook call), corrupt/missing file fails strict.
+- Test coverage: `test-tool-manifest.js` (manifest parse/scaffold round-trip, per-verb gate matrix incl. undeclared refusal + nested composition, fingerprint lifecycle, approvals idempotence + fail-closed timeout) and `test-tooling-mode.js` (strict denies / relaxed logs-and-allows / fail-safe strict).
+
+## v2.7.6
+- **/tooltrace now shows WHAT ran, not just THAT it ran.** The 🔧 line per tool run was `Ran tool: kticket` — no verb, no args, and one line per tool even when different verbs ran in the same turn. It now renders the **sanitized command shape** (quoted strings → `<text>`, ids/uuids → `<id>`, paths → `<path>` — same shaping the tool graph already computes, so this is display-only and free) plus a **human-readable doc sentence for that verb**: new `tools.verbDoc(name, verb)` parses the sentence mechanically from the tool's own leading comment block (the same docs `--help` prints — zero model cost, can't drift from the source). Both documented header shapes are recognised (indented description under the verb line, or same-line prose after 2+ spaces), with fallback to the tool description's first clause. Example: `🔧 kticket show <id> — One ticket in full`. Dedup is now per tool+verb per turn, so `kticket list` then `kticket show` both announce. Unit coverage in `test-tools.js` (both shapes, sentence cut, fallback, flag-token and unknown-tool cases).
+
 ## v2.7.5
 - **Tool composition with inherited approval — a composing tool cannot self-approve (Phase 4).** Higher-order tools may shell into lower tools (report → kticket + kchat), but the callee's risk gate stays intact: `tool run` now exports the tier the **outermost** invocation's flags acknowledged (`OPEN_CLAUDIA_APPROVED_TIER`) plus the call chain (`OPEN_CLAUDIA_TOOL_STACK`) into the child env, and a nested run gates on that inherited tier while **ignoring its own argv flags** — so a composing tool that hardcodes `--yes-destructive` in its source is refused with a message pointing at the outer re-run. An inherited tier passes through unchanged (depth-safe), a tool already in the chain is refused (cycle guard), and each nested run still stamps its own telemetry. Verified live: fabricated approval blocked at exit 3, legit outer `--yes-destructive` flowing through, self-call cycle caught at depth 1.
 - **`_lib/` shared plumbing with dependent journaling (Phase 4).** Genuinely shared code (central auth, mongo-exec) now lives in `tools/_lib` — tiny modules tools import via a literal `_lib/<name>` path, never tools themselves (the registry, surfacing index, and legacy migration all skip the `_` prefix). New `tool lib list|show|set`: `set` writes the module (secret-blocking, traversal-safe), finds every dependent by a boundary-safe source grep (`central-auth` matches `_lib/central-auth.js` and the `path.join` form, **not** `central-auth-v2`), journals each dependent `unverified since _lib change — re-verified by next real use`, and commits the lot in ONE commit naming the dependents — the PLAN's blast-radius rule, since a lib change can break several tools at once and health is verified by use, not smoke tests.

package/bin/cli.js

@@ -151,6 +151,24 @@ switch (command) {
     break;
   }
 
+  // Tooling-mode switch (strict = forced CLI / relaxed = scripting allowed).
+  // Mirrors /toolmode in chat; global file, effective on the next command.
+  case "tooling-mode": {
+    const tm = require(path.join(botDir, "core", "tooling-mode"));
+    const want = (args[0] || "").trim().toLowerCase();
+    if (!want) {
+      console.log(`Tooling mode: ${tm.getToolingMode()}`);
+    } else {
+      try {
+        console.log(`Tooling mode: ${tm.setToolingMode(want)}`);
+      } catch (e) {
+        console.error(e.message);
+        process.exit(1);
+      }
+    }
+    break;
+  }
+
   case "start": {
     const skipHealthCheck = args.includes("--skip-health") || args.includes("--force");
     const botFile = getBotFile();
@@ -302,7 +320,8 @@ switch (command) {
   }
 
   case "tool": {
-    require("./tool").run(args.slice(1));
+    Promise.resolve(require("./tool").run(args.slice(1)))
+      .catch((e) => { console.error(`tool command failed: ${e.message}`); process.exitCode = 1; });
     break;
   }
 

package/bin/tool.js

@@ -8,6 +8,7 @@
 //   open-claudia tool scaffold <name>            — create a new tool skeleton (dir + stub + TOOL.md)
 //       [--pack <dir>] [--desc "..."] [--risk read-only|write|destructive]
 //       [--requires "k1,k2"] [--tags "group"] [--usage "..."] [--lang node|bash]
+//       [--verbs "list:read-only:doc,create:write:doc"]  — per-verb manifest; undeclared verbs are refused
 //   open-claudia tool add <path> [--name n]      — register an existing script as a tool
 //       [--pack <dir>] [--desc "..."] [--risk tier] [--requires "k1,k2"] [--tags "group"] [--usage "..."]
 //   open-claudia tool set <name> [--desc ...]    — fix a tool's metadata in place
@@ -109,7 +110,7 @@ function reportSafety(t) {
   }
 }
 
-function run(args) {
+async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
@@ -193,6 +194,12 @@ function run(args) {
       if (t.pack) console.log(`Skill pack: ${t.pack}  (open-claudia pack show ${t.pack})`);
       if (t.tags && t.tags.length) console.log(`Tags: ${t.tags.join(", ")}`);
       console.log(`Risk: ${t.risk || "(undeclared — treated as write)"}`);
+      if (t.manifest && t.manifest.length) {
+        console.log("Declared verbs (undeclared verbs are refused; each gated by its own tier):");
+        for (const v of t.manifest) {
+          console.log(`  • ${v.name}${v.args ? " " + v.args : ""} — ${v.tier || t.risk || "write"}${v.doc ? ` — ${v.doc}` : ""}`);
+        }
+      }
       console.log(`Usage: open-claudia tool run ${t.name}${t.usage ? "   (" + t.usage + ")" : ""}`);
       if (t.requires.length) {
         const missing = tools.missingRequires(t);
@@ -348,18 +355,55 @@ function run(args) {
       if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
       const toolArgs = rest.slice(1);
 
-      // Risk-tier gate: write needs --yes, destructive needs --yes-destructive.
-      // The flag is passed through to the tool (which may have its own gate).
-      // Nested runs (a tool calling this tool) gate on the tier the OUTERMOST
-      // invocation approved instead — argv flags can't fabricate approval.
+      // Risk-tier gate, resolved per verb when the tool declares a manifest:
+      // write needs --yes, destructive needs --yes-destructive. Undeclared
+      // verbs on a manifest tool are refused outright. Nested runs (a tool
+      // calling this tool) gate on the tier the OUTERMOST invocation approved
+      // instead — argv flags can't fabricate approval.
       const gate = tools.runGate(t, toolArgs, process.env);
-      if (!gate.ok) { console.error(gate.message); process.exitCode = 3; return; }
+      let approvedVia = "";
+      if (!gate.ok) {
+        // Chat-approval fallback: an unflagged destructive top-level run inside
+        // a bot task escalates to the requesting channel with the EXACT command
+        // and inline Approve/Deny. Anything but an explicit approve = refusal.
+        const canAsk = gate.tier === "destructive" && !gate.nested && !gate.undeclared
+          && process.env.OC_SEND_URL && process.env.OC_SEND_TOKEN && process.env.OC_CHANNEL_ID && process.env.OC_CHANNEL_ADAPTER;
+        if (!canAsk) { console.error(gate.message); process.exitCode = 3; return; }
+        const commandLine = ["open-claudia tool run", t.name, ...toolArgs].join(" ");
+        console.error(`Destructive run without --yes-destructive — asking for chat approval of the exact command...`);
+        let decision = "denied";
+        try {
+          const { postJson } = require("./loopback-client");
+          const res = await postJson("approval-request", {
+            tool: t.name, verb: tools.invokedVerb(toolArgs), tier: gate.tier, command: commandLine,
+          });
+          const approvals = require("../core/approvals");
+          decision = await approvals.waitForDecision(res.id);
+        } catch (e) {
+          console.error(`Chat approval unavailable (${e.message}).`);
+        }
+        if (decision !== "approved") {
+          console.error(`⛔ Not approved (${decision}) — refusing to run ${t.name}. ` +
+            `Re-run with --yes-destructive only after the user explicitly approves.`);
+          process.exitCode = 3; return;
+        }
+        approvedVia = "chat-approval";
+        console.error(`✅ Approved in chat — running.`);
+      }
 
       const missing = tools.missingRequires(t);
       if (missing.length) {
         console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
         process.exitCode = 1; return;
       }
+      // Fingerprint check: warn (never block) when the source changed since the
+      // last verified (exit-0) run — the next green run re-verifies it.
+      try {
+        const fp = tools.fingerprint(t.name);
+        if (fp.status === "changed") {
+          console.error(`⚠ ${t.name} is unverified since its last change (source hash differs from last green run). A successful run re-verifies it.`);
+        }
+      } catch (e) { /* advisory */ }
       // Composition inheritance: export the approved tier + call chain so any
       // tool this tool shells into is gated by what the human actually approved
       // at the top — an already-inherited tier passes through UNCHANGED.
@@ -367,18 +411,18 @@ function run(args) {
       const parentStack = String(process.env.OPEN_CLAUDIA_TOOL_STACK || "").trim();
       env.OPEN_CLAUDIA_APPROVED_TIER = parentStack
         ? (tools.normalizeRisk(process.env.OPEN_CLAUDIA_APPROVED_TIER) || "read-only")
-        : tools.approvedTierFromArgv(toolArgs);
+        : (approvedVia === "chat-approval" ? "destructive" : tools.approvedTierFromArgv(toolArgs));
       env.OPEN_CLAUDIA_TOOL_STACK = parentStack ? `${parentStack}>${t.name}` : t.name;
       const started = Date.now();
       const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env });
       const ms = Date.now() - started;
       if (r.error) {
-        tools.recordRunResult(t.name, { args: toolArgs, exit: -1, ms });
+        tools.recordRunResult(t.name, { args: toolArgs, exit: -1, ms, tier: gate.tier, approvedVia });
         console.error(`Failed to run ${t.name}: ${r.error.message}`);
         process.exitCode = 1; return;
       }
       const exit = typeof r.status === "number" ? r.status : 1;
-      tools.recordRunResult(t.name, { args: toolArgs, exit, ms });
+      tools.recordRunResult(t.name, { args: toolArgs, exit, ms, tier: gate.tier, approvedVia });
       if (exit !== 0) {
         console.error(`(exit ${exit} recorded in ${t.name} telemetry — if this is a real defect, journal it: ` +
           `open-claudia tool note ${t.name} --issue "<what broke>")`);
@@ -392,10 +436,18 @@ function run(args) {
       const { positional, flags } = parseFlags(rest);
       const name = positional[0];
       if (!name) {
-        console.error('Usage: tool scaffold <name> [--pack dir] [--desc "..."] [--risk read-only|write|destructive] [--requires "k1,k2"] [--tags "group"] [--usage "..."] [--lang node|bash]');
+        console.error('Usage: tool scaffold <name> [--pack dir] [--desc "..."] [--risk read-only|write|destructive] [--requires "k1,k2"] [--tags "group"] [--usage "..."] [--lang node|bash] [--verbs "list:read-only:doc,create:write:doc"]');
         process.exitCode = 1; return;
       }
       try {
+        // --verbs "name[:tier[:doc]],..." → per-verb manifest lines + dispatcher
+        // entries in the generated stub. Tier defaults to the tool's risk.
+        const verbs = typeof flags.verbs === "string"
+          ? flags.verbs.split(",").map((item) => {
+              const [vName, vTier, ...vDoc] = item.split(":");
+              return { name: (vName || "").trim(), tier: (vTier || "").trim(), doc: vDoc.join(":").trim() };
+            }).filter((v) => v.name)
+          : [];
         const t = repo.scaffoldTool(name, {
           pack: typeof flags.pack === "string" ? flags.pack : undefined,
           description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
@@ -404,10 +456,14 @@ function run(args) {
           tags: typeof flags.tags === "string" ? flags.tags.split(/[,\s]+/).filter(Boolean) : [],
           usage: typeof flags.usage === "string" ? flags.usage : undefined,
           lang: typeof flags.lang === "string" ? flags.lang : "node",
+          verbs,
         });
         console.log(`Scaffolded tool "${t.name}" (risk: ${t.risk}).`);
         console.log(`  Executable: ${t.file}`);
         console.log(`  Docs:       ${t.docFile}`);
+        if (t.manifest && t.manifest.length) {
+          console.log(`  Manifest:   ${t.manifest.map((v) => `${v.name} (${v.tier || t.risk})`).join(", ")} — undeclared verbs are refused at run time`);
+        }
         console.log(`Fill in the verbs, then work through it: open-claudia tool run ${t.name} <verb>`);
       } catch (e) {
         console.error(`Could not scaffold: ${e.message}`); process.exitCode = 1;

package/core/actions.js

@@ -290,6 +290,29 @@ async function handleAction(envelope) {
     await send(`Recall debug: ${state.settings.showRecall ? "on" : "off"}`);
     return;
   }
+  if (d.startsWith("tm:")) {
+    const tm = require("./tooling-mode");
+    let m;
+    try { m = tm.setToolingMode(d.slice(3)); } catch (e) { return; }
+    await send(`Tooling mode: ${m}${m === "relaxed" ? " ⚠️ deny-gate is log-only; ad-hoc scripting allowed" : " — tool-first enforced"}`);
+    return;
+  }
+  if (d.startsWith("apr:")) {
+    // Destructive tool-run approval buttons. Owner-only: the exact payload was
+    // shown in the prompt; decide() is idempotent so double-taps can't flip it.
+    if (!isChatOwner(envelope.channelId)) return send("Owner only — tool approvals are restricted.");
+    const parts = d.split(":");
+    const id = parts[1];
+    const choice = parts[2] === "ok" ? "approved" : "denied";
+    const approvals = require("./approvals");
+    const rec = approvals.decide(id, choice, String(envelope.channelId));
+    if (!rec) return send("That approval request has expired or was cleaned up — the run stays blocked.");
+    // If a second press disagreed, rec.status still holds the FIRST decision.
+    await send(rec.status === "approved"
+      ? `✅ Approved — ${rec.tool}${rec.verb ? " " + rec.verb : ""} will run now.`
+      : `⛔ Denied — ${rec.tool}${rec.verb ? " " + rec.verb : ""} will not run.`);
+    return;
+  }
   if (d.startsWith("tt:")) {
     state.settings.showToolTrace = d.slice(3) === "on";
     saveState();

package/core/approvals.js

@@ -0,0 +1,85 @@
+// Chat approval for destructive tool runs: the runner shows the EXACT resolved
+// payload on the requesting channel with inline Approve/Deny buttons, and the
+// run proceeds only on an explicit Approve. This closes the gap where a
+// --yes-destructive flag acknowledges a summary — here the user approves the
+// literal command that will execute, not the agent's paraphrase of it.
+//
+// Mechanics: file-backed records under CONFIG_DIR/approvals. The CLI (a bot
+// subprocess) POSTs approval-request to the bot's loopback server, which sends
+// the button message and creates the pending record; the CLI then polls the
+// record file until the actions.js "apr:" callback flips its status, or the
+// timeout lapses (timeout = denied — fail-closed, unlike the guard's
+// fail-open, because this path only exists for destructive actions).
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const CONFIG_DIR = require("../config-dir");
+
+const APPROVALS_DIR = process.env.APPROVALS_DIR || path.join(CONFIG_DIR, "approvals");
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function fileOf(id) {
+  const base = path.basename(String(id || "").trim());
+  if (!base) throw new Error("approval id required");
+  return path.join(APPROVALS_DIR, `${base}.json`);
+}
+
+// Best-effort GC so decided/expired records don't accumulate forever.
+function prune() {
+  let entries;
+  try { entries = fs.readdirSync(APPROVALS_DIR); } catch (e) { return; }
+  const cutoff = Date.now() - MAX_AGE_MS;
+  for (const f of entries) {
+    if (!f.endsWith(".json")) continue;
+    const p = path.join(APPROVALS_DIR, f);
+    try { if (fs.statSync(p).mtimeMs < cutoff) fs.rmSync(p, { force: true }); } catch (e) {}
+  }
+}
+
+function create({ tool, verb = "", tier = "destructive", command = "", channelId = "", adapter = "" }) {
+  fs.mkdirSync(APPROVALS_DIR, { recursive: true, mode: 0o700 });
+  prune();
+  const id = `apr_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+  const rec = {
+    id, status: "pending",
+    tool: String(tool || ""), verb: String(verb || ""), tier: String(tier || ""),
+    command: String(command || "").slice(0, 1000),
+    channelId: String(channelId || ""), adapter: String(adapter || ""),
+    requestedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
+  return rec;
+}
+
+function read(id) {
+  try { return JSON.parse(fs.readFileSync(fileOf(id), "utf-8")); }
+  catch (e) { return null; }
+}
+
+// Flip a pending record. Idempotence guard: a second button press on the same
+// message must not overturn the first decision.
+function decide(id, status, by = "") {
+  const rec = read(id);
+  if (!rec) return null;
+  if (rec.status !== "pending") return rec;
+  rec.status = status === "approved" ? "approved" : "denied";
+  rec.decidedAt = new Date().toISOString();
+  if (by) rec.decidedBy = String(by);
+  fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
+  return rec;
+}
+
+// Poll until decided or timeout. Timeout resolves as "timeout" — the caller
+// must treat anything other than "approved" as a refusal.
+async function waitForDecision(id, { timeoutMs = 300000, pollMs = 1500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const rec = read(id);
+    if (rec && rec.status !== "pending") return rec.status;
+    if (Date.now() >= deadline) return "timeout";
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+}
+
+module.exports = { APPROVALS_DIR, create, read, decide, waitForDecision };

package/core/handlers.js

@@ -123,7 +123,7 @@ register({
     if (!authorized(env)) return;
     send([
       "Session: /session /sessions /projects /continue /status /stop /end",
-      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine /recall /tooltrace",
+      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine /recall /tooltrace /toolmode",
       "Identity: /whoami /link",
       "Team: /people /intros /auth (owner)",
       "Automation: /cron /vault /soul /dreamsummary",
@@ -743,6 +743,29 @@ register({
   },
 });
 
+register({
+  name: "toolmode", description: "Tooling enforcement mode (strict = forced CLI, relaxed = scripting allowed)", args: "[strict|relaxed]", ownerOnly: true,
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const tm = require("./tooling-mode");
+    if (tail) {
+      let m;
+      try { m = tm.setToolingMode(tail); } catch (e) { return send(`Usage: /toolmode [strict|relaxed]. Currently ${tm.getToolingMode()}.`); }
+      return send(`Tooling mode: ${m}${m === "relaxed" ? " ⚠️ deny-gate is log-only; ad-hoc scripting allowed" : " — tool-first enforced"}`);
+    }
+    const cur = tm.getToolingMode();
+    send(
+      `Tooling mode: ${cur}\n\n` +
+      "strict — operational work is forced through reusable CLIs: the deny-gate blocks raw prod commands and the agent must search/extend/scaffold tools first.\n" +
+      "relaxed — the older model: tools preferred but ad-hoc scripting allowed; the deny-gate logs instead of blocking.\n\n" +
+      "Risk-tier approvals (--yes / --yes-destructive) apply in both modes. Takes effect on the next command, no restart.",
+      { keyboard: { inline_keyboard: [
+        [{ text: "Strict", callback_data: "tm:strict" }, { text: "Relaxed", callback_data: "tm:relaxed" }],
+      ] } },
+    );
+  },
+});
+
 register({
   name: "tooltrace", description: "Show tool activity each turn (surfaced/ran/updated)", args: "[on|off]",
   handler: async (env, { tail }) => {

package/core/loopback.js

@@ -79,6 +79,7 @@ const JSON_KINDS = new Set([
   "intros-list", "intros-approve", "intros-reject",
   "relay-send", "recent-fetch", "audit-tail",
   "auth-list", "auth-revoke",
+  "approval-request",
 ]);
 
 function callerIsOwner(payload) {
@@ -459,6 +460,36 @@ async function handleJson(req, res, url, kind) {
     return reply(res, 200, { ok: true, entries: audit.tail(n) });
   }
 
+  // Chat approval for a destructive tool run: post the EXACT resolved command
+  // to the requesting channel with Approve/Deny buttons and hand back the
+  // record id; the CLI polls the record until the "apr:" callback decides it.
+  if (kind === "approval-request") {
+    if (!payload.tool || !payload.command) return reply(res, 400, { error: "missing tool/command" });
+    try {
+      const approvals = require("./approvals");
+      const rec = approvals.create({
+        tool: payload.tool, verb: payload.verb || "", tier: payload.tier || "destructive",
+        command: payload.command, channelId, adapter: adapterId,
+      });
+      const text = [
+        `🔐 Destructive tool run wants approval:`,
+        ``,
+        `<pre>${String(payload.command).slice(0, 800).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</pre>`,
+        ``,
+        `Tool: ${payload.tool}${payload.verb ? ` · verb: ${payload.verb}` : ""} · tier: ${rec.tier}`,
+        `This is the literal command that will execute. Times out (denied) in 5 minutes.`,
+      ].join("\n");
+      const keyboard = { inline_keyboard: [[
+        { text: "✅ Approve", callback_data: `apr:${rec.id}:ok` },
+        { text: "⛔ Deny", callback_data: `apr:${rec.id}:no` },
+      ]] };
+      const ok = await adapter.send(channelId, text, { keyboard });
+      if (!ok) { approvals.decide(rec.id, "denied", "send-failed"); return reply(res, 500, { error: "could not deliver approval prompt" }); }
+      audit.log("tool.approval.requested", { id: rec.id, tool: rec.tool, verb: rec.verb, channelId });
+      return reply(res, 200, { ok: true, id: rec.id });
+    } catch (e) { return reply(res, 400, { error: e.message }); }
+  }
+
   return reply(res, 404, { error: "not found" });
 }
 

package/core/runner.js

@@ -988,9 +988,14 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       try {
         for (const run of require("./tool-graph").parseToolRuns(cmd)) {
           toolRunsThisTurn.push(run);
-          // Visibility (gated by /tooltrace): one 🔧 line per distinct tool run
-          // this turn. Telemetry (recordRun) fires at end-of-turn on success.
-          notifyToolTrace(`ran:${run.name}`, `🔧 Ran tool: ${run.name}`);
+          // Visibility (gated by /tooltrace): one 🔧 line per distinct
+          // tool+verb this turn — sanitized command shape plus the verb's own
+          // doc sentence (verbDoc: parsed mechanically from the tool header,
+          // zero model cost). Telemetry (recordRun) fires at end-of-turn.
+          const verb = (String(run.shape || "").split(/\s+/)[1] || "");
+          let doc = "";
+          try { doc = toolsLib.verbDoc(run.name, verb); } catch (e) {}
+          notifyToolTrace(`ran:${run.name}:${verb}`, `🔧 ${run.shape || run.name}${doc ? ` — ${doc}` : ""}`);
         }
       } catch (e) { /* graph optional (old node) */ }
       // `open-claudia tool add <src> [--name X]` — a tool being saved/updated.

package/core/system-prompt.js

@@ -84,17 +84,33 @@ function buildToolIndexBlock() {
   } catch (e) {
     return "";
   }
+  // Relaxed tooling mode (/toolmode): the older model — tools are available
+  // and preferred, but ad-hoc scripting is allowed and the deny-gate only
+  // observes. The risk gate on tool runs applies in BOTH modes.
+  try {
+    if (require("./tooling-mode").getToolingMode() === "relaxed") {
+      return `\n## Tools are available (relaxed mode)
+Tool-first enforcement is currently OFF (\`/toolmode\` switches it). Reusable tools exist and are usually the fastest path — check the "Tools that may help here" block, or \`open-claudia tool search <query>\` / \`tool list\`, and prefer a covering tool when one fits. But ad-hoc scripts and raw shell commands are permitted for operational work in this mode; the deny-gate logs raw prod-surface commands for audit without blocking them.
+
+Still in force regardless of mode:
+- Risk gate on tool runs: read-only runs freely; write-tier needs \`--yes\`; destructive needs \`--yes-destructive\` — the flag is your acknowledgment AFTER the user approves, never a substitute for asking first.
+- Credential confinement: keyring creds are injected only into \`tool run\` subprocesses for declared \`--requires\` keys; never write a secret into a tool file or script.
+- Keep TOOL.md truthful when you do change a tool, and announce scaffolds/changes in one line.
+${listing}`;
+    }
+  } catch (e) { /* fail-strict */ }
   return `\n## Tools are the interface (tool-first)
 Operational work — hitting an API, mutating a live system, driving an interface, any command you would re-derive next time — happens THROUGH a reusable tool, not around one. BEFORE doing the work, walk this loop in order:
 
 1. **Search** — check the "Tools that may help here" block if present; otherwise \`open-claudia tool search <query>\` or \`tool list\`.
 2. **Use** — a tool covers it: read it first (\`open-claudia tool show <name>\` gives docs, State, known issues, recent changes — never guess its args; \`--source\` only when modifying), then \`open-claudia tool run <name> <verb> [args]\`.
 3. **Extend** — right tool, missing verb: add the verb to that tool (\`tool edit <name>\`, then \`tool note <name> --journal "added <verb>"\`) and run it. One CLI per system, verbs as subcommands — never fork a near-duplicate.
-4. **Scaffold** — no tool fronts the system: \`open-claudia tool scaffold <name> --desc "..." --risk <read-only|write|destructive> [--pack <dir>] [--requires "key1,key2"]\` FIRST, implement the verb you need, then do the work through it.
+4. **Scaffold** — no tool fronts the system: \`open-claudia tool scaffold <name> --desc "..." --risk <read-only|write|destructive> [--pack <dir>] [--requires "key1,key2"] [--verbs "list:read-only:doc,create:write:doc"]\` FIRST, implement the verb you need, then do the work through it.
 
 Raw shell one-liners and heredocs are for probing and diagnosis only — never the operational action itself. If a tool is broken, fix it or journal the defect (\`tool note <name> --issue "..."\`); do not route around it with a script.
 
 - Risk gate: read-only tools run freely; write-tier needs \`--yes\`; destructive needs \`--yes-destructive\`. The flag is your mechanical acknowledgment AFTER the user approves the action — it never replaces asking first.
+- Per-verb manifest: a tool that declares \`verb:\` header lines is gated verb-by-verb — each verb runs at its own declared tier, and an undeclared verb is refused outright (declare it in the header before using it). An unflagged destructive run inside a bot task escalates to chat with the EXACT command and Approve/Deny buttons; anything but an explicit approve is a refusal.
 - Tools carry their own memory: TOOL.md (Interface · Known issues · State · Journal) is the manual, state.json records every run (per-verb health), and every change is a git commit. Keep TOOL.md truthful as you work; update the tool in place when behaviour changes.
 - Preauth, least-privilege: keyring creds are injected ONLY into \`tool run\` subprocesses, and only the keys a tool declares via \`--requires\` (\`open-claudia keyring list\` shows names) — your own shell and sub-agents hold NO creds. Reference creds as \`$inet_central_user\` etc. inside tool sources and declare every one; never write a secret into a tool file (saves are refused).
 - Deny-gate: raw shell commands that act on known production surfaces (platform APIs, prod hosts, in-cluster mongo, GitLab host shell) are blocked mid-flight with a redirect to the covering tool — that block is the system working, not an obstacle to route around. Genuine one-off no tool covers yet? \`open-claudia keyring exec --reason "<why>" -- <cmd>\` runs with full creds and logs the bypass for audit; scaffold the tool if you'd ever run it twice.

package/core/tool-guard.js

@@ -161,7 +161,7 @@ function noteRawOp(command) {
 // KPI data source (5c): guard events since a timestamp, grouped by kind.
 // Malformed lines are skipped — the log is append-only best-effort.
 function readGuardEvents(sinceTs) {
-  const out = { denies: [], bypasses: [], rawOps: [] };
+  const out = { denies: [], bypasses: [], rawOps: [], relaxedPasses: [] };
   let raw = "";
   try { raw = fs.readFileSync(GUARD_LOG, "utf-8"); } catch (e) { return out; }
   const since = sinceTs ? Date.parse(sinceTs) : NaN;
@@ -173,6 +173,7 @@ function readGuardEvents(sinceTs) {
     if (evt.kind === "deny") out.denies.push(evt);
     else if (evt.kind === "bypass") out.bypasses.push(evt);
     else if (evt.kind === "raw-op") out.rawOps.push(evt);
+    else if (evt.kind === "relaxed-pass") out.relaxedPasses.push(evt);
   }
   return out;
 }
@@ -192,6 +193,15 @@ function runHook(payload) {
     const command = data.tool_input && data.tool_input.command;
     const rule = matchRule(command);
     if (!rule) return { exit: 0, stderr: "" };
+    // Relaxed tooling mode: the gate observes but never blocks. The event is
+    // still logged (as relaxed-pass, not deny) so the dream KPI can report
+    // what WOULD have been denied — visibility survives the mode switch.
+    let relaxed = false;
+    try { relaxed = require("./tooling-mode").getToolingMode() === "relaxed"; } catch (e) { /* fail-strict */ }
+    if (relaxed) {
+      logGuardEvent({ kind: "relaxed-pass", rule: rule.id, command: String(command).slice(0, 300) });
+      return { exit: 0, stderr: "" };
+    }
     logGuardEvent({ kind: "deny", rule: rule.id, command: String(command).slice(0, 300) });
     return { exit: 2, stderr: denyMessage(rule) };
   } catch (e) {

package/core/tool-repo.js

@@ -102,7 +102,11 @@ function toolLog(name, limit = 5) {
 
 function today() { return new Date().toISOString().slice(0, 10); }
 
-function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateLine, journalLine }) {
+function toolMdSkeleton({ name, description, usage, risk, requires, pack, verbs, stateLine, journalLine }) {
+  const verbLines = (verbs && verbs.length)
+    ? ["", "Verbs (from the manifest in the tool header — the runner refuses undeclared verbs):",
+       ...verbs.map((v) => `- \`${v.name}${v.args ? " " + v.args : ""}\` — ${v.tier || risk || "write"}${v.doc ? ` — ${v.doc}` : ""}`)]
+    : [];
   return [
     `# ${name}`,
     "",
@@ -111,6 +115,7 @@ function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateL
     "",
     `Usage: \`open-claudia tool run ${name}${usage ? " " + usage.replace(new RegExp("^" + name + "\\s*"), "") : " <verb> [args]"}\``,
     `Risk: ${risk || "write"}${requires && requires.length ? ` · Requires: ${requires.join(", ")}` : ""}${pack ? ` · Pack: ${pack}` : ""}`,
+    ...verbLines,
     "",
     "## Known issues",
     "(none yet)",
@@ -124,16 +129,30 @@ function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateL
   ].join("\n");
 }
 
-function nodeStub({ name, description, pack, risk, requires, usage, tags }) {
+// Manifest header lines: one `verb:` line per declared verb, parsed by
+// tools.parseHeader into the per-verb gate. Format: name [args] | tier | doc.
+function verbHeaderLines(verbs, comment) {
+  return (verbs || []).map((v) =>
+    `${comment} verb: ${v.name}${v.args ? " " + v.args : ""} | ${v.tier || "write"}${v.doc ? ` | ${v.doc}` : ""}\n`).join("");
+}
+
+function nodeStub({ name, description, pack, risk, requires, usage, tags, verbs }) {
   const req = requires && requires.length ? `// requires: ${requires.join(", ")}\n` : "";
   const tag = tags && tags.length ? `// tags: ${tags.join(", ")}\n` : "";
+  const manifest = verbHeaderLines(verbs, "//");
+  const handlers = (verbs || []).map((v) =>
+    `  ${/^[a-zA-Z_$][\w$]*$/.test(v.name) ? v.name : JSON.stringify(v.name)}(rest) {\n` +
+    `    console.error("TODO: implement ${v.name}${v.doc ? ` — ${v.doc.replace(/"/g, '\\"')}` : ""}");\n` +
+    `    process.exit(1);\n  },`).join("\n");
   return `#!/usr/bin/env node
 // open-claudia-tool: ${name}
 // description: ${description || ""}
 ${pack ? `// pack: ${pack}\n` : ""}// risk: ${risk}
 ${req}${tag}// usage: ${usage || `${name} <verb> [args]`}
-//
+${manifest}//
 // One CLI per system, verbs as subcommands. Add a function per verb below.
+// Every verb MUST be declared with a "verb:" header line above — the runner
+// refuses undeclared verbs and gates each one by its declared tier.
 // Confirmation flags (--yes / --yes-destructive) are enforced by the tool
 // runner and may appear in argv — ignore them unless you need them.
 
@@ -145,8 +164,7 @@ const HANDLERS = {
     console.log("${name} — ${(description || "").replace(/"/g, '\\"')}");
     console.log("verbs: " + Object.keys(HANDLERS).join(", "));
   },
-  // example(rest) { ... },
-};
+${handlers ? handlers + "\n" : "  // example(rest) { ... },\n"}};
 
 const fn = HANDLERS[verb] || (verb === "--help" ? HANDLERS.help : null);
 if (!fn) { console.error("unknown verb: " + verb); HANDLERS.help(); process.exit(1); }
@@ -154,16 +172,22 @@ Promise.resolve(fn(args.slice(1))).catch((e) => { console.error(e.message || e);
 `;
 }
 
-function bashStub({ name, description, pack, risk, requires, usage, tags }) {
+function bashStub({ name, description, pack, risk, requires, usage, tags, verbs }) {
   const req = requires && requires.length ? `# requires: ${requires.join(", ")}\n` : "";
   const tag = tags && tags.length ? `# tags: ${tags.join(", ")}\n` : "";
+  const manifest = verbHeaderLines(verbs, "#");
+  const verbNames = ["help", ...(verbs || []).map((v) => v.name)];
+  const cases = (verbs || []).map((v) =>
+    `  ${v.name})\n    echo "TODO: implement ${v.name}" >&2; exit 1 ;;`).join("\n");
   return `#!/usr/bin/env bash
 # open-claudia-tool: ${name}
 # description: ${description || ""}
 ${pack ? `# pack: ${pack}\n` : ""}# risk: ${risk}
 ${req}${tag}# usage: ${usage || `${name} <verb> [args]`}
-#
+${manifest}#
 # One CLI per system, verbs as subcommands: add a case per verb below.
+# Every verb MUST be declared with a "verb:" header line above — the runner
+# refuses undeclared verbs and gates each one by its declared tier.
 # Confirmation flags (--yes / --yes-destructive) are enforced by the tool
 # runner and may appear in "$@" — ignore them unless you need them.
 set -euo pipefail
@@ -173,8 +197,8 @@ verb="\${1:-help}"; shift || true
 case "$verb" in
   help|--help)
     echo "${name} — ${description || ""}"
-    echo "verbs: help" ;;
-  *)
+    echo "verbs: ${verbNames.join(", ")}" ;;
+${cases ? cases + "\n" : ""}  *)
     echo "unknown verb: $verb" >&2; exit 1 ;;
 esac
 `;
@@ -192,7 +216,10 @@ function scaffoldTool(name, opts = {}) {
   const risk = tools.normalizeRisk(opts.risk) || "write";
   const requires = [].concat(opts.requires || []).filter(Boolean);
   const tags = [].concat(opts.tags || []).map((s) => tools.sanitizeName(s)).filter(Boolean);
-  const spec = { name: n, description: opts.description || "", pack: opts.pack || "", risk, requires, tags, usage: opts.usage || "" };
+  const verbs = [].concat(opts.verbs || [])
+    .map((v) => ({ name: String(v.name || "").trim(), args: String(v.args || "").trim(), tier: tools.normalizeRisk(v.tier) || risk, doc: String(v.doc || "").trim() }))
+    .filter((v) => v.name && v.name !== "help");
+  const spec = { name: n, description: opts.description || "", pack: opts.pack || "", risk, requires, tags, usage: opts.usage || "", verbs };
 
   ensureRepo();
   const dir = path.join(toolsDir(), n);

package/core/tooling-mode.js

@@ -0,0 +1,40 @@
+// Tooling-mode switch: "strict" (tool-first enforced — deny-gate blocks raw
+// prod commands, prompt teaches the mandatory search→use→extend→scaffold loop)
+// vs "relaxed" (the older model — ad-hoc scripting allowed, deny-gate observes
+// and logs but never blocks).
+//
+// Global rather than per-channel: the deny-gate hook runs as a bare
+// subprocess with no channel context, so the mode lives in a file it re-reads
+// on every invocation — switching takes effect on the next Bash call, no
+// restart needed.
+//
+// What the mode NEVER changes: risk-tier approvals (--yes/--yes-destructive),
+// credential confinement, and the guard AUDIT log. Those mechanise the
+// ask-first hard rule and apply to scripts and tools alike in both modes.
+//
+// Fail-safe: any read error means "strict" — enforcement is the default.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+
+const MODE_FILE = process.env.TOOLING_MODE_FILE || path.join(CONFIG_DIR, "tooling-mode.json");
+const MODES = ["strict", "relaxed"];
+
+function getToolingMode() {
+  try {
+    const data = JSON.parse(fs.readFileSync(MODE_FILE, "utf-8"));
+    return MODES.includes(data.mode) ? data.mode : "strict";
+  } catch (e) {
+    return "strict";
+  }
+}
+
+function setToolingMode(mode) {
+  const m = String(mode || "").trim().toLowerCase();
+  if (!MODES.includes(m)) throw new Error(`invalid tooling mode "${mode}" — use one of: ${MODES.join(", ")}`);
+  fs.writeFileSync(MODE_FILE, JSON.stringify({ mode: m, changedAt: new Date().toISOString() }, null, 2) + "\n");
+  return m;
+}
+
+module.exports = { MODE_FILE, MODES, getToolingMode, setToolingMode };

package/core/tools.js

@@ -28,6 +28,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const CONFIG_DIR = require("../config-dir");
 
 const TOOLS_DIR = process.env.TOOLS_DIR ? path.resolve(process.env.TOOLS_DIR) : path.join(CONFIG_DIR, "tools");
@@ -114,7 +115,7 @@ function writeState(name, s) {
 // non-flag arg) so TOOL.md can report "assign: last real run <date>" honestly,
 // plus a capped run history. A non-zero exit is the trigger for a known-issue
 // entry in TOOL.md (the CLI nudges; the foreground agent writes it).
-function recordRunResult(name, { args = [], exit = 0, ms = 0 } = {}) {
+function recordRunResult(name, { args = [], exit = 0, ms = 0, tier = "", approvedVia = "" } = {}) {
   const n = sanitizeName(name);
   if (!n) return;
   if (toolPaths(n).layout !== "dir") { recordRun(n); return; } // legacy fallback
@@ -125,6 +126,13 @@ function recordRunResult(name, { args = [], exit = 0, ms = 0 } = {}) {
   s.runCount = (s.runCount || 0) + 1;
   s.lastExit = exit;
   if (exit === 0) s.lastSuccess = now; else s.lastFailure = now;
+  // A clean exit re-verifies the current source: the fingerprint proves "this
+  // exact code worked" — any later edit flips the tool to unverified until its
+  // next successful run.
+  if (exit === 0) {
+    const h = sourceHash(n);
+    if (h) { s.verifiedHash = h; s.verifiedAt = now; }
+  }
   const verb = (args.find((a) => a && !String(a).startsWith("-")) || "(default)").slice(0, 40);
   s.verbs = s.verbs || {};
   const v = s.verbs[verb] || { runs: 0 };
@@ -133,10 +141,32 @@ function recordRunResult(name, { args = [], exit = 0, ms = 0 } = {}) {
   if (exit === 0) v.lastSuccess = now; else v.lastFailure = now;
   s.verbs[verb] = v;
   const argLine = args.join(" ").slice(0, 120);
-  s.history = [{ at: now, args: argLine, exit, ms }, ...(s.history || [])].slice(0, HISTORY_CAP);
+  const entry = { at: now, args: argLine, exit, ms };
+  if (tier) entry.tier = tier;               // which tier was acknowledged for this run
+  if (approvedVia) entry.approvedVia = approvedVia; // flag vs chat-approval — auditable forever
+  s.history = [entry, ...(s.history || [])].slice(0, HISTORY_CAP);
   writeState(n, s);
 }
 
+// ── Source fingerprint ───────────────────────────────────────────────────────
+// sha256 of the executable. recordRunResult stamps it as verifiedHash on every
+// clean exit; fingerprint() compares the stamp to the current source so the
+// runner can warn "unverified since change" — the agent can never unknowingly
+// run code that changed since it was last proven to work.
+function sourceHash(name) {
+  try { return crypto.createHash("sha256").update(fs.readFileSync(toolPaths(name).exec)).digest("hex"); }
+  catch (e) { return ""; }
+}
+
+function fingerprint(name) {
+  const n = sanitizeName(name);
+  const s = readState(n);
+  const current = sourceHash(n);
+  if (!s.verifiedHash) return { status: "never-verified", current, verified: "", verifiedAt: "" };
+  if (s.verifiedHash === current) return { status: "verified", current, verified: s.verifiedHash, verifiedAt: s.verifiedAt || "" };
+  return { status: "changed", current, verified: s.verifiedHash, verifiedAt: s.verifiedAt || "" };
+}
+
 // Bump a tool's run counter without outcome detail. Still called at end of turn
 // from the runner's transcript parse; for directory tools that's a no-op (the
 // CLI already stamped the authoritative result — double-counting would lie),
@@ -244,7 +274,7 @@ function uncomment(line) {
 // script is only a tool if the block contains an "open-claudia-tool: <name>"
 // line.
 function parseHeader(content) {
-  const out = { name: "", description: "", pack: "", requires: [], usage: "", risk: "", tags: [] };
+  const out = { name: "", description: "", pack: "", requires: [], usage: "", risk: "", tags: [], manifest: [] };
   const lines = String(content || "").split("\n");
   let started = false;
   for (let i = 0; i < lines.length; i++) {
@@ -265,11 +295,94 @@ function parseHeader(content) {
     else if (key === "requires") out.requires = val.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
     else if (key === "risk") out.risk = normalizeRisk(val);
     else if (key === "tags") out.tags = val.split(/[,\s]+/).map((s) => sanitizeName(s)).filter(Boolean);
+    else if (key === "verb") {
+      // Per-verb manifest line: `verb: <name> [arg hint] | <tier> | <doc>`.
+      // The machine-readable contract the runner gates on — a tool WITH a
+      // manifest refuses undeclared verbs, and each verb carries its own tier.
+      const segs = val.split("|").map((s) => s.trim());
+      const head = segs[0] || "";
+      const nameTok = head.split(/\s+/)[0] || "";
+      if (nameTok) {
+        out.manifest.push({
+          name: nameTok,
+          args: head.slice(nameTok.length).trim(),
+          tier: normalizeRisk(segs[1]),
+          doc: segs.slice(2).join(" | "),
+        });
+      }
+    }
     else if (HEADER_KEYS.includes(key)) out[key] = val;
   }
   return out.name ? out : null;
 }
 
+// First readable clause of a doc string: cut at sentence end or " — ",
+// collapse whitespace, cap length. Used for one-line verb docs in chat.
+function firstClause(s) {
+  let t = String(s || "").replace(/\s+/g, " ").trim();
+  if (!t) return "";
+  const m = t.match(/^(.{10,}?[.!?])(?:\s|$)/);
+  if (m) t = m[1].replace(/[.!?]+$/, "");
+  else t = t.split(" — ")[0];
+  if (t.length > 90) t = t.slice(0, 87).trimEnd() + "…";
+  return t;
+}
+
+// One human-readable sentence for a tool verb, parsed mechanically from the
+// tool's own leading comment block (the same docs --help prints) — zero model
+// cost, always in sync with the source. Two documented shapes are recognised:
+//   //   kticket list [--stage a,b]        ← verb line; description on the
+//   //       List tickets. --q matches …      deeper-indented line(s) below
+//   //   inet-central users [regex]     list users; same-line prose after 2+ spaces
+// Falls back to the tool description's first clause; "" when the tool is unknown.
+function verbDoc(name, verb) {
+  let content;
+  try { content = fs.readFileSync(toolPaths(name).exec, "utf-8"); } catch (e) { return ""; }
+  const header = parseHeader(content);
+  if (!header) return "";
+  const fallback = firstClause(header.description);
+  const v = String(verb || "").trim();
+  if (!v || v.startsWith("-") || v.startsWith("<")) return fallback;
+  // Manifest doc wins when declared — it's the contract, not prose.
+  const mv = (header.manifest || []).find((x) => x.name === v);
+  if (mv && mv.doc) return firstClause(mv.doc);
+  // Re-walk the leading comment block (same bounds as parseHeader).
+  const lines = String(content).split("\n");
+  const block = [];
+  let started = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (i === 0 && lines[i].startsWith("#!")) continue;
+    const body = uncomment(lines[i]);
+    if (body === null) {
+      if (started) break;
+      if (lines[i].trim() === "") continue;
+      break;
+    }
+    started = true;
+    block.push(body);
+  }
+  const vEsc = v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const verbLine = new RegExp(`^(\\s+)\\S+\\s+${vEsc}\\b(.*)$`);
+  for (let i = 0; i < block.length; i++) {
+    const m = block[i].match(verbLine);
+    if (!m) continue;
+    const same = m[2].match(/\s{2,}([A-Za-z].*)$/);
+    if (same) return firstClause(same[1]);
+    const indent = m[1].length;
+    let desc = "";
+    for (let j = i + 1; j < block.length; j++) {
+      const ind = (block[j].match(/^\s*/) || [""])[0].length;
+      const text = block[j].trim();
+      if (!text || ind <= indent) break;
+      desc += (desc ? " " : "") + text;
+      if (/[.!?]$/.test(text)) break;
+    }
+    if (desc) return firstClause(desc);
+    break;
+  }
+  return fallback;
+}
+
 // Path of a tool's executable (legacy signature kept: several callers treat
 // "the tool file" as the thing you run/edit).
 function toolFile(name) {
@@ -295,6 +408,7 @@ function readTool(name, usageMap) {
     usage: header.usage || "",
     risk: header.risk || "",
     tags: header.tags || [],
+    manifest: header.manifest || [],
     layout: p.layout,
     file: p.exec,
     docFile: p.doc,
@@ -340,6 +454,9 @@ function toolCondition(t) {
     const issues = sectionOf(doc, "Known issues").split("\n").filter((l) => /^\s*-\s*\S/.test(l)).length;
     if (issues) parts.push(`⚠ ${issues} known issue${issues === 1 ? "" : "s"}`);
   }
+  if (t.layout === "dir" && t.runCount && fingerprint(t.name).status === "changed") {
+    parts.push("⚠ unverified since change");
+  }
   if (!t.runCount) parts.push("never run");
   else {
     const when = (t.lastUsed || "").slice(0, 10);
@@ -764,9 +881,40 @@ function approvedTierFromArgv(argv = []) {
   return "read-only";
 }
 
+// Resolve the effective tier for an invocation from the tool's per-verb
+// manifest (when it declares one). The manifest is the contract: a declared
+// read-only verb runs ungated even in a write-tier tool (the lower tier is
+// EARNED by the verb's own in-code limits), and an undeclared verb is refused
+// outright — the dispatcher shouldn't know it either. Tools without a manifest
+// keep the tool-level tier (fail-safe write until classified/migrated).
+function invokedVerb(argv = []) {
+  const v = (argv || []).find((a) => a && !String(a).startsWith("-"));
+  return v ? String(v) : "";
+}
+
+function resolveTier(tool, argv = []) {
+  const declared = normalizeRisk(tool && tool.risk) || "write";
+  const manifest = (tool && tool.manifest) || [];
+  const verb = invokedVerb(argv);
+  if (!manifest.length) return { tier: declared, verb, manifest: false };
+  if (!verb || verb === "help") return { tier: "read-only", verb: verb || "help", manifest: true };
+  const m = manifest.find((x) => x.name === verb);
+  if (!m) return { tier: declared, verb, manifest: true, undeclared: true };
+  return { tier: m.tier || declared, verb, manifest: true };
+}
+
 function runGate(tool, argv = [], env = process.env) {
-  const declared = normalizeRisk(tool && tool.risk);
-  const tier = declared || "write";
+  const resolved = resolveTier(tool, argv);
+  if (resolved.undeclared) {
+    const known = (tool.manifest || []).map((v) => v.name).join(", ");
+    return {
+      ok: false, tier: resolved.tier, verb: resolved.verb, undeclared: true,
+      message: `⛔ "${tool.name}" has no declared verb "${resolved.verb}" — its manifest allows: ${known || "(none)"}.\n` +
+        `If the verb genuinely exists, declare it in the tool header (\`${"verb"}: ${resolved.verb} | <tier> | <doc>\`) so the gate knows its tier.`,
+    };
+  }
+  const tier = resolved.tier;
+  const declared = resolved.manifest ? tier : normalizeRisk(tool && tool.risk);
   const stack = String((env && env.OPEN_CLAUDIA_TOOL_STACK) || "").trim();
   if (stack) {
     // Nested run — a tool called this tool.
@@ -848,9 +996,10 @@ function toolNameFromPath(filePath) {
 
 module.exports = {
   TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS, LIB_DIR,
-  parseHeader, readTool, readToolDoc, toolCondition, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
+  parseHeader, readTool, readToolDoc, toolCondition, verbDoc, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir, normalizeRisk,
   toolPaths, readState, writeState, recordRunResult, runGate, approvedTierFromArgv,
+  resolveTier, invokedVerb, sourceHash, fingerprint,
   listLib, readLib, writeLib, libDependents,
   matchTools, recordRun, recordCreate, readUsage,
   lintToolSource, checkSyntax, envRefsIn, assertNoSecrets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.7.5",
+  "version": "2.8.0",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "setup": "node setup.js",
     "start": "node bot.js",
-    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js"
+    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js"
   },
   "files": [
     "bot.js",
@@ -47,7 +47,9 @@
     "test-read-signal.js",
     "test-tools.js",
     "test-tool-graph.js",
-    "test-tool-guard.js"
+    "test-tool-guard.js",
+    "test-tooling-mode.js",
+    "test-tool-manifest.js"
   ],
   "keywords": [
     "claude",

package/test-tool-manifest.js

@@ -0,0 +1,110 @@
+// Per-verb manifest + fingerprint + chat approvals: a tool that declares
+// `verb:` header lines is gated verb-by-verb (undeclared verbs refused, each
+// verb at its own tier, help/no-verb read-only), a green run stamps a source
+// fingerprint that flags "changed" after an edit, and approval records are
+// fail-closed (only an explicit approve unblocks; timeout = denied).
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tool-manifest-test-"));
+process.env.TOOLS_DIR = path.join(tmp, "tools");
+process.env.KEYRING_FILE = path.join(tmp, "keyring.json");
+process.env.APPROVALS_DIR = path.join(tmp, "approvals");
+
+const tools = require("./core/tools");
+const repo = require("./core/tool-repo");
+const approvals = require("./core/approvals");
+
+(async () => {
+  // ── scaffold with --verbs → manifest header lines, dispatcher, TOOL.md block ──
+  const t = repo.scaffoldTool("fleet", {
+    description: "manage the fleet",
+    risk: "write",
+    lang: "bash",
+    verbs: [
+      { name: "list", tier: "read-only", doc: "list nodes" },
+      { name: "restart", tier: "write", doc: "restart one node" },
+      { name: "purge", tier: "destructive", doc: "wipe a node" },
+    ],
+  });
+  assert.strictEqual(t.manifest.length, 3, "manifest parsed back from generated header");
+  assert.deepStrictEqual(t.manifest.map((v) => v.name), ["list", "restart", "purge"]);
+  assert.strictEqual(t.manifest[0].tier, "read-only");
+  assert.strictEqual(t.manifest[2].tier, "destructive");
+  assert.strictEqual(t.manifest[1].doc, "restart one node", "per-verb doc carried");
+  const doc = tools.readToolDoc("fleet");
+  assert.ok(/`purge` — destructive — wipe a node/.test(doc), "TOOL.md Interface lists the manifest");
+  assert.ok(/list\)/.test(t.content) && /purge\)/.test(t.content), "bash dispatcher has a case per verb");
+
+  // ── per-verb gate: tier comes from the invoked verb, not the tool tier ──
+  assert.strictEqual(tools.runGate(t, ["list"]).ok, true, "read-only verb runs unflagged");
+  assert.strictEqual(tools.runGate(t, ["list"]).tier, "read-only");
+  assert.strictEqual(tools.runGate(t, ["restart", "n1"]).ok, false, "write verb demands --yes");
+  assert.strictEqual(tools.runGate(t, ["restart", "n1", "--yes"]).ok, true);
+  assert.strictEqual(tools.runGate(t, ["purge", "n1", "--yes"]).ok, false, "--yes cannot approve a destructive verb");
+  const purgeGate = tools.runGate(t, ["purge", "n1"]);
+  assert.strictEqual(purgeGate.tier, "destructive", "failed gate reports the resolved tier for the approval fallback");
+  assert.strictEqual(tools.runGate(t, ["purge", "n1", "--yes-destructive"]).ok, true);
+
+  // ── undeclared verb on a manifest tool is refused regardless of flags ──
+  const un = tools.runGate(t, ["obliterate", "--yes-destructive"]);
+  assert.strictEqual(un.ok, false, "undeclared verb refused");
+  assert.strictEqual(un.undeclared, true);
+  assert.ok(/no declared verb "obliterate"/.test(un.message));
+
+  // ── help / no verb = read-only ──
+  assert.strictEqual(tools.runGate(t, []).ok, true, "no verb (help) runs unflagged");
+  assert.strictEqual(tools.runGate(t, ["help"]).tier, "read-only");
+
+  // ── manifest-less tools keep the old whole-tool gate (backward compatible) ──
+  const legacySrc = path.join(tmp, "old.sh");
+  fs.writeFileSync(legacySrc, "#!/usr/bin/env bash\necho old\n");
+  const legacy = tools.addTool(legacySrc, { name: "old", description: "legacy", risk: "write" });
+  assert.strictEqual(legacy.manifest.length, 0);
+  assert.strictEqual(tools.runGate(legacy, ["anything"]).ok, false, "manifest-less write tool still needs --yes");
+  assert.strictEqual(tools.runGate(legacy, ["anything", "--yes"]).ok, true, "…and any verb is allowed with it");
+
+  // ── nested composition still gates on the inherited tier, per verb ──
+  const env = { OPEN_CLAUDIA_TOOL_STACK: "outer", OPEN_CLAUDIA_APPROVED_TIER: "write" };
+  assert.strictEqual(tools.runGate(t, ["restart", "n1"], env).ok, true, "nested write verb ok under write approval");
+  assert.strictEqual(tools.runGate(t, ["purge", "n1", "--yes-destructive"], env).ok, false,
+    "nested destructive verb can't self-approve with argv flags");
+
+  // ── fingerprint lifecycle: never-verified → verified (green run) → changed (edit) ──
+  assert.strictEqual(tools.fingerprint("fleet").status, "never-verified");
+  tools.recordRunResult("fleet", { args: ["list"], exit: 0, ms: 5, tier: "read-only" });
+  assert.strictEqual(tools.fingerprint("fleet").status, "verified", "exit-0 run stamps the hash");
+  fs.appendFileSync(t.file, "# touched\n");
+  assert.strictEqual(tools.fingerprint("fleet").status, "changed", "source edit flags unverified-since-change");
+  tools.recordRunResult("fleet", { args: ["list"], exit: 1, ms: 5 });
+  assert.strictEqual(tools.fingerprint("fleet").status, "changed", "a failing run does NOT re-verify");
+  tools.recordRunResult("fleet", { args: ["list"], exit: 0, ms: 5 });
+  assert.strictEqual(tools.fingerprint("fleet").status, "verified", "next green run re-verifies");
+
+  // ── telemetry carries the acknowledged tier + approval channel ──
+  tools.recordRunResult("fleet", { args: ["purge", "n1"], exit: 0, ms: 9, tier: "destructive", approvedVia: "chat-approval" });
+  const st = JSON.parse(fs.readFileSync(path.join(process.env.TOOLS_DIR, "fleet", "state.json"), "utf-8"));
+  const last = st.history[0]; // history is newest-first
+  assert.strictEqual(last.tier, "destructive");
+  assert.strictEqual(last.approvedVia, "chat-approval");
+
+  // ── approvals: create → decide is idempotent, wait resolves, timeout = fail-closed ──
+  const rec = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: "open-claudia tool run fleet purge n1", channelId: "c1", adapter: "tg" });
+  assert.strictEqual(approvals.read(rec.id).status, "pending");
+  const waiter = approvals.waitForDecision(rec.id, { timeoutMs: 5000, pollMs: 50 });
+  approvals.decide(rec.id, "approved", "c1");
+  assert.strictEqual(await waiter, "approved");
+  const flipped = approvals.decide(rec.id, "denied", "c1");
+  assert.strictEqual(flipped.status, "approved", "second press cannot overturn the first decision");
+
+  const rec2 = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: "x", channelId: "c1", adapter: "tg" });
+  assert.strictEqual(await approvals.waitForDecision(rec2.id, { timeoutMs: 200, pollMs: 50 }), "timeout",
+    "no decision = timeout, which callers treat as denied");
+  const rec3 = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: "x", channelId: "c1", adapter: "tg" });
+  approvals.decide(rec3.id, "denied", "c1");
+  assert.strictEqual(await approvals.waitForDecision(rec3.id, { timeoutMs: 5000, pollMs: 50 }), "denied");
+
+  console.log("tool manifest OK");
+})().catch((e) => { console.error(e); process.exit(1); });

package/test-tooling-mode.js

@@ -0,0 +1,44 @@
+// Tooling-mode switch: strict denies, relaxed logs-and-allows, fail-safe strict.
+// The prod-URL fixture is assembled from parts so the live deny-gate (which
+// pattern-matches the raw Bash command text) doesn't block running this test.
+process.env.TOOLING_MODE_FILE = "/tmp/oc-test-tooling-mode.json";
+process.env.TOOL_GUARD_LOG = "/tmp/oc-test-tooling-mode-guard.jsonl";
+
+const fs = require("fs");
+const assert = require("assert");
+for (const f of [process.env.TOOLING_MODE_FILE, process.env.TOOL_GUARD_LOG]) {
+  try { fs.unlinkSync(f); } catch (e) {}
+}
+
+const tm = require("./core/tooling-mode");
+const tg = require("./core/tool-guard");
+
+const host = ["central", "inet", "africa"].join(".");
+const cmd = ["cu", "rl"].join("") + " https://" + host + "/api/users";
+const payload = JSON.stringify({ tool_name: "Bash", tool_input: { command: cmd } });
+
+// Default (no mode file) = strict → deny.
+assert.strictEqual(tm.getToolingMode(), "strict");
+assert.strictEqual(tg.runHook(payload).exit, 2, "strict should deny");
+
+// Relaxed → allow, logged as relaxed-pass (not deny) for the KPI pass.
+tm.setToolingMode("relaxed");
+assert.strictEqual(tm.getToolingMode(), "relaxed");
+assert.strictEqual(tg.runHook(payload).exit, 0, "relaxed should allow");
+const evts = tg.readGuardEvents();
+assert.strictEqual(evts.denies.length, 1);
+assert.strictEqual(evts.relaxedPasses.length, 1);
+
+// Switch back is instant — next hook call re-reads the file.
+tm.setToolingMode("strict");
+assert.strictEqual(tg.runHook(payload).exit, 2, "strict again should deny");
+
+// Invalid mode refused; corrupt file fails safe to strict.
+assert.throws(() => tm.setToolingMode("yolo"));
+fs.writeFileSync(process.env.TOOLING_MODE_FILE, "not json");
+assert.strictEqual(tm.getToolingMode(), "strict");
+
+for (const f of [process.env.TOOLING_MODE_FILE, process.env.TOOL_GUARD_LOG]) {
+  try { fs.unlinkSync(f); } catch (e) {}
+}
+console.log("tooling mode OK");

package/test-tools.js

@@ -438,6 +438,34 @@ assert.ok(!cycle.ok && /cycle/i.test(cycle.message), "a tool already in the call
 const topLevel = tools.runGate({ name: "kticket", risk: "write" }, ["--yes"], {});
 assert.ok(topLevel.ok && !topLevel.nested, "no stack env → the classic argv-flag gate applies");
 
+// ── verbDoc: one mechanical sentence per verb, parsed from the header docs ──
+// Covers both documented shapes (indented-description-below and same-line
+// prose after 2+ spaces), the description fallback, and the unknown-tool "".
+const srcV = path.join(tmp, "vdoc.js");
+fs.writeFileSync(srcV, [
+  "#!/usr/bin/env node",
+  "// open-claudia-tool: vdoc",
+  "// description: Query the demo platform (demo.example) as operator — login, list things, show one thing",
+  "// risk: read-only",
+  "// usage: vdoc <verb> [args]",
+  "//",
+  "//   vdoc list [--stage a,b] [--json]",
+  "//       List things. Filters are regexes and",
+  "//       combine with AND.",
+  "//   vdoc peek [regex]      look at things; optional case-insensitive filter",
+  "//   vdoc stages",
+  "console.log('hi');",
+].join("\n"));
+tools.addTool(srcV, { name: "vdoc" });
+assert.strictEqual(tools.verbDoc("vdoc", "list"), "List things", "indented description below the verb line, cut at first sentence");
+assert.strictEqual(tools.verbDoc("vdoc", "peek"), "look at things; optional case-insensitive filter", "same-line prose after 2+ spaces");
+assert.strictEqual(tools.verbDoc("vdoc", "stages"), "Query the demo platform (demo.example) as operator",
+  "undocumented-body verb falls back to the description's first clause");
+assert.strictEqual(tools.verbDoc("vdoc", ""), "Query the demo platform (demo.example) as operator", "no verb → description clause");
+assert.strictEqual(tools.verbDoc("vdoc", "--json"), "Query the demo platform (demo.example) as operator", "flag token is not a verb");
+assert.strictEqual(tools.verbDoc("no-such-tool", "list"), "", "unknown tool → empty string");
+tools.removeTool("vdoc");
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");