@inetafrica/open-claudia 2.6.58 → 2.7.0

package/core/tools.js

@@ -1,18 +1,29 @@
-// Reusable tools: executable scripts the agent crystallises as it works, so a
-// procedure it figured out once (hit an API, drive an interface, transform a
-// file) becomes a re-runnable command next time instead of a throwaway heredoc.
+// Reusable tools: the interface operational work happens THROUGH — not
+// souvenirs saved after the fact. The agent searches for a tool first, extends
+// a missing verb, or scaffolds; scripts are for probing unknown APIs only.
 //
-// This is the executable sibling of context packs. A pack's Procedure section
-// documents *how* in prose; a tool *is* the how — a real file you run. Tools
-// are surfaced in the system prompt as an always-on index (like skill packs)
-// and read on demand via `open-claudia tool show <name>` (progressive
-// disclosure). Each tool can name an owning skill pack so the two stay linked.
+// A tool is a memory object, not a file — a directory:
+//   tools/<name>/tool        executable (any language, shebang)
+//   tools/<name>/TOOL.md     Interface · Known issues · State · Journal (prose)
+//   tools/<name>/state.json  machine telemetry, stamped by the runtime only
+// The tools dir is git-initialised (core/tool-repo.js); every add/change
+// commits, so git log is the upgrade history. Pre-2.7 flat-file tools are
+// still readable and are migrated to directories on first CLI use.
+//
+// This is the executable sibling of context packs: packs hold judgment
+// (when/why/what needs approval), tools hold mechanics (how). Tools surface in
+// the system prompt as an always-on index and are read on demand via
+// `open-claudia tool show <name>` (progressive disclosure).
 //
 // Preauth: tools run with the operational keyring merged into their env (see
-// runEnv()), exactly like the agent's own subprocess. So a tool references a
-// credential as $inet_central_user and never hardcodes a secret. The keyring is
-// already a managed .env (plaintext + chmod 600 + log redaction); tools inherit
-// that model rather than inventing a second one.
+// runEnv()). A tool references a credential as $inet_central_user and never
+// hardcodes a secret — addTool/updateToolHeader REFUSE sources that match
+// secret patterns, because the auto-commit history is forever.
+//
+// Risk tiers mechanise the ask-first rule: every tool declares read-only /
+// write / destructive. runGate() refuses write-tier runs without --yes and
+// destructive-tier runs without --yes-destructive; approval itself always
+// comes from the user — the flag is the agent's deliberate confirmation step.
 
 const fs = require("fs");
 const path = require("path");
@@ -24,7 +35,20 @@ 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"];
+const HEADER_KEYS = ["description", "pack", "requires", "usage", "risk"];
+const RISK_TIERS = ["read-only", "write", "destructive"];
+
+// Normalise a risk value to one of RISK_TIERS ("" when unrecognised). Blast
+// radius on LIVE systems is what counts: writing a local output file is still
+// read-only; mutating an API/DB/cluster is write; deleting or irreversible is
+// destructive.
+function normalizeRisk(val) {
+  const v = String(val || "").toLowerCase().trim().replace(/[_\s]+/g, "-");
+  if (["read-only", "readonly", "read", "ro"].includes(v)) return "read-only";
+  if (["write", "w", "mutating"].includes(v)) return "write";
+  if (["destructive", "dangerous"].includes(v)) return "destructive";
+  return "";
+}
 
 function ensureDir() {
   fs.mkdirSync(TOOLS_DIR, { recursive: true, mode: 0o700 });
@@ -35,12 +59,28 @@ function sanitizeName(name) {
     .replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 60);
 }
 
+// ── Layout resolution ────────────────────────────────────────────────────────
+// Directory layout (2.7+) vs legacy flat file. A name resolves to the directory
+// shape when tools/<name>/tool exists; otherwise to the flat file if present;
+// otherwise (for creation) to the directory shape.
+function toolPaths(name) {
+  const n = sanitizeName(name);
+  const dir = path.join(TOOLS_DIR, n);
+  const exec = path.join(dir, "tool");
+  const isDir = (() => { try { return fs.statSync(exec).isFile(); } catch (e) { return false; } })();
+  if (isDir) return { name: n, layout: "dir", dir, exec, doc: path.join(dir, "TOOL.md"), state: path.join(dir, "state.json") };
+  const isFile = (() => { try { return fs.statSync(dir).isFile(); } catch (e) { return false; } })();
+  if (isFile) return { name: n, layout: "file", dir: TOOLS_DIR, exec: dir, doc: null, state: null };
+  return { name: n, layout: "new", dir, exec, doc: path.join(dir, "TOOL.md"), state: path.join(dir, "state.json") };
+}
+
 // ── Run telemetry ────────────────────────────────────────────────────────────
-// A tiny JSON sidecar (name -> { runCount, lastUsed }) kept beside the tools.
-// Deliberately NOT a SQLite graph: telemetry must work on the node:20 pods where
-// node:sqlite is absent, and it's a flat counter, not a graph. Dotfile so
-// listTools (which skips ".") never mistakes it for a tool.
+// Directory tools: per-tool state.json, written ONLY by the runtime (never
+// hand-edited, never committed — gitignored; TOOL.md's State section is the
+// curated prose view). Plain JSON, not SQLite: must work on node:20 pods.
+// Legacy flat tools keep the old .usage.json sidecar until migrated.
 const USAGE_FILE = path.join(TOOLS_DIR, ".usage.json");
+const HISTORY_CAP = 20;
 
 function readUsage() {
   try { return JSON.parse(fs.readFileSync(USAGE_FILE, "utf-8")) || {}; }
@@ -52,12 +92,58 @@ function writeUsage(u) {
   catch (e) { /* best-effort */ }
 }
 
-// Bump a tool's run counter. Called at end of turn from the runner when it parses
-// an `open-claudia tool run <name>` out of the shell. Feeds matchTools' tiebreak
-// (popular tools rank up) and the dream's zero-run hygiene flag.
+function readState(name) {
+  const p = toolPaths(name);
+  if (!p.state) return {};
+  try { return JSON.parse(fs.readFileSync(p.state, "utf-8")) || {}; }
+  catch (e) { return {}; }
+}
+
+function writeState(name, s) {
+  const p = toolPaths(name);
+  const file = p.state || path.join(TOOLS_DIR, sanitizeName(name), "state.json");
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(s, null, 1), { mode: 0o600 });
+  } catch (e) { /* best-effort */ }
+}
+
+// Authoritative telemetry stamp — called by `tool run` itself with the real
+// outcome (exit code, duration, argv). Tracks per-verb health (verb = first
+// non-flag arg) so TOOL.md can report "assign: last real run <date>" honestly,
+// plus a capped run history. A non-zero exit is the trigger for a known-issue
+// entry in TOOL.md (the CLI nudges; the foreground agent writes it).
+function recordRunResult(name, { args = [], exit = 0, ms = 0 } = {}) {
+  const n = sanitizeName(name);
+  if (!n) return;
+  if (toolPaths(n).layout !== "dir") { recordRun(n); return; } // legacy fallback
+  const now = new Date().toISOString();
+  const s = readState(n);
+  if (!s.createdAt) s.createdAt = now;
+  s.lastUsed = now;
+  s.runCount = (s.runCount || 0) + 1;
+  s.lastExit = exit;
+  if (exit === 0) s.lastSuccess = now; else s.lastFailure = now;
+  const verb = (args.find((a) => a && !String(a).startsWith("-")) || "(default)").slice(0, 40);
+  s.verbs = s.verbs || {};
+  const v = s.verbs[verb] || { runs: 0 };
+  v.runs += 1;
+  v.lastExit = exit;
+  if (exit === 0) v.lastSuccess = now; else v.lastFailure = now;
+  s.verbs[verb] = v;
+  const argLine = args.join(" ").slice(0, 120);
+  s.history = [{ at: now, args: argLine, exit, ms }, ...(s.history || [])].slice(0, HISTORY_CAP);
+  writeState(n, s);
+}
+
+// Bump a tool's run counter without outcome detail. Still called at end of turn
+// from the runner's transcript parse; for directory tools that's a no-op (the
+// CLI already stamped the authoritative result — double-counting would lie),
+// so this only feeds the legacy sidecar for unmigrated flat tools.
 function recordRun(name) {
   const n = sanitizeName(name);
   if (!n) return;
+  if (toolPaths(n).layout === "dir") return; // CLI stamps state.json directly
   const u = readUsage();
   const cur = u[n] || { runCount: 0, lastUsed: "" };
   cur.runCount = (cur.runCount || 0) + 1;
@@ -66,13 +152,18 @@ function recordRun(name) {
   writeUsage(u);
 }
 
-// Stamp an immutable createdAt the first time a tool is registered. Kept in the
-// sidecar (not the header) so editing the file never disturbs it — unlike file
-// mtime, which resets on every edit and would make an edited-but-never-run tool
-// look freshly minted. The dream's zero-run hygiene ages tools from this.
+// Stamp an immutable createdAt the first time a tool is registered. Kept in
+// telemetry (not the header) so editing the file never disturbs it — unlike
+// file mtime, which resets on every edit and would make an edited-but-never-run
+// tool look freshly minted. The dream's zero-run hygiene ages tools from this.
 function recordCreate(name) {
   const n = sanitizeName(name);
   if (!n) return;
+  if (toolPaths(n).layout === "dir") {
+    const s = readState(n);
+    if (!s.createdAt) { s.createdAt = new Date().toISOString(); writeState(n, s); }
+    return;
+  }
   const u = readUsage();
   const cur = u[n] || { runCount: 0, lastUsed: "" };
   if (!cur.createdAt) cur.createdAt = new Date().toISOString();
@@ -152,7 +243,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: "" };
+  const out = { name: "", description: "", pack: "", requires: [], usage: "", risk: "" };
   const lines = String(content || "").split("\n");
   let started = false;
   for (let i = 0; i < lines.length; i++) {
@@ -171,40 +262,59 @@ function parseHeader(content) {
     const val = kv[2].trim();
     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 (HEADER_KEYS.includes(key)) out[key] = val;
   }
   return out.name ? out : null;
 }
 
+// Path of a tool's executable (legacy signature kept: several callers treat
+// "the tool file" as the thing you run/edit).
 function toolFile(name) {
-  return path.join(TOOLS_DIR, sanitizeName(name));
+  return toolPaths(name).exec;
 }
 
 function readTool(name, usageMap) {
-  const file = toolFile(name);
+  const p = toolPaths(name);
   let content;
-  try { content = fs.readFileSync(file, "utf-8"); } catch (e) { return null; }
+  try { content = fs.readFileSync(p.exec, "utf-8"); } catch (e) { return null; }
   const header = parseHeader(content);
   if (!header) return null;
   let stat = null;
-  try { stat = fs.statSync(file); } catch (e) {}
-  const usage = (usageMap || readUsage())[header.name || sanitizeName(name)] || {};
+  try { stat = fs.statSync(p.exec); } catch (e) {}
+  const telemetry = p.layout === "dir"
+    ? readState(header.name || p.name)
+    : (usageMap || readUsage())[header.name || p.name] || {};
   return {
-    name: header.name || sanitizeName(name),
+    name: header.name || p.name,
     description: header.description || "",
     pack: header.pack || "",
     requires: header.requires || [],
     usage: header.usage || "",
-    file,
+    risk: header.risk || "",
+    layout: p.layout,
+    file: p.exec,
+    docFile: p.doc,
     executable: stat ? !!(stat.mode & 0o111) : false,
     updatedAt: stat ? stat.mtime.toISOString() : "",
-    createdAt: usage.createdAt || "",
-    runCount: usage.runCount || 0,
-    lastUsed: usage.lastUsed || "",
+    createdAt: telemetry.createdAt || "",
+    runCount: telemetry.runCount || 0,
+    lastUsed: telemetry.lastUsed || "",
+    lastExit: telemetry.lastExit,
+    verbs: telemetry.verbs || null,
+    history: telemetry.history || null,
     content,
   };
 }
 
+// A tool's TOOL.md prose (Interface · Known issues · State · Journal), "" when
+// absent — loaded on demand (tool show), never in the always-on index.
+function readToolDoc(name) {
+  const p = toolPaths(name);
+  if (!p.doc) return "";
+  try { return fs.readFileSync(p.doc, "utf-8"); } catch (e) { return ""; }
+}
+
 function listTools() {
   let entries;
   try { entries = fs.readdirSync(TOOLS_DIR); } catch (e) { return []; }
@@ -212,8 +322,11 @@ function listTools() {
   const tools = [];
   for (const name of entries) {
     if (name.startsWith(".")) continue;
-    try { if (!fs.statSync(path.join(TOOLS_DIR, name)).isFile()) continue; }
-    catch (e) { continue; }
+    const full = path.join(TOOLS_DIR, name);
+    let st;
+    try { st = fs.statSync(full); } catch (e) { continue; }
+    if (st.isDirectory() && !fs.existsSync(path.join(full, "tool"))) continue; // junk dir, not a tool
+    if (!st.isDirectory() && !st.isFile()) continue;
     const t = readTool(name, usage);
     if (t) tools.push(t);
   }
@@ -229,10 +342,11 @@ function findTool(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 }) {
+function buildHeader(prefix, { name, description, pack, requires, usage, risk }) {
   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(", ")}`);
   if (usage) lines.push(`${prefix} usage: ${usage}`);
   return lines.join("\n");
@@ -320,26 +434,47 @@ function checkSyntax(file, content) {
   } catch (e) { return null; }
 }
 
-// Register a script as a tool. Copies it into TOOLS_DIR under a sanitized name,
-// ensures it carries a header (synthesising one from opts if absent), and makes
-// it executable. Returns the stored tool.
+// Refuse content carrying a hardcoded credential. The tools repo auto-commits,
+// and git history is forever — so unlike the advisory lints, secrets BLOCK.
+function assertNoSecrets(content, what) {
+  const hits = [];
+  for (const [re, label] of SECRET_PATTERNS) if (re.test(String(content || ""))) hits.push(label);
+  if (hits.length) {
+    throw new Error(`${what || "content"} contains hardcoded secret(s): ${hits.join(", ")}. ` +
+      "Reference credentials as $KEYRING_VAR (declare via --requires) — refusing to save into the git-tracked tools repo.");
+  }
+}
+
+// Register a script as a tool. New tools land in the directory layout (tool +
+// TOOL.md + state.json); re-adding over a legacy flat file upgrades it. The
+// source must carry a header (synthesised from opts if absent), gets a
+// fail-safe `risk: write` tier when none is declared, is refused if it embeds
+// a secret, and the save is git-committed. Returns the stored tool.
 function addTool(srcPath, opts = {}) {
   ensureDir();
   let content;
   try { content = fs.readFileSync(srcPath, "utf-8"); }
   catch (e) { throw new Error(`cannot read ${srcPath}: ${e.message}`); }
 
+  assertNoSecrets(content, path.basename(srcPath));
+
   let header = parseHeader(content);
   const name = sanitizeName(opts.name || (header && header.name) || path.basename(srcPath).replace(/\.[^.]+$/, ""));
   if (!name) throw new Error("tool needs a name (pass --name or add an 'open-claudia-tool:' header line)");
 
+  const optRisk = normalizeRisk(opts.risk);
+  let defaultedRisk = false;
+
   if (!header) {
     // No header in the source — synthesise one so the tool is self-documenting.
     const prefix = commentPrefixFor(content, srcPath);
+    let risk = optRisk;
+    if (!risk) { risk = "write"; defaultedRisk = true; } // fail-safe: ungated only when declared read-only
     const block = buildHeader(prefix, {
       name,
       description: opts.description || "",
       pack: opts.pack || "",
+      risk,
       requires: opts.requires || [],
       usage: opts.usage || "",
     });
@@ -351,26 +486,59 @@ function addTool(srcPath, opts = {}) {
       content = block + "\n" + content;
     }
     header = parseHeader(content);
-  } else if (opts.pack && !header.pack) {
-    // Source had a header but no pack link and the caller supplied one — add it.
+  } else {
     const prefix = commentPrefixFor(content, srcPath);
-    content = content.replace(
-      new RegExp(`((#|//)\\s*${MARKER}:.*\\n)`),
-      `$1${prefix} pack: ${opts.pack}\n`
-    );
+    const injectAfterMarker = (line) => {
+      content = content.replace(new RegExp(`((#|//)\\s*${MARKER}:.*\\n)`), `$1${line}\n`);
+    };
+    if (opts.pack && !header.pack) injectAfterMarker(`${prefix} pack: ${opts.pack}`);
+    if (!header.risk) {
+      const risk = optRisk || "write";
+      if (!optRisk) defaultedRisk = true;
+      injectAfterMarker(`${prefix} risk: ${risk}`);
+    }
+    header = parseHeader(content);
   }
 
-  const dest = toolFile(name);
-  fs.writeFileSync(dest, content, { mode: 0o700 });
-  try { fs.chmodSync(dest, 0o700); } catch (e) {}
+  // Upgrade a legacy flat file in place: the new content replaces it in the
+  // directory layout, carrying the old sidecar telemetry across.
+  const pre = toolPaths(name);
+  if (pre.layout === "file") {
+    const u = readUsage();
+    const old = u[name] || {};
+    try { fs.rmSync(pre.exec, { force: true }); } catch (e) {}
+    delete u[name];
+    writeUsage(u);
+    fs.mkdirSync(path.join(TOOLS_DIR, name), { recursive: true, mode: 0o700 });
+    writeState(name, { createdAt: old.createdAt || new Date().toISOString(), lastUsed: old.lastUsed || "", runCount: old.runCount || 0 });
+  }
+
+  const p = toolPaths(name);
+  fs.mkdirSync(path.dirname(p.exec), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(p.exec, content, { mode: 0o700 });
+  try { fs.chmodSync(p.exec, 0o700); } catch (e) {}
+  if (p.doc && !fs.existsSync(p.doc)) {
+    try {
+      const repo = require("./tool-repo");
+      fs.writeFileSync(p.doc, repo.toolMdSkeleton({ ...header, journalLine: "Registered via tool add." }), { mode: 0o600 });
+    } catch (e) { /* skeleton optional */ }
+  }
   recordCreate(name);
-  return readTool(name);
+  try { require("./tool-repo").commitTool(name, `${pre.layout === "new" ? "add" : "update"} ${name}`); } catch (e) {}
+  const stored = readTool(name);
+  if (stored) stored.defaultedRisk = defaultedRisk;
+  return stored;
 }
 
 function removeTool(name) {
   const tool = findTool(name);
   if (!tool) return null;
-  try { fs.rmSync(tool.file, { force: true }); } catch (e) { return null; }
+  const p = toolPaths(name);
+  try {
+    if (p.layout === "dir") fs.rmSync(path.join(TOOLS_DIR, p.name), { recursive: true, force: true });
+    else fs.rmSync(p.exec, { force: true });
+  } catch (e) { return null; }
+  try { require("./tool-repo").commitTool(p.name, `remove ${p.name}`); } catch (e) {}
   return tool;
 }
 
@@ -387,6 +555,11 @@ function updateToolHeader(name, opts = {}) {
   const description = opts.description !== undefined ? opts.description : t.description;
   const pack = opts.pack !== undefined ? opts.pack : t.pack;
   const usage = opts.usage !== undefined ? opts.usage : t.usage;
+  let risk = t.risk;
+  if (opts.risk !== undefined) {
+    risk = normalizeRisk(opts.risk);
+    if (!risk) throw new Error(`invalid risk tier "${opts.risk}" — use one of: ${RISK_TIERS.join(", ")}`);
+  }
   let requires = opts.requires !== undefined ? opts.requires : t.requires;
   if (!Array.isArray(requires)) requires = String(requires || "").split(/[,\s]+/).filter(Boolean);
 
@@ -412,6 +585,7 @@ function updateToolHeader(name, opts = {}) {
   const fieldLines = [];
   if (description) fieldLines.push(`${prefix} description: ${description}`);
   if (pack) fieldLines.push(`${prefix} pack: ${pack}`);
+  if (risk) fieldLines.push(`${prefix} risk: ${risk}`);
   if (requires.length) fieldLines.push(`${prefix} requires: ${requires.join(", ")}`);
   if (usage) fieldLines.push(`${prefix} usage: ${usage}`);
 
@@ -420,11 +594,40 @@ function updateToolHeader(name, opts = {}) {
   else newBlock = [`${prefix} ${MARKER}: ${t.name}`, ...fieldLines, ...kept];
 
   const next = [...lines.slice(0, headStart), ...newBlock, ...lines.slice(blockEnd)].join("\n");
+  assertNoSecrets(next, `tool ${t.name}`);
   fs.writeFileSync(t.file, next, { mode: 0o700 });
   try { fs.chmodSync(t.file, 0o700); } catch (e) {}
+  try { require("./tool-repo").commitTool(t.name, `set ${t.name} metadata`); } catch (e) {}
   return readTool(t.name);
 }
 
+// ── Risk-tier run gate ───────────────────────────────────────────────────────
+// Mechanises ask-first: read-only runs freely; write-tier requires --yes;
+// destructive-tier requires --yes-destructive (a plain --yes habit must not
+// 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 = []) {
+  const declared = normalizeRisk(tool && tool.risk);
+  const tier = declared || "write";
+  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") {
+    if (argv.includes("--yes-destructive")) return { ok: true, tier };
+    return {
+      ok: false, tier,
+      message: `⛔ DESTRUCTIVE tool "${tool.name}" — this can delete or irreversibly change live state.\n` +
+        `Warn the user what exactly will happen and get explicit approval, then re-run with --yes-destructive.`,
+    };
+  }
+  if (argv.includes("--yes")) return { ok: true, tier };
+  return {
+    ok: false, tier,
+    message: `⛔ "${tool.name}" is write-tier${note} — it changes live system state.\n` +
+      `Confirm the action with the user first, then re-run with --yes.`,
+  };
+}
+
 // Env for running a tool: the bot's standard subprocess env (PATH + keyring
 // creds merged) so tools are pre-authed the same way the agent is. Falls back to
 // a plain keyring merge if config isn't importable (e.g. standalone test).
@@ -448,20 +651,26 @@ function missingRequires(tool) {
   return tool.requires.filter((k) => !present.has(k) && process.env[k] === undefined);
 }
 
-// Recognise a Write/Edit aimed at a tool file (for chat announcements).
+// Recognise a Write/Edit aimed at a tool (for chat announcements). Legacy flat
+// file (tools/<name>) or the directory layout's agent-editable members
+// (tools/<name>/tool, tools/<name>/TOOL.md). state.json is machine telemetry —
+// hand edits to it are not a tool change, so it maps to null.
 function toolNameFromPath(filePath) {
   if (!filePath) return null;
   const resolved = path.resolve(String(filePath));
   const rel = path.relative(TOOLS_DIR, resolved);
   if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
-  if (rel.split(path.sep).length !== 1) return null;
-  return rel;
+  const parts = rel.split(path.sep);
+  if (parts.length === 1) return parts[0] || null;
+  if (parts.length === 2 && (parts[1] === "tool" || parts[1] === "TOOL.md")) return parts[0];
+  return null;
 }
 
 module.exports = {
-  TOOLS_DIR, MARKER, USAGE_FILE,
-  parseHeader, readTool, listTools, findTool, addTool, removeTool, updateToolHeader,
-  runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir,
+  TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS,
+  parseHeader, readTool, readToolDoc, listTools, findTool, addTool, removeTool, updateToolHeader,
+  runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir, normalizeRisk,
+  toolPaths, readState, writeState, recordRunResult, runGate,
   matchTools, recordRun, recordCreate, readUsage,
-  lintToolSource, checkSyntax, envRefsIn,
+  lintToolSource, checkSyntax, envRefsIn, assertNoSecrets,
 };

package/core/transcript-index.js

@@ -145,6 +145,26 @@ function rebuild(transcriptsDir = defaultTranscriptsDir()) {
   return indexAll(transcriptsDir);
 }
 
+// Nightly upkeep: catch up new appends, then drop index rows for transcript
+// files that no longer exist on disk — dead sessions stop matching and the
+// FTS table stays proportional to what is actually recallable.
+function tend(transcriptsDir = defaultTranscriptsDir()) {
+  const db = open(transcriptsDir);
+  if (!db) return { available: false, added: 0, prunedFiles: 0 };
+  const { added } = indexAll(transcriptsDir);
+  let prunedFiles = 0;
+  try {
+    const rows = db.prepare("SELECT path FROM files").all();
+    for (const r of rows) {
+      if (fs.existsSync(r.path)) continue;
+      db.prepare("DELETE FROM entries WHERE file = ?").run(r.path);
+      db.prepare("DELETE FROM files WHERE path = ?").run(r.path);
+      prunedFiles++;
+    }
+  } catch (e) {}
+  return { available: true, added, prunedFiles };
+}
+
 // FTS5 MATCH chokes on unbalanced quotes/operators in natural queries, so
 // by default each term is quoted (implicit AND). Pass raw=true for full
 // FTS5 query syntax (NEAR, OR, prefix*).
@@ -184,4 +204,4 @@ function stats(transcriptsDir = defaultTranscriptsDir()) {
   }
 }
 
-module.exports = { available, open, indexFile, indexAll, rebuild, search, stats, sanitizeQuery, defaultTranscriptsDir };
+module.exports = { available, open, indexFile, indexAll, rebuild, tend, search, stats, sanitizeQuery, defaultTranscriptsDir };

package/package.json

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

package/test-recall-discoverer.js

@@ -1,6 +1,9 @@
 // Discoverer engine: pre-gate, seed → (graph) → fail-open injection. The LLM
 // walker is disabled here (RECALL_DISCOVERER_WALKER=off) so the engine takes
-// its deterministic fail-open path: keep user-origin seeds, drop guesses.
+// its deterministic fail-open path. Contract: the seeds tier keeps ALL
+// user-origin keyword seeds (packs, entities, tools); the full tier without a
+// judge keeps only the top-3 user-origin pack/entity seeds — an unjudged tool
+// or episode is a guess, not a memory.
 const assert = require("assert");
 const fs = require("fs");
 const os = require("os");
@@ -101,16 +104,28 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   });
   assert.strictEqual(typeof out2.packBlock, "string");
 
-  // tool seeding: a tool matching the user text surfaces as a kept tool match and
-  // renders into toolBlock; a turn that matches no tool yields an empty toolBlock
+  // tool seeding (seeds tier): a ≤4-word command matching a tool keeps it as a
+  // user-origin seed and renders the toolBlock; no tool match → empty toolBlock
   const outTool = await disc.run({
-    userText: "audit the mikrotik router fleet", contextText: "",
-    fullContext: "audit the mikrotik router fleet", packLimit: 6, budget: {}, helpers,
+    userText: "audit mikrotik router fleet", contextText: "",
+    fullContext: "audit mikrotik router fleet", packLimit: 6, budget: {}, helpers,
   });
-  assert.ok(outTool.toolMatches.some((m) => m.name === "mikrotik-audit"), "matching tool is kept (fail-open user seed)");
+  assert.strictEqual(outTool.tier, "seeds", "4-word command lands on the seeds tier");
+  assert.ok(outTool.toolMatches.some((m) => m.name === "mikrotik-audit"), "matching tool is kept (seeds-tier user seed)");
   assert.ok(/mikrotik-audit/.test(outTool.toolBlock), "kept tool renders into the toolBlock");
   assert.ok(/Tools that may help here/.test(outTool.toolBlock), "toolBlock carries its heading");
 
+  // full-tier fail-open: with no judge, an unjudged TOOL is a guess — dropped.
+  // (Measured before the fix: a failed walk kept 15 unjudged seeds including
+  // WiFi tools for a dream question.) Pack/entity user seeds still inject.
+  const outToolFull = await disc.run({
+    userText: "audit the mikrotik router fleet inventory please", contextText: "",
+    fullContext: "audit the mikrotik router fleet inventory please", packLimit: 6, budget: {}, helpers,
+  });
+  assert.strictEqual(outToolFull.tier, "full", "substantive ask lands on the full tier");
+  assert.strictEqual(outToolFull.toolMatches.length, 0, "fail-open drops unjudged tools at full tier");
+  assert.strictEqual(outToolFull.toolBlock, "", "no unjudged toolBlock at full tier");
+
   const outNoTool = await disc.run({
     userText: "help with the mobile app", contextText: "", fullContext: "help with the mobile app",
     packLimit: 6, budget: {}, helpers,