@inetafrica/open-claudia 2.7.4 → 2.7.6

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## v2.7.4
+## 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.
+- **Umbrella grouping from registry tags (Phase 4).** Tools gain an optional `tags:` header field (`--tags` on `scaffold`/`add`/`set`, sanitised, strong-match in `tool search`); `tool list` renders the first tag as an umbrella group — `kazee/{kchat,kticket}`, `infra/{prod-k8s}` — with untagged tools flat below. Purely presentational: "Kazee" stays a registry grouping, never a binary. The fixed system-prompt tools section gains one composition bullet (approval is inherited, never fabricated; `_lib` marks dependents unverified). Test coverage: tags round-trip, lib dependent grep boundaries, setLib journaling, and the full nested-gate matrix including the fabrication and cycle refusals.
 - **The dream now audits tool usage — raw-op detector + usage KPI (Phase 3/item 9 + enforcement 5c).** The guard log knew about *blocked* commands (denies) and *authorised* one-offs (`keyring exec` bypasses), but operational work done raw that the gate didn't cover — inline heredoc scripts fed to an interpreter, raw DB clients, mutating `kubectl` — left no trace, so the tool-usage KPI had a blind spot exactly where the "repeated heredocs slip through" failure lives. New deterministic detector in `core/tool-guard.js` (`matchRawOp`/`noteRawOp`): high-precision patterns (`heredoc-interpreter`, `db-client`, `kubectl-mutate`), wired into the runner's Bash-stream chokepoint so every command is observed — **observation only, never blocking**; the authorised channels and anything the deny-gate already owns are skipped so one command never yields two guard events. Reads (`kubectl get/logs`, `rollout status`, `cat <<EOF` file writes, mentioning a client in grep) stay unflagged.
 - **Doc/code drift flag completes the dream tool-pass.** Alongside the existing hygiene flags (dangling pack links, cold never-run tools, near-duplicate pairs), the pass now flags tools whose source was edited after TOOL.md was last touched, and verbs that telemetry proves are in real use but the docs never mention (`tools.docDrift()`; `help`/`(default)` ignored). Flag only — the fix is a `tool note`. Zero false flags on the live 12-tool registry at ship time.
 - **Nightly KPI in the dream report, computed from stamps — never prose.** The dream's tool pass now appends `📈 Tool usage since last dream`: % of operational actions via `tool run` (target >90%, denominator = tool runs + escape-hatch bypasses + raw-op sightings; gate denies reported separately since blocked ≠ completed), bypass count **with reasons**, raw-ops by pattern, and failure-at-use counts naming the failing tools. Sources are `state.json` run-history stamps (new `tools.runsSince(sinceTs)`) + `tool-guard.jsonl` (new `readGuardEvents(sinceTs)`) — per the plan, the KPI is never parsed out of conversation prose. Escape-hatch bypasses surface in the dream report only (no immediate chat pings — pings would train us both to ignore them). Test coverage: raw-op matrix incl. no-double-count with denies, event grouping/windowing, `runsSince` window math.

package/bin/tool.js

@@ -2,20 +2,21 @@
 // through. Tool-first loop: search → exists: use it → missing a verb: extend →
 // nothing: scaffold, then work through the tool.
 //
-//   open-claudia tool list                       — index (name — description [skill])
+//   open-claudia tool list                       — index, grouped by first tag (kazee/, infra/, …)
 //   open-claudia tool search <query>             — lexical match (find before adding a dup)
 //   open-claudia tool show <name> [--source]     — TOOL.md, telemetry, history (source with --source)
 //   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"] [--usage "..."] [--lang node|bash]
+//       [--requires "k1,k2"] [--tags "group"] [--usage "..."] [--lang node|bash]
 //   open-claudia tool add <path> [--name n]      — register an existing script as a tool
-//       [--pack <dir>] [--desc "..."] [--risk tier] [--requires "k1,k2"] [--usage "..."]
+//       [--pack <dir>] [--desc "..."] [--risk tier] [--requires "k1,k2"] [--tags "group"] [--usage "..."]
 //   open-claudia tool set <name> [--desc ...]    — fix a tool's metadata in place
-//       [--pack <dir>] [--risk tier] [--requires "k1,k2"] [--usage "..."]
+//       [--pack <dir>] [--risk tier] [--requires "k1,k2"] [--tags "group"] [--usage "..."]
 //   open-claudia tool note <name>                — append to TOOL.md (auto-committed)
 //       [--issue "..."] [--state "..."] [--journal "..."]
 //   open-claudia tool edit <name>                — print the file path to open & edit
 //   open-claudia tool run <name> [args...]       — run it (keyring pre-loaded, risk-gated)
+//   open-claudia tool lib [list|show|set] ...    — shared _lib plumbing tools import (see below)
 //   open-claudia tool migrate                    — convert legacy flat-file tools to directories
 //   open-claudia tool remove <name>              — delete one
 //   open-claudia tool path                       — print the tools directory
@@ -38,6 +39,13 @@
 // it declares via --requires — reference them as $NAME inside the script and
 // declare every one. `open-claudia keyring list` shows what exists; never
 // hardcode secrets in a tool. Undeclared keys simply won't be in the env.
+//
+// Composition (Phase 4): a tool may shell into other tools (report → kticket).
+// Approval is inherited, never fabricated: the runner exports the tier the
+// OUTER flags acknowledged, and a nested `tool run` gates on that inherited
+// tier while ignoring its own argv flags. Shared plumbing lives in _lib/
+// (`tool lib set <name> <src>`); a lib change journals every dependent tool
+// "unverified since _lib change" — re-verified by its next real use.
 
 const { spawnSync } = require("child_process");
 const tools = require("../core/tools");
@@ -124,10 +132,31 @@ function run(args) {
         return console.log(`No tools yet (${tools.TOOLS_DIR}).\nSave one with: open-claudia tool add <script-path> --pack <skill>`);
       }
       console.log(`${all.length} reusable tool(s) — run via 'open-claudia tool run <name>':\n`);
-      for (const t of all) {
+      const bullet = (t, indent = "") => {
         const skill = t.pack ? `  [skill: ${t.pack}]` : "";
         const risk = t.risk === "read-only" ? "" : `  [${t.risk || "write?"}]`;
-        console.log(`• ${t.name} — ${t.description || "(no description)"}${skill}${risk}`);
+        console.log(`${indent}• ${t.name} — ${t.description || "(no description)"}${skill}${risk}`);
+      };
+      // Umbrella grouping from registry tags: first tag is the group
+      // (kazee/{kticket,…}); untagged tools render flat. Purely presentational —
+      // groups are tags, never binaries.
+      const groups = new Map();
+      for (const t of all) {
+        const g = (t.tags && t.tags[0]) || "";
+        if (!groups.has(g)) groups.set(g, []);
+        groups.get(g).push(t);
+      }
+      if (groups.size === 1 && groups.has("")) {
+        for (const t of all) bullet(t);
+      } else {
+        for (const g of [...groups.keys()].filter(Boolean).sort()) {
+          console.log(`${g}/`);
+          for (const t of groups.get(g)) bullet(t, "  ");
+        }
+        if (groups.has("")) {
+          console.log("");
+          for (const t of groups.get("")) bullet(t);
+        }
       }
       console.log(`\nDocs: open-claudia tool show <name>   ·   Dir: ${tools.TOOLS_DIR}`);
       break;
@@ -162,6 +191,7 @@ function run(args) {
       console.log(`Tool: ${t.name}`);
       if (t.description) console.log(`Description: ${t.description}`);
       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)"}`);
       console.log(`Usage: open-claudia tool run ${t.name}${t.usage ? "   (" + t.usage + ")" : ""}`);
       if (t.requires.length) {
@@ -228,6 +258,7 @@ function run(args) {
           description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
           risk: typeof flags.risk === "string" ? flags.risk : undefined,
           requires: typeof flags.requires === "string" ? flags.requires.split(/[,\s]+/).filter(Boolean) : undefined,
+          tags: typeof flags.tags === "string" ? flags.tags.split(/[,\s]+/).filter(Boolean) : undefined,
           usage: typeof flags.usage === "string" ? flags.usage : undefined,
         });
         console.log(`Saved tool "${t.name}"${t.pack ? ` (skill: ${t.pack})` : ""} — risk: ${t.risk}.`);
@@ -276,9 +307,10 @@ function run(args) {
       if (typeof flags.pack === "string") patch.pack = flags.pack;
       if (typeof flags.risk === "string") patch.risk = flags.risk;
       if (typeof flags.requires === "string") patch.requires = flags.requires.split(/[,\s]+/).filter(Boolean);
+      if (typeof flags.tags === "string") patch.tags = flags.tags.split(/[,\s]+/).filter(Boolean);
       if (typeof flags.usage === "string") patch.usage = flags.usage;
       if (Object.keys(patch).length === 0) {
-        console.error('Nothing to set. Pass at least one of --desc / --pack / --risk / --requires / --usage. Body edits: open-claudia tool edit ' + name);
+        console.error('Nothing to set. Pass at least one of --desc / --pack / --risk / --requires / --tags / --usage. Body edits: open-claudia tool edit ' + name);
         process.exitCode = 1; return;
       }
       let updated;
@@ -290,6 +322,7 @@ function run(args) {
       if (updated.pack) console.log(`  Skill pack:  ${updated.pack}`);
       console.log(`  Risk:        ${updated.risk || "(undeclared — treated as write)"}`);
       if (updated.requires.length) console.log(`  Requires:    ${updated.requires.join(", ")}`);
+      if (updated.tags && updated.tags.length) console.log(`  Tags:        ${updated.tags.join(", ")}`);
       if (updated.usage) console.log(`  Usage:       ${updated.usage}`);
       reportSafety(updated);
       break;
@@ -317,7 +350,9 @@ function run(args) {
 
       // Risk-tier gate: write needs --yes, destructive needs --yes-destructive.
       // The flag is passed through to the tool (which may have its own gate).
-      const gate = tools.runGate(t, toolArgs);
+      // 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; }
 
       const missing = tools.missingRequires(t);
@@ -325,8 +360,17 @@ function run(args) {
         console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
         process.exitCode = 1; return;
       }
+      // 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.
+      const env = tools.runEnv(t);
+      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);
+      env.OPEN_CLAUDIA_TOOL_STACK = parentStack ? `${parentStack}>${t.name}` : t.name;
       const started = Date.now();
-      const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env: tools.runEnv(t) });
+      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 });
@@ -348,7 +392,7 @@ 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"] [--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]');
         process.exitCode = 1; return;
       }
       try {
@@ -357,6 +401,7 @@ function run(args) {
           description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
           risk: typeof flags.risk === "string" ? flags.risk : undefined,
           requires: typeof flags.requires === "string" ? flags.requires.split(/[,\s]+/).filter(Boolean) : [],
+          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",
         });
@@ -410,6 +455,60 @@ function run(args) {
       break;
     }
 
+    case "lib": {
+      const sub = (rest[0] || "list").toLowerCase();
+      const libArgs = rest.slice(1);
+      if (sub === "list" || sub === "ls") {
+        const libs = tools.listLib();
+        if (!libs.length) {
+          console.log(`No shared _lib modules yet (${tools.LIB_DIR}).`);
+          console.log('Add one: open-claudia tool lib set <name.js> <src-path>  — for plumbing 2+ tools share (central auth, mongo-exec).');
+          return;
+        }
+        console.log(`${libs.length} shared _lib module(s) — imported by tools via a literal "_lib/<name>" path:\n`);
+        for (const l of libs) {
+          const deps = tools.libDependents(l.name);
+          console.log(`• ${l.name} (${l.size} bytes, ${l.updatedAt.slice(0, 10)})${deps.length ? ` — used by: ${deps.join(", ")}` : " — no dependents yet"}`);
+        }
+        console.log(`\nnode: require(\`\${__dirname}/../_lib/<name>.js\`)   ·   bash: source "$(dirname "$0")/../_lib/<name>.sh"`);
+        break;
+      }
+      if (sub === "show" || sub === "cat") {
+        const name = libArgs[0];
+        if (!name) { console.error("Usage: tool lib show <name>"); process.exitCode = 1; return; }
+        const content = tools.readLib(name);
+        if (content === null) { console.error(`No _lib module "${name}". Run: open-claudia tool lib list`); process.exitCode = 1; return; }
+        const deps = tools.libDependents(name);
+        console.log(`_lib/${name} — used by: ${deps.length ? deps.join(", ") : "(no dependents yet)"}\n`);
+        console.log(content);
+        break;
+      }
+      if (sub === "set" || sub === "add") {
+        const name = libArgs[0];
+        const srcPath = libArgs[1];
+        if (!name || !srcPath) { console.error("Usage: tool lib set <name.js> <src-path>"); process.exitCode = 1; return; }
+        let content;
+        try { content = require("fs").readFileSync(srcPath, "utf-8"); }
+        catch (e) { console.error(`Cannot read ${srcPath}: ${e.message}`); process.exitCode = 1; return; }
+        try {
+          const r = repo.setLib(name, content);
+          console.log(`${r.existed ? "Updated" : "Added"} _lib/${r.name}.`);
+          if (r.dependents.length) {
+            console.log(`Dependents journaled as unverified until their next real use: ${r.dependents.join(", ")}.`);
+            console.log("Re-verify each by simply using it — a green run at point of use is the health check.");
+          } else {
+            console.log("No dependents yet — tools import it via a literal \"_lib/" + r.name.replace(/\.[^.]+$/, "") + "\" path.");
+          }
+        } catch (e) {
+          console.error(`Could not set _lib module: ${e.message}`); process.exitCode = 1;
+        }
+        break;
+      }
+      console.error("Usage: tool lib [list | show <name> | set <name.js> <src-path>]");
+      process.exitCode = 1;
+      break;
+    }
+
     case "migrate": {
       const { migrated, skipped } = repo.migrateLegacyTools();
       if (!migrated.length && !skipped.length) console.log("Nothing to migrate — all tools already use the directory layout.");
@@ -432,7 +531,7 @@ function run(args) {
       break;
 
     default:
-      console.log('Usage: open-claudia tool [list | search <query> | show <name> [--source] | scaffold <name> [flags] | add <path> [flags] | set <name> [flags] | note <name> [flags] | edit <name> | run <name> [args] | migrate | remove <name> | path]');
+      console.log('Usage: open-claudia tool [list | search <query> | show <name> [--source] | scaffold <name> [flags] | add <path> [flags] | set <name> [flags] | note <name> [flags] | edit <name> | run <name> [args] | lib [list|show|set] | migrate | remove <name> | path]');
   }
 }
 

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

@@ -98,7 +98,8 @@ Raw shell one-liners and heredocs are for probing and diagnosis only — never t
 - 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.
-- Announce in one line when you scaffold or change a tool, same as packs. Full CLI: \`open-claudia tool list|search|show|scaffold|add|set|note|edit|run|migrate|remove\`.
+- Composition: a tool may shell into other tools (report → kticket + kchat). Approval is inherited, never fabricated — a nested callee runs at most at the tier YOUR outer \`tool run\` flags acknowledged, so pass --yes/--yes-destructive on the outer call (after user approval) when the composition writes. Shared plumbing lives in \`_lib/\` (\`tool lib list|show|set\`); a lib change marks each dependent "unverified since _lib change" until its next real use.
+- Announce in one line when you scaffold or change a tool, same as packs. Full CLI: \`open-claudia tool list|search|show|scaffold|add|set|note|edit|run|lib|migrate|remove\`.
 ${listing}`;
 }
 

package/core/tool-repo.js

@@ -64,6 +64,32 @@ function commitTool(name, message) {
   return git(["commit", "-q", "-m", message], { ident: true }).ok;
 }
 
+// Write/update a shared _lib module, then journal every dependent tool as
+// "unverified since _lib change" and commit the lot in ONE commit whose message
+// names the dependents (PLAN §3.5: a _lib change can break several tools at
+// once; each is re-verified by its next real use, not by smoke tests).
+// Commits with target "." — sanitizeName would mangle "_lib", and the commit
+// must carry the dependents' TOOL.md marks anyway.
+function setLib(name, content) {
+  const tools = require("./tools");
+  ensureRepo();
+  const existed = tools.readLib(name) !== null;
+  const { name: libName, file } = tools.writeLib(name, content);
+  const dependents = tools.libDependents(libName);
+  for (const dep of dependents) {
+    const t = tools.findTool(dep);
+    if (!t || !t.docFile) continue;
+    let doc = tools.readToolDoc(dep) || toolMdSkeleton(t);
+    const line = `- [${today()}] unverified since _lib change (${libName}) — re-verified by next real use.`;
+    const re = /(##\s*Journal[^\n]*\n)/i;
+    doc = re.test(doc) ? doc.replace(re, `$1${line}\n`) : doc + `\n## Journal\n${line}\n`;
+    try { fs.writeFileSync(t.docFile, doc, { mode: 0o600 }); } catch (e) { /* journal is best-effort */ }
+  }
+  const depNote = dependents.length ? `dependents: ${dependents.join(", ")} (unverified until next use)` : "no dependents yet";
+  commitTool(null, `lib ${libName}: ${existed ? "update" : "add"} — ${depNote}`);
+  return { name: libName, file, dependents, existed };
+}
+
 // Recent history for one tool — surfaced by `tool show` as the upgrade log.
 function toolLog(name, limit = 5) {
   const n = require("./tools").sanitizeName(name);
@@ -98,13 +124,14 @@ function toolMdSkeleton({ name, description, usage, risk, requires, pack, stateL
   ].join("\n");
 }
 
-function nodeStub({ name, description, pack, risk, requires, usage }) {
+function nodeStub({ name, description, pack, risk, requires, usage, tags }) {
   const req = requires && requires.length ? `// requires: ${requires.join(", ")}\n` : "";
+  const tag = tags && tags.length ? `// tags: ${tags.join(", ")}\n` : "";
   return `#!/usr/bin/env node
 // open-claudia-tool: ${name}
 // description: ${description || ""}
 ${pack ? `// pack: ${pack}\n` : ""}// risk: ${risk}
-${req}// usage: ${usage || `${name} <verb> [args]`}
+${req}${tag}// usage: ${usage || `${name} <verb> [args]`}
 //
 // One CLI per system, verbs as subcommands. Add a function per verb below.
 // Confirmation flags (--yes / --yes-destructive) are enforced by the tool
@@ -127,13 +154,14 @@ Promise.resolve(fn(args.slice(1))).catch((e) => { console.error(e.message || e);
 `;
 }
 
-function bashStub({ name, description, pack, risk, requires, usage }) {
+function bashStub({ name, description, pack, risk, requires, usage, tags }) {
   const req = requires && requires.length ? `# requires: ${requires.join(", ")}\n` : "";
+  const tag = tags && tags.length ? `# tags: ${tags.join(", ")}\n` : "";
   return `#!/usr/bin/env bash
 # open-claudia-tool: ${name}
 # description: ${description || ""}
 ${pack ? `# pack: ${pack}\n` : ""}# risk: ${risk}
-${req}# usage: ${usage || `${name} <verb> [args]`}
+${req}${tag}# usage: ${usage || `${name} <verb> [args]`}
 #
 # One CLI per system, verbs as subcommands: add a case per verb below.
 # Confirmation flags (--yes / --yes-destructive) are enforced by the tool
@@ -163,7 +191,8 @@ function scaffoldTool(name, opts = {}) {
   if (tools.findTool(n)) throw new Error(`tool "${n}" already exists — extend it (tool edit ${n}) instead of re-scaffolding`);
   const risk = tools.normalizeRisk(opts.risk) || "write";
   const requires = [].concat(opts.requires || []).filter(Boolean);
-  const spec = { name: n, description: opts.description || "", pack: opts.pack || "", risk, requires, usage: opts.usage || "" };
+  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 || "" };
 
   ensureRepo();
   const dir = path.join(toolsDir(), n);
@@ -267,4 +296,4 @@ function hasLegacyTools() {
   return false;
 }
 
-module.exports = { ensureRepo, commitTool, toolLog, scaffoldTool, migrateLegacyTools, hasLegacyTools, toolMdSkeleton };
+module.exports = { ensureRepo, commitTool, setLib, toolLog, scaffoldTool, migrateLegacyTools, hasLegacyTools, toolMdSkeleton };

package/core/tools.js

@@ -36,7 +36,7 @@ const TOOLS_DIR = process.env.TOOLS_DIR ? path.resolve(process.env.TOOLS_DIR) :
 // parse from the leading comment block. Language-agnostic: we accept "#" (sh,
 // python, ruby) and "//" (js, ts, go) comment prefixes.
 const MARKER = "open-claudia-tool";
-const HEADER_KEYS = ["description", "pack", "requires", "usage", "risk"];
+const HEADER_KEYS = ["description", "pack", "requires", "usage", "risk", "tags"];
 const RISK_TIERS = ["read-only", "write", "destructive"];
 
 // Normalise a risk value to one of RISK_TIERS ("" when unrecognised). Blast
@@ -219,7 +219,7 @@ function matchTools(text, { limit = 5, threshold = null } = {}) {
   const min = threshold ?? Number(process.env.TOOL_MATCH_THRESHOLD || 2);
   const out = [];
   for (const t of listTools()) {
-    const strong = wordsOf([t.name, t.description, t.usage].filter(Boolean).join(" "));
+    const strong = wordsOf([t.name, t.description, t.usage, (t.tags || []).join(" ")].filter(Boolean).join(" "));
     const weak = wordsOf([(t.requires || []).join(" "), t.pack, t.content].filter(Boolean).join(" "));
     let score = 0;
     for (const term of terms) {
@@ -244,7 +244,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: "" };
+  const out = { name: "", description: "", pack: "", requires: [], usage: "", risk: "", tags: [] };
   const lines = String(content || "").split("\n");
   let started = false;
   for (let i = 0; i < lines.length; i++) {
@@ -264,11 +264,76 @@ function parseHeader(content) {
     if (key === MARKER) out.name = sanitizeName(val);
     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 (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;
+  // 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) {
@@ -293,6 +358,7 @@ function readTool(name, usageMap) {
     requires: header.requires || [],
     usage: header.usage || "",
     risk: header.risk || "",
+    tags: header.tags || [],
     layout: p.layout,
     file: p.exec,
     docFile: p.doc,
@@ -356,7 +422,7 @@ function listTools() {
   const usage = readUsage();
   const tools = [];
   for (const name of entries) {
-    if (name.startsWith(".")) continue;
+    if (name.startsWith(".") || name.startsWith("_")) continue; // _lib etc. — plumbing, not tools
     const full = path.join(TOOLS_DIR, name);
     let st;
     try { st = fs.statSync(full); } catch (e) { continue; }
@@ -413,14 +479,75 @@ function docDrift(t) {
   return null;
 }
 
+// ── _lib shared plumbing ─────────────────────────────────────────────────────
+// Genuinely shared code (central auth, mongo-exec) lives in tools/_lib — tiny
+// modules IMPORTED by tools, never tools themselves (listTools skips the "_"
+// prefix, so _lib never appears in the registry or surfacing index). Import
+// with a literal "_lib/<name>" path so dependents stay grep-detectable:
+//   node: require(`${__dirname}/../_lib/<name>.js`)
+//   bash: source "$(dirname "$0")/../_lib/<name>.sh"
+// A _lib change can break several tools at once, so every change is committed
+// with its dependents named and each dependent journaled "unverified since
+// _lib change" — re-verified by its next real use (no smoke tests, by design).
+const LIB_DIR = path.join(TOOLS_DIR, "_lib");
+
+function libPath(name) {
+  const base = path.basename(String(name || "").trim());
+  if (!base || base.startsWith(".")) throw new Error(`invalid lib name "${name}"`);
+  return path.join(LIB_DIR, base);
+}
+
+function listLib() {
+  let entries;
+  try { entries = fs.readdirSync(LIB_DIR); } catch (e) { return []; }
+  const out = [];
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    try {
+      const st = fs.statSync(path.join(LIB_DIR, name));
+      if (st.isFile()) out.push({ name, file: path.join(LIB_DIR, name), size: st.size, updatedAt: st.mtime.toISOString() });
+    } catch (e) { /* unreadable entry — skip */ }
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+function readLib(name) {
+  try { return fs.readFileSync(libPath(name), "utf-8"); } catch (e) { return null; }
+}
+
+function writeLib(name, content) {
+  const file = libPath(name);
+  assertNoSecrets(content, `_lib/${path.basename(file)}`);
+  fs.mkdirSync(LIB_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, content, { mode: 0o600 });
+  return { name: path.basename(file), file };
+}
+
+// Which registered tools import a given lib — a deterministic source grep for
+// the "_lib/<stem>" reference shape (tolerates path.join'd segments), so a lib
+// change can name exactly the tools it may have broken. Extension-agnostic but
+// boundary-safe: "central-auth" matches _lib/central-auth.js, not
+// _lib/central-auth-v2.js.
+function libDependents(name) {
+  const base = path.basename(String(name || "").trim());
+  if (!base) return [];
+  const stem = base.replace(/\.[^.]+$/, "");
+  const esc = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`_lib[/\\\\"'\\s,]{1,5}["']?${esc}(?:\\.[A-Za-z0-9]+)?(?![A-Za-z0-9._-])`);
+  return listTools().filter((t) => re.test(t.content || "")).map((t) => t.name);
+}
+
 // Build the header comment block for a script that doesn't already declare one.
 // Uses the comment prefix that matches the script's shebang/extension.
-function buildHeader(prefix, { name, description, pack, requires, usage, risk }) {
+function buildHeader(prefix, { name, description, pack, requires, usage, risk, tags }) {
   const lines = [`${prefix} ${MARKER}: ${name}`];
   if (description) lines.push(`${prefix} description: ${description}`);
   if (pack) lines.push(`${prefix} pack: ${pack}`);
   if (risk) lines.push(`${prefix} risk: ${risk}`);
   if (requires && requires.length) lines.push(`${prefix} requires: ${[].concat(requires).join(", ")}`);
+  const cleanTags = [].concat(tags || []).map((s) => sanitizeName(s)).filter(Boolean);
+  if (cleanTags.length) lines.push(`${prefix} tags: ${cleanTags.join(", ")}`);
   if (usage) lines.push(`${prefix} usage: ${usage}`);
   return lines.join("\n");
 }
@@ -549,6 +676,7 @@ function addTool(srcPath, opts = {}) {
       pack: opts.pack || "",
       risk,
       requires: opts.requires || [],
+      tags: opts.tags || [],
       usage: opts.usage || "",
     });
     const hasShebang = content.startsWith("#!");
@@ -565,6 +693,7 @@ function addTool(srcPath, opts = {}) {
       content = content.replace(new RegExp(`((#|//)\\s*${MARKER}:.*\\n)`), `$1${line}\n`);
     };
     if (opts.pack && !header.pack) injectAfterMarker(`${prefix} pack: ${opts.pack}`);
+    if (opts.tags && opts.tags.length && !header.tags.length) injectAfterMarker(`${prefix} tags: ${[].concat(opts.tags).map((s) => sanitizeName(s)).filter(Boolean).join(", ")}`);
     if (!header.risk) {
       const risk = optRisk || "write";
       if (!optRisk) defaultedRisk = true;
@@ -635,6 +764,9 @@ function updateToolHeader(name, opts = {}) {
   }
   let requires = opts.requires !== undefined ? opts.requires : t.requires;
   if (!Array.isArray(requires)) requires = String(requires || "").split(/[,\s]+/).filter(Boolean);
+  let tags = opts.tags !== undefined ? opts.tags : t.tags;
+  if (!Array.isArray(tags)) tags = String(tags || "").split(/[,\s]+/).filter(Boolean);
+  tags = tags.map((s) => sanitizeName(s)).filter(Boolean);
 
   const lines = t.content.split("\n");
   let headStart = 0;
@@ -660,6 +792,7 @@ function updateToolHeader(name, opts = {}) {
   if (pack) fieldLines.push(`${prefix} pack: ${pack}`);
   if (risk) fieldLines.push(`${prefix} risk: ${risk}`);
   if (requires.length) fieldLines.push(`${prefix} requires: ${requires.join(", ")}`);
+  if (tags.length) fieldLines.push(`${prefix} tags: ${tags.join(", ")}`);
   if (usage) fieldLines.push(`${prefix} usage: ${usage}`);
 
   let newBlock;
@@ -680,9 +813,38 @@ function updateToolHeader(name, opts = {}) {
 // unlock it) and gets a spelled-out warning. An undeclared tier is treated as
 // write — fail-safe until classified. The flag is the agent's deliberate
 // confirmation step AFTER user approval; it never replaces asking the user.
-function runGate(tool, argv = []) {
+//
+// Composition (Phase 4): tools may shell into other tools. Approval flows ONLY
+// from the outermost, human-approved invocation — the runner exports the tier
+// its 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 cannot
+// fabricate approval by hardcoding --yes-destructive in its own source.
+const TIER_RANK = { "read-only": 0, write: 1, destructive: 2 };
+
+function approvedTierFromArgv(argv = []) {
+  if (argv.includes("--yes-destructive")) return "destructive";
+  if (argv.includes("--yes")) return "write";
+  return "read-only";
+}
+
+function runGate(tool, argv = [], env = process.env) {
   const declared = normalizeRisk(tool && tool.risk);
   const tier = declared || "write";
+  const stack = String((env && env.OPEN_CLAUDIA_TOOL_STACK) || "").trim();
+  if (stack) {
+    // Nested run — a tool called this tool.
+    if (stack.split(">").includes(tool.name)) {
+      return { ok: false, tier, nested: true, message: `⛔ Tool-call cycle: "${tool.name}" is already running in this chain (${stack}).` };
+    }
+    const approved = normalizeRisk(env.OPEN_CLAUDIA_APPROVED_TIER) || "read-only";
+    if (TIER_RANK[tier] <= TIER_RANK[approved]) return { ok: true, tier, nested: true };
+    return {
+      ok: false, tier, nested: true,
+      message: `⛔ "${tool.name}" is ${tier}-tier but was called by "${stack}", approved only for ${approved} actions.\n` +
+        `A composing tool cannot self-approve. Get the user's approval, then re-run the OUTER tool with ${tier === "destructive" ? "--yes-destructive" : "--yes"}.`,
+    };
+  }
   const note = declared ? "" : ` (no risk tier declared — treated as write; classify: open-claudia tool set ${tool.name} --risk read-only|write|destructive)`;
   if (tier === "read-only") return { ok: true, tier };
   if (tier === "destructive") {
@@ -749,10 +911,11 @@ function toolNameFromPath(filePath) {
 }
 
 module.exports = {
-  TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS,
-  parseHeader, readTool, readToolDoc, toolCondition, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
+  TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS, LIB_DIR,
+  parseHeader, readTool, readToolDoc, toolCondition, verbDoc, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir, normalizeRisk,
-  toolPaths, readState, writeState, recordRunResult, runGate,
+  toolPaths, readState, writeState, recordRunResult, runGate, approvedTierFromArgv,
+  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.4",
+  "version": "2.7.6",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {

package/test-tools.js

@@ -362,6 +362,110 @@ fs.utimesSync(tools.findTool("condtool").file, future, future);
 assert.strictEqual(tools.docDrift(tools.findTool("condtool")), "source newer than TOOL.md", "source edited after docs is drift");
 assert.strictEqual(tools.docDrift(null), null, "no tool → no drift");
 
+// ── tags (Phase 4 umbrella grouping): round-trip through the header, settable,
+//    sanitised, and part of the STRONG match haystack ──
+const tagSrc = path.join(tmp, "kgadget.sh");
+fs.writeFileSync(tagSrc, "#!/usr/bin/env bash\necho g\n");
+const tagged = tools.addTool(tagSrc, { name: "kgadget", description: "gadget ops", risk: "read-only", tags: ["Kazee"] });
+assert.deepStrictEqual(tagged.tags, ["kazee"], "tags parse back from the header, sanitised to lowercase");
+assert.ok(/# tags: kazee/.test(tagged.content), "tags land as a header line");
+assert.ok(tools.matchTools("kazee").some((m) => m.name === "kgadget"), "a tag term matches strongly");
+const retagged = tools.updateToolHeader("kgadget", { tags: "kazee, infra" });
+assert.deepStrictEqual(retagged.tags, ["kazee", "infra"], "updateToolHeader sets tags from a comma string");
+assert.strictEqual((retagged.content.match(/# tags:/g) || []).length, 1, "tags line survives exactly once");
+const scTagged = repo.scaffoldTool("ktagged", { description: "tagged scaffold", risk: "read-only", tags: ["infra"] });
+assert.deepStrictEqual(scTagged.tags, ["infra"], "scaffold carries tags into the stub header");
+
+// ── _lib shared plumbing (Phase 4): invisible to the registry, secret-guarded,
+//    dependents found by a boundary-safe source grep ──
+tools.writeLib("central-auth.js", "module.exports = { login() { return process.env.inet_central_user; } };\n");
+assert.ok(tools.readLib("central-auth.js").includes("login()"), "writeLib/readLib round-trip");
+assert.ok(tools.listLib().some((l) => l.name === "central-auth.js"), "listLib sees the module");
+assert.ok(!tools.listTools().some((t) => t.name.startsWith("_") || t.name === "lib"), "_lib never appears in the tool registry");
+assert.strictEqual(tools.readLib("nope.js"), null, "missing lib reads as null");
+assert.throws(() => tools.writeLib("leak.js", 'const k = "sk-ant-abcdefgh12345678";\n'), /secret/i, "a hardcoded secret blocks a lib save");
+const trav = tools.writeLib("../escape.js", "// harmless\n");
+assert.strictEqual(path.dirname(trav.file), tools.LIB_DIR, "path traversal is neutralised — basename only, stays inside _lib");
+assert.throws(() => tools.writeLib(".hidden", "x"), /invalid lib name/i, "dot-prefixed lib names are refused");
+
+const depA = path.join(tmp, "authuser.sh");
+fs.writeFileSync(depA, '#!/usr/bin/env bash\nsource "$(dirname "$0")/../_lib/central-auth.js"\n');
+tools.addTool(depA, { name: "authuser", description: "uses central auth", risk: "read-only" });
+const depB = path.join(tmp, "authjoin.js");
+fs.writeFileSync(depB, '#!/usr/bin/env node\nconst lib = require(require("path").join(__dirname, "..", "_lib", "central-auth.js"));\n');
+tools.addTool(depB, { name: "authjoin", description: "joins via central auth", risk: "read-only" });
+const depC = path.join(tmp, "othertool.sh");
+fs.writeFileSync(depC, '#!/usr/bin/env bash\nsource "$(dirname "$0")/../_lib/central-auth-v2.js"\n');
+tools.addTool(depC, { name: "othertool", description: "uses the v2 lib", risk: "read-only" });
+const deps = tools.libDependents("central-auth.js");
+assert.ok(deps.includes("authuser"), "a literal _lib/<name> reference is a dependent");
+assert.ok(deps.includes("authjoin"), "a path.join'd _lib reference is a dependent");
+assert.ok(!deps.includes("othertool"), "central-auth-v2 is NOT a dependent of central-auth (boundary-safe)");
+assert.deepStrictEqual(tools.libDependents("unused-lib.js"), [], "a lib nothing imports has no dependents");
+
+// ── setLib: one commit, every dependent journaled "unverified since _lib change" ──
+const libRes = repo.setLib("central-auth.js", "module.exports = { login() { return { user: process.env.inet_central_user }; } };\n");
+assert.strictEqual(libRes.name, "central-auth.js", "setLib resolves the lib name");
+assert.ok(libRes.existed, "setLib reports an update over an existing lib");
+assert.deepStrictEqual(libRes.dependents.sort(), ["authjoin", "authuser"], "setLib names exactly the dependents");
+assert.ok(/unverified since _lib change \(central-auth\.js\)/.test(tools.readToolDoc("authuser")), "dependent journaled as unverified");
+assert.ok(/unverified since _lib change/.test(tools.readToolDoc("authjoin")), "second dependent journaled too");
+assert.ok(!/unverified since _lib change/.test(tools.readToolDoc("othertool")), "a non-dependent is left alone");
+
+// ── nested tool-calls-tool gate (Phase 4): approval is inherited from the
+//    outermost human-approved invocation; a composing tool cannot fabricate it ──
+assert.strictEqual(tools.approvedTierFromArgv([]), "read-only", "no flags → read-only approval");
+assert.strictEqual(tools.approvedTierFromArgv(["--yes"]), "write", "--yes → write approval");
+assert.strictEqual(tools.approvedTierFromArgv(["--yes", "--yes-destructive"]), "destructive", "--yes-destructive wins");
+const nestedEnv = (approved, stack) => ({ OPEN_CLAUDIA_APPROVED_TIER: approved, OPEN_CLAUDIA_TOOL_STACK: stack });
+assert.ok(tools.runGate({ name: "kticket", risk: "write" }, [], nestedEnv("write", "report")).ok,
+  "a write callee runs under an inherited write approval — no argv flag needed");
+assert.ok(tools.runGate({ name: "kticket", risk: "read-only" }, [], nestedEnv("read-only", "report")).ok,
+  "a read-only callee always runs nested");
+const fabricated = tools.runGate({ name: "wipe", risk: "destructive" }, ["--yes-destructive"], nestedEnv("write", "report"));
+assert.ok(!fabricated.ok, "a composing tool cannot self-approve destructive with its own hardcoded flag");
+assert.ok(/cannot self-approve/i.test(fabricated.message), "the refusal explains approval must come from the outer run");
+assert.ok(!tools.runGate({ name: "kticket", risk: "write" }, ["--yes"], nestedEnv("read-only", "report")).ok,
+  "an outer read-only approval does not unlock a nested write, argv flags ignored");
+assert.ok(tools.runGate({ name: "wipe", risk: "destructive" }, [], nestedEnv("destructive", "report")).ok,
+  "an outer --yes-destructive approval flows through to a destructive callee");
+assert.ok(tools.runGate({ name: "wipe", risk: "" }, [], nestedEnv("write", "report")).ok,
+  "an undeclared callee tier is treated as write — runs under an inherited write approval");
+assert.ok(!tools.runGate({ name: "wipe", risk: "" }, [], nestedEnv("read-only", "report")).ok,
+  "an undeclared callee tier is refused under a read-only approval (fail-safe when nested too)");
+const cycle = tools.runGate({ name: "report", risk: "read-only" }, [], nestedEnv("read-only", "weekly>report"));
+assert.ok(!cycle.ok && /cycle/i.test(cycle.message), "a tool already in the call chain is refused (cycle guard)");
+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");