@inetafrica/open-claudia 2.7.3 → 2.7.5

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## v2.7.3
+## 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.
 - **Surfaced tools now carry their condition (tiered surfacing, Phase 2/item 6).** The per-turn "Tools that may help here" block rendered one identity line per tool — name, description, keyring needs — so the agent knew a tool *existed* but not what state it was in, and had to spend a `tool show` (or just run it blind) to find out it was broken, never proven, or failing since Tuesday. Each surfaced tool is now a **2-line headline**: line 1 is identity (name — description, risk tier, keyring needs, why it surfaced), line 2 is condition — the TOOL.md **State** headline (first line, truncated), the open **known-issue count** (⚠ n), and **last-run health** from telemetry (`last run OK/FAILED (exit n) <date>, n runs`, or `never run`; legacy flat tools without exit telemetry degrade to `last used`). This completes the tiering ladder: 2-line headline always → TOOL.md via `tool show` → source only via `--source` — you read the manual, not the disassembly, and now the cover tells you if the manual has errata. New `tools.toolCondition()` with unit coverage in `test-tools.js` (headline extraction, `(none yet)` filtering, health formats, clean degrade) and end-to-end render assertions in `test-recall-discoverer.js`.
 
 ## v2.7.2

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/dream.js

@@ -1192,6 +1192,42 @@ async function runDream({ trigger = "manual" } = {}) {
       if (dupPairs.size) {
         bits.push(`👯 ${dupPairs.size} near-duplicate tool pair(s): ${[...dupPairs].join(", ")} — consider merging into one tool with subcommands.`);
       }
+      // Doc/code drift: source edited after TOOL.md, or verbs in real use that
+      // the docs never mention. Flag only — the fix is a tool note.
+      const drifted = allTools
+        .map((t) => { const d = toolsLib.docDrift(t); return d ? `${t.name} (${d})` : null; })
+        .filter(Boolean);
+      if (drifted.length) {
+        bits.push(`📝 ${drifted.length} tool(s) with doc/code drift: ${drifted.join("; ")} — refresh the docs with tool note.`);
+      }
+      // 5c usage KPI: what fraction of operational actions went through the
+      // authorised channel, computed from telemetry stamps (state.json run
+      // history) + the guard log — never prose parsing. Denominator counts
+      // COMPLETED actions: tool runs + logged escape-hatch bypasses + raw-op
+      // sightings; gate denies are reported separately (blocked ≠ completed).
+      try {
+        const guardLib = require("./tool-guard");
+        const sinceTs = dreamState.lastRun || new Date(Date.now() - 7 * 86400000).toISOString();
+        const g = guardLib.readGuardEvents(sinceTs);
+        const r = toolsLib.runsSince(sinceTs);
+        const ops = r.runs + g.bypasses.length + g.rawOps.length;
+        if (ops) {
+          const pct = Math.round((100 * r.runs) / ops);
+          const kpiBits = [`${pct}% of operational actions via tool run (${r.runs}/${ops}, target >90%)`];
+          if (g.bypasses.length) {
+            const reasons = g.bypasses.map((b) => b.reason).filter(Boolean).slice(0, 3).join("; ");
+            kpiBits.push(`${g.bypasses.length} escape-hatch bypass(es)${reasons ? ` — ${reasons}` : ""}`);
+          }
+          if (g.rawOps.length) {
+            const byPattern = {};
+            for (const evt of g.rawOps) byPattern[evt.pattern || "?"] = (byPattern[evt.pattern || "?"] || 0) + 1;
+            kpiBits.push(`${g.rawOps.length} raw op(s) outside tools: ${Object.entries(byPattern).map(([k, v]) => `${k} ×${v}`).join(", ")}`);
+          }
+          if (g.denies.length) kpiBits.push(`${g.denies.length} denied by the gate`);
+          if (r.failures) kpiBits.push(`${r.failures} failed run(s) at use: ${r.failedTools.join(", ")}`);
+          bits.push(`📈 Tool usage since last dream: ${kpiBits.join(" · ")}.`);
+        }
+      } catch (e) { /* KPI is best-effort */ }
       toolNote = bits.join("\n");
     } catch (e) { /* tool graph is best-effort (old node) */ }
 

package/core/runner.js

@@ -958,6 +958,11 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   const noteRecallFromShell = (command) => {
     try {
       const cmd = String(command || "");
+      // 5c raw-op audit: every Bash command in the stream passes here, so
+      // operational work done raw — heredoc scripts, DB clients, mutating
+      // kubectl — gets stamped to the guard log for the dream's KPI pass.
+      // Observation only; blocking is the deny-gate hook's job, not this.
+      try { require("./tool-guard").noteRawOp(cmd); } catch (e) { /* best-effort */ }
       if (!cmd.includes("open-claudia")) return;
       let m;
       const packRe = /\bpack\s+show\s+["']?([a-z0-9][\w.-]*)/gi;

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-guard.js

@@ -107,6 +107,76 @@ function logGuardEvent(evt) {
   } catch (e) { /* best effort */ }
 }
 
+// ── 5c raw-op audit (observation, never blocking) ──────────────────────────
+// The deny-gate above catches acting commands aimed at KNOWN prod surfaces;
+// this detector catches the SHAPE of operational work done raw that should
+// have been a tool — inline heredoc scripts fed to an interpreter, raw DB
+// clients, mutating kubectl. Same high-precision-over-recall doctrine as the
+// gate: reads and probes (kubectl get/logs, grep, ping) stay unflagged, so
+// the dream's KPI measures real operational bypassing, not diagnosis noise.
+const RAW_OP_PATTERNS = [
+  {
+    // An interpreter or DB shell fed an inline heredoc script — the exact
+    // "re-derive the script instead of reusing a tool" smell. cat/tee heredocs
+    // (file writes) deliberately don't match.
+    id: "heredoc-interpreter",
+    re: /(?:^|[|;&(`'"]|\$\()\s*(?:sudo\s+)?(?:node|python3?|ruby|perl|php|deno|bun|mongo|mongosh|psql|mysql|redis-cli)\b[^\n]*<</,
+  },
+  {
+    id: "db-client",
+    re: /(?:^|[|;&(`'"]|\$\()\s*(?:sudo\s+)?(?:mongo|mongosh|psql|mysql|redis-cli)\b/,
+  },
+  {
+    // Cluster mutations raw from the shell (GitOps or the prod-k8s tool are
+    // the channels). kubectl get/describe/logs/top/events/port-forward and
+    // rollout status/history are reads — always free per the hard rules.
+    id: "kubectl-mutate",
+    re: /\bkubectl\s+(?:exec|apply|delete|scale|patch|edit|create|replace|cordon|uncordon|drain|taint|label|annotate|set)\b|\bkubectl\s+rollout\s+(?:restart|undo|pause|resume)\b/,
+  },
+];
+
+// Pure: null, or the matched raw-op pattern. The authorised channels and
+// anything the deny-gate owns (already logged as a deny by the hook) are
+// skipped so one command never produces two guard events.
+function matchRawOp(command) {
+  const cmd = String(command || "");
+  if (!cmd.trim()) return null;
+  if (ALLOW_RE.test(cmd)) return null;
+  if (matchRule(cmd)) return null;
+  for (const p of RAW_OP_PATTERNS) if (p.re.test(cmd)) return p;
+  return null;
+}
+
+// Stamp a sighting to the guard log. Called from the runner's Bash-stream
+// chokepoint on every command; must never throw into the stream parser.
+function noteRawOp(command) {
+  try {
+    const p = matchRawOp(command);
+    if (!p) return null;
+    logGuardEvent({ kind: "raw-op", pattern: p.id, command: String(command).slice(0, 300) });
+    return p;
+  } catch (e) { return null; }
+}
+
+// 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: [] };
+  let raw = "";
+  try { raw = fs.readFileSync(GUARD_LOG, "utf-8"); } catch (e) { return out; }
+  const since = sinceTs ? Date.parse(sinceTs) : NaN;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let evt;
+    try { evt = JSON.parse(line); } catch (e) { continue; }
+    if (!Number.isNaN(since) && (!evt.ts || Date.parse(evt.ts) < since)) continue;
+    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);
+  }
+  return out;
+}
+
 // Hook entry, pure enough to test: takes the PreToolUse stdin payload (object
 // or JSON string), returns { exit, stderr }. exit 2 = deny (stderr is fed back
 // to the model); exit 0 = allow. Anything unexpected → allow (fail-open).
@@ -160,4 +230,8 @@ function ensureHookSettings() {
   return SETTINGS_FILE;
 }
 
-module.exports = { RULES, GUARD_LOG, SETTINGS_FILE, matchRule, denyMessage, logGuardEvent, runHook, hookSettings, ensureHookSettings };
+module.exports = {
+  RULES, RAW_OP_PATTERNS, GUARD_LOG, SETTINGS_FILE,
+  matchRule, denyMessage, logGuardEvent, runHook, hookSettings, ensureHookSettings,
+  matchRawOp, noteRawOp, readGuardEvents,
+};

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,6 +264,7 @@ 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;
@@ -293,6 +294,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 +358,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; }
@@ -375,14 +377,113 @@ function findTool(name) {
   return readTool(needle);
 }
 
+// Window telemetry for the 5c usage KPI: `tool run` executions since a
+// timestamp, counted from state.json history entries — the CLI's authoritative
+// per-run stamps, never prose parsing. History is capped per tool, so a tool
+// that ran more than HISTORY_CAP times in the window undercounts slightly;
+// acceptable for a nightly ratio.
+function runsSince(sinceTs) {
+  const since = sinceTs ? Date.parse(sinceTs) : NaN;
+  const out = { runs: 0, failures: 0, byTool: {}, failedTools: [] };
+  for (const t of listTools()) {
+    const hist = Array.isArray(t.history) ? t.history : [];
+    const inWindow = hist.filter((h) => h && h.at && (Number.isNaN(since) || Date.parse(h.at) >= since));
+    if (!inWindow.length) continue;
+    const fails = inWindow.filter((h) => h.exit !== 0).length;
+    out.runs += inWindow.length;
+    out.failures += fails;
+    out.byTool[t.name] = { runs: inWindow.length, failures: fails };
+    if (fails) out.failedTools.push(`${t.name} ×${fails}`);
+  }
+  return out;
+}
+
+// Doc/code drift check for the dream's tool pass: the source was edited after
+// TOOL.md was last touched (docs describe an older tool), or a verb telemetry
+// proves is in real use never appears in the docs. Returns a short reason or
+// null. The 60s slack absorbs creation-time write ordering (source + doc
+// skeleton land moments apart).
+function docDrift(t) {
+  if (!t || t.layout !== "dir" || !t.docFile) return null;
+  try {
+    if (fs.statSync(t.file).mtimeMs > fs.statSync(t.docFile).mtimeMs + 60000) return "source newer than TOOL.md";
+  } catch (e) { /* doc or source unreadable → fall through to verb check */ }
+  const doc = readToolDoc(t.name) || "";
+  const verbs = Object.keys(t.verbs || {}).filter((v) => v && v !== "(default)" && v !== "help" && !v.startsWith("-"));
+  const undocd = verbs.filter((v) => !doc.includes(v)).slice(0, 3);
+  if (undocd.length) return `verb${undocd.length === 1 ? "" : "s"} ${undocd.join(", ")} used but undocumented`;
+  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");
 }
@@ -511,6 +612,7 @@ function addTool(srcPath, opts = {}) {
       pack: opts.pack || "",
       risk,
       requires: opts.requires || [],
+      tags: opts.tags || [],
       usage: opts.usage || "",
     });
     const hasShebang = content.startsWith("#!");
@@ -527,6 +629,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;
@@ -597,6 +700,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;
@@ -622,6 +728,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;
@@ -642,9 +749,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") {
@@ -711,10 +847,11 @@ function toolNameFromPath(filePath) {
 }
 
 module.exports = {
-  TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS,
-  parseHeader, readTool, readToolDoc, toolCondition, listTools, findTool, addTool, removeTool, updateToolHeader,
+  TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS, LIB_DIR,
+  parseHeader, readTool, readToolDoc, toolCondition, 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.3",
+  "version": "2.7.5",
   "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-tool-guard.js

@@ -68,6 +68,43 @@ assert.ok(lines.some((l) => l.kind === "deny" && l.rule === "inet-central-api"),
 assert.ok(lines.some((l) => l.kind === "bypass" && l.reason === "no tool yet"), "keyring exec bypass is logged");
 assert.ok(lines.every((l) => l.ts), "every guard event is timestamped");
 
+// ── raw-op audit (5c): operational work done raw is observed, never blocked ──
+assert.strictEqual(guard.matchRawOp("node <<'EOF'\nfetch('https://api.example.com/x')\nEOF").id, "heredoc-interpreter",
+  "inline node heredoc is the canonical re-derived-script smell");
+assert.strictEqual(guard.matchRawOp("python3 <<PY\nprint(1)\nPY").id, "heredoc-interpreter");
+assert.strictEqual(guard.matchRawOp('echo start && mongosh <<JS\ndb.x.find()\nJS').id, "heredoc-interpreter",
+  "heredoc after && still detected");
+assert.strictEqual(guard.matchRawOp('mongosh "mongodb://db.internal/app" --eval "db.users.count()"').id, "db-client");
+assert.strictEqual(guard.matchRawOp("psql -h db.internal -c 'select 1'").id, "db-client");
+assert.strictEqual(guard.matchRawOp("kubectl delete pod api-0 -n prod").id, "kubectl-mutate");
+assert.strictEqual(guard.matchRawOp("kubectl apply -f deploy.yaml").id, "kubectl-mutate");
+assert.strictEqual(guard.matchRawOp("kubectl rollout restart deploy/api").id, "kubectl-mutate");
+assert.strictEqual(guard.matchRawOp("kubectl exec api-0 -- cat /etc/config").id, "kubectl-mutate",
+  "raw kubectl exec is an op vector even for reads inside the pod");
+assert.strictEqual(guard.matchRawOp("cat <<'EOF' > notes.md\nhello\nEOF"), null, "heredoc into a file write is not an op");
+assert.strictEqual(guard.matchRawOp("kubectl get pods -A"), null, "read-only kubectl stays unflagged");
+assert.strictEqual(guard.matchRawOp("kubectl rollout status deploy/api"), null, "rollout status is a read");
+assert.strictEqual(guard.matchRawOp("kubectl logs api-7f9 -n prod"), null, "kubectl logs is a read");
+assert.strictEqual(guard.matchRawOp("node script.js"), null, "running a checked-in script is not the heredoc smell");
+assert.strictEqual(guard.matchRawOp("grep -rn mongosh docs/"), null, "mentioning a client binary mid-line is not acting");
+assert.strictEqual(guard.matchRawOp("open-claudia tool run prod-k8s exec api-0 'cat /etc/config'"), null,
+  "authorised channel never flagged");
+assert.strictEqual(guard.matchRawOp('open-claudia keyring exec --reason "x" -- mongosh mongodb://db/x'), null,
+  "escape hatch logs its own bypass, not a raw-op");
+assert.strictEqual(guard.matchRawOp("kubectl exec mongo-0 -- mongosh"), null,
+  "deny-rule matches belong to the gate — one command never yields two guard events");
+assert.strictEqual(guard.noteRawOp("kubectl delete pod api-1 -n prod").id, "kubectl-mutate", "noteRawOp returns the pattern");
+assert.strictEqual(guard.noteRawOp("ls -la"), null, "benign commands log nothing");
+
+// ── readGuardEvents: since-filtered grouping (the KPI's data source) ──
+const evts = guard.readGuardEvents("2000-01-01T00:00:00Z");
+assert.ok(evts.denies.length >= 1, "denies grouped");
+assert.ok(evts.bypasses.length >= 1, "bypasses grouped");
+assert.ok(evts.rawOps.some((e) => e.pattern === "kubectl-mutate"), "raw-ops grouped with their pattern");
+assert.strictEqual(guard.readGuardEvents(new Date(Date.now() + 86400000).toISOString()).rawOps.length, 0,
+  "future since → empty window");
+assert.ok(guard.readGuardEvents(null).denies.length >= 1, "null since → whole log");
+
 // ── hook settings: a valid claude --settings payload, idempotent writer ──
 const sPath = guard.ensureHookSettings();
 assert.strictEqual(sPath, process.env.DENY_GATE_SETTINGS, "settings path is env-overridable (test isolation)");

package/test-tools.js

@@ -334,6 +334,110 @@ tools.writeState("condtool", { createdAt: "2026-07-01T00:00:00Z", lastUsed: "202
 assert.ok(/last run OK 2026-07-03, 4 runs/.test(tools.toolCondition(tools.findTool("condtool"))), "healthy last run reads OK");
 assert.strictEqual(tools.toolCondition(null), "", "no tool → empty digest");
 
+// ── runsSince: windowed run counts from state.json history (5c KPI source) ──
+tools.writeState("condtool", {
+  createdAt: "2026-07-01T00:00:00Z", lastUsed: "2099-01-02T00:00:00Z", runCount: 7, lastExit: 1,
+  history: [
+    { at: "2099-01-02T00:00:00Z", args: "list --json", exit: 1, ms: 40 },
+    { at: "2099-01-01T00:00:00Z", args: "list", exit: 0, ms: 35 },
+    { at: "2000-01-01T00:00:00Z", args: "list", exit: 0, ms: 30 },
+  ],
+});
+const win = tools.runsSince("2098-12-31T00:00:00Z");
+assert.strictEqual(win.byTool.condtool.runs, 2, "only history entries inside the window count");
+assert.strictEqual(win.byTool.condtool.failures, 1, "non-zero exits count as failures at use");
+assert.ok(win.failedTools.includes("condtool ×1"), "failing tools are named for the dream report");
+assert.strictEqual(tools.runsSince("2099-06-01T00:00:00Z").runs, 0, "empty window → zero runs");
+
+// ── docDrift: docs stale vs source/telemetry (dream tool-pass flag) ──
+assert.strictEqual(tools.docDrift(tools.findTool("condtool")), null, "fresh docs → no drift");
+tools.writeState("condtool", {
+  createdAt: "2026-07-01T00:00:00Z", lastUsed: "2099-01-02T00:00:00Z", runCount: 7, lastExit: 0,
+  verbs: { list: { runs: 3 }, stages: { runs: 1 }, help: { runs: 1 }, "(default)": { runs: 1 } },
+});
+assert.strictEqual(tools.docDrift(tools.findTool("condtool")), "verb stages used but undocumented",
+  "a verb in real use that TOOL.md never mentions is drift (help/(default) ignored)");
+const future = new Date(Date.now() + 3600000);
+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");
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");