@inetafrica/open-claudia 3.4.23 → 3.5.0

package/bin/tool.js

@@ -31,6 +31,14 @@
 // --yes-destructive — get the user's approval first; the flag records that
 // deliberate step. Read-only tools run freely.
 //
+// Who a run acts for is decided by the RUNNING BOT (loopback whoami over the
+// run's attestation), never by this process's env: the owner's turn keeps the
+// flag gate above; a staff turn's write/destructive run is decided in the bot
+// (tool-gate: mandate vet, else a held owner approval); a process with no live
+// run behind it may run write/destructive only with an owner's --approval
+// token. Changing tools (add/set/scaffold/edit/note/remove/migrate/lib set) is
+// owner-only.
+//
 // Fix before fork: when a tool is wrong, prefer `tool set` (metadata), `tool
 // note` (docs), or `tool edit` (body) over adding a near-duplicate. Hardcoded
 // secrets BLOCK a save; other lints (requires/keyring mismatch, syntax,
@@ -110,10 +118,22 @@ function reportSafety(t) {
   }
 }
 
+// Verbs that change the tool set, a tool's source/metadata, its TOOL.md, or the
+// shared _lib: owner-only. Reads (list/search/show/lib list|show/path) and
+// `run` (gated per tier below) are not in this set.
+const OWNER_ONLY_VERBS = new Set(["add", "save", "set", "fix", "scaffold", "new", "edit", "note", "migrate", "remove", "rm"]);
+const OWNER_ONLY_LIB_VERBS = new Set(["set", "add"]);
+
 async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  const libVerb = cmd === "lib" ? String(rest[0] || "list").toLowerCase() : "";
+  if (OWNER_ONLY_VERBS.has(cmd) || OWNER_ONLY_LIB_VERBS.has(libVerb)) {
+    const what = `"tool ${libVerb ? `lib ${libVerb}` : cmd}" changes the bot's tools`;
+    if (!(await require("./owner-gate").requireOwner(what))) return;
+  }
+
   // Auto-migrate legacy flat-file tools to the directory layout on first use
   // (idempotent, one git commit per tool, telemetry carried over).
   if (cmd !== "path") {
@@ -376,9 +396,14 @@ async function run(args) {
       // 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);
+      // A tool's manifest is the contract: a verb it does not declare is
+      // refused for EVERY caller, before any vet, escalation or approval
+      // redemption — there is no tier to judge or to approve.
+      if (gate.undeclared) { console.error(gate.message); process.exitCode = 3; return; }
       const approvals = require("../core/approvals");
       const commandLine = approvals.formatApprovedCommand(["open-claudia", "tool", "run", t.name, ...toolArgs]);
       let approvedVia = "";
+      let approvedTier = "";
 
       // B10: creds preflight BEFORE any approval machinery. A missing keyring
       // key used to be discovered only after the one-shot --approval token was
@@ -395,56 +420,53 @@ async function run(args) {
         }
       }
 
-      // ── Phase 3.5: per-speaker external gate ──────────────────────────────
-      // When this run is FOR an external (non-owner) speaker, a write/destructive
-      // tool cannot rely on the agent's own --yes flag — the external could have
-      // talked it into passing it. Route mutating runs through the independent
-      // mandate vet: an action the owner-authored mandate clearly covers carries
-      // the owner's authority and runs; anything else is HELD and the owner is
-      // asked (Approve/Deny/Always-allow), then re-run via a one-shot --approval
-      // token. A token already present means the owner just approved → skip.
-      // Owner / no-context speakers are never gated here, so the legacy owner
-      // path is byte-for-byte unchanged (R9/R14).
-      if (!approvalId && (gate.tier === "write" || gate.tier === "destructive")) {
-        let speaker = null;
-        try {
-          const relationship = require("../core/relationship");
-          const sp = relationship.speakerFor(process.env.OC_CHANNEL_ADAPTER, process.env.OC_CHANNEL_ID, process.env.OC_CHANNEL_USER_ID);
-          if (relationship.guardActive(sp)) speaker = sp; // else owner/no-context → ungated
-        } catch (e) { speaker = null; }
-        if (speaker) {
-          const enforcer = require("../core/enforcer");
-          let vet;
-          try { vet = await enforcer.vetAction(speaker, { command: commandLine, tier: gate.tier }); }
-          catch (e) { vet = { decision: "escalate", reason: "vet error — failing closed" }; }
-          if (vet.decision === "allow") {
+      // ── Who this run acts for, decided by the RUNNING BOT ─────────────────
+      // Read-only runs are ungated for everyone. For write/destructive the
+      // bot answers from the run's attestation (whoami), never from this
+      // process's env (OC_CHANNEL_* can be unset or rewritten by the shell):
+      //   • the owner's run → the flag/approval gate below, unchanged;
+      //   • a guarded (non-owner) run → a --yes the speaker may have talked the
+      //     agent into proves nothing, so the bot decides (tool-gate): an action
+      //     the owner-authored mandate clearly covers carries the owner's
+      //     authority; anything else is HELD with an owner card (then re-run
+      //     via a one-shot --approval token) or blocked. A token already
+      //     present means the owner approved → redeem it below;
+      //   • no live run behind this process → refused unless it presents an
+      //     owner's --approval token.
+      if (gate.tier === "write" || gate.tier === "destructive") {
+        const client = require("./loopback-client");
+        const caller = await client.whoami();
+        if (!caller.attributed) {
+          if (!approvalId) {
+            console.error(`⛔ ${t.name} (${gate.tier}) refused — not attributed to a live chat turn; write actions need a chat turn or an owner approval token.`);
+            process.exitCode = 3; return;
+          }
+        } else if (!caller.owner && !approvalId) {
+          let decision = null;
+          try {
+            const ctx = client.context();
+            if (!ctx.sendUrl || !ctx.sendToken || !ctx.channelId || !ctx.adapterId) throw new Error("no chat context to ask the bot from");
+            decision = await client.postJson("tool-gate", {
+              tool: t.name, verb: tools.invokedVerb(toolArgs), tier: gate.tier, command: commandLine,
+            });
+          } catch (e) {
+            decision = { decision: "blocked", reason: `the bot could not vet this action (${e.message})` };
+          }
+          const who = (decision && decision.name) || caller.name || "the external contact";
+          if (decision && decision.decision === "allow") {
             // The owner's mandate pre-authorizes this class of action → it carries
             // the owner's approval, satisfying the risk gate without a redundant --yes.
             approvedVia = "mandate";
+          } else if (decision && decision.decision === "held" && decision.approvalId) {
+            console.error(`🛡️ Held for owner approval — ${who} is outside mandate for this ${gate.tier} action.`);
+            console.error(`Approval ${decision.approvalId} was raised to the owner. End the turn and tell them you're checking; a wakeup fires when they decide. Do NOT retry or re-request.`);
+            process.exitCode = 5; return;
           } else {
-            const esc = await enforcer.escalate({
-              speaker, kind: "action", command: commandLine, tier: gate.tier, reason: vet.reason,
-              canonicalUserId: process.env.OC_CANONICAL_USER_ID || "",
-              userId: process.env.OC_CHANNEL_USER_ID || "",
-              provider: process.env.OC_PROVIDER || "",
-              providerSettings: (() => {
-                try {
-                  const value = JSON.parse(process.env.OC_PROVIDER_SETTINGS || "{}");
-                  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-                } catch (_) { return {}; }
-              })(),
-              project: process.env.OC_PROJECT || "",
-              projectDir: process.env.OC_PROJECT_DIR || "",
-              sessionId: process.env.OC_SESSION_ID || process.env.OC_LAST_SESSION_ID || "",
-              previousSessionId: process.env.OC_PREVIOUS_SESSION_ID || "",
-              originRunId: process.env.OC_RUN_ID || process.env.OC_ORIGIN_RUN_ID || "",
-            });
-            if (esc.escalated) {
-              console.error(`🛡️ Held for owner approval — ${speaker.name || "the external contact"} is outside mandate for this ${gate.tier} action.`);
-              console.error(`Approval ${esc.id} was raised to the owner. End the turn and tell them you're checking; a wakeup fires when they decide. Do NOT retry or re-request.`);
-              process.exitCode = 5; return;
+            if (decision && decision.unreachable) {
+              console.error(`⛔ Blocked — ${who} is outside mandate and the owner could not be reached to approve.`);
+            } else {
+              console.error(`⛔ Blocked — ${(decision && decision.reason) || "the bot did not clear this action"}; failing closed.`);
             }
-            console.error(`⛔ Blocked — ${speaker.name || "the external contact"} is outside mandate and the owner could not be reached to approve.`);
             process.exitCode = 3; return;
           }
         }
@@ -455,12 +477,15 @@ async function run(args) {
           console.error("⛔ --approval tokens are only honored on top-level runs, not nested tool calls.");
           process.exitCode = 3; return;
         }
-        const redeemed = approvals.consume(approvalId, commandLine);
+        // Bound to the tier the owner approved: a run that now resolves above
+        // it is refused without burning the token.
+        const redeemed = approvals.consume(approvalId, commandLine, { tier: gate.tier });
         if (!redeemed.ok) {
           console.error(`⛔ Approval ${approvalId} rejected: ${redeemed.reason}. The run stays blocked.`);
           process.exitCode = 3; return;
         }
         approvedVia = "chat-approval";
+        approvedTier = approvals.approvedTier(redeemed.record, gate.tier);
         console.error(`✅ Approval ${approvalId} redeemed (single use) — running.`);
       } else if (!gate.ok && approvedVia !== "mandate") {
         // Chat-approval fallback: an unflagged destructive top-level run inside
@@ -497,12 +522,13 @@ async function run(args) {
             `Re-run with --yes-destructive only after the user explicitly approves.`);
           process.exitCode = 3; return;
         }
-        const redeemed = approvals.consume(reqId, commandLine);
+        const redeemed = approvals.consume(reqId, commandLine, { tier: gate.tier });
         if (!redeemed.ok) {
           console.error(`⛔ Approval ${reqId || "(missing)"} rejected: ${redeemed.reason}. The run stays blocked.`);
           process.exitCode = 3; return;
         }
         approvedVia = "chat-approval";
+        approvedTier = approvals.approvedTier(redeemed.record, gate.tier);
         console.error(`✅ Approval ${reqId} redeemed (single use) — running.`);
       }
 
@@ -516,12 +542,14 @@ async function run(args) {
       } catch (e) { /* advisory */ }
       // Composition inheritance: export the approved tier + call chain so any
       // tool this tool shells into is gated by what the human actually approved
-      // at the top — an already-inherited tier passes through UNCHANGED.
+      // at the top — an already-inherited tier passes through UNCHANGED. A
+      // redeemed approval exports exactly the tier on the owner's card (a write
+      // approval never unlocks a nested destructive tool).
       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")
-        : (approvedVia === "chat-approval" ? "destructive"
+        : (approvedVia === "chat-approval" ? (approvedTier || gate.tier)
           : approvedVia === "mandate" ? gate.tier
           : tools.approvedTierFromArgv(toolArgs));
       env.OPEN_CLAUDIA_TOOL_STACK = parentStack ? `${parentStack}>${t.name}` : t.name;

package/bin/transcript-search.js

@@ -10,6 +10,8 @@
 
 const path = require("path");
 const index = require(path.join(__dirname, "..", "core", "transcript-index"));
+const { whoami } = require("./loopback-client");
+const { transcriptOwnerOf } = require(path.join(__dirname, "..", "project-transcripts"));
 
 function parseArgs(argv) {
   const out = { query: [], all: false, project: null, limit: 8, raw: false, rebuild: false, json: false, help: false };
@@ -47,7 +49,41 @@ Options:
 Exit codes: 0 hits, 1 no hits, 2 usage error, 3 index unavailable.`);
 }
 
-function run(argv) {
+// A non-owner's search must stay in their own room: no cross-room widening
+// (--all / --project / --rebuild) and results scoped to the caller's OWN
+// transcript. The room is decided by the RUNNING BOT (whoami — run-attested),
+// never by the process's own env; and the scoped file is confirmed to belong
+// to that principal, so an env-forged OC_TRANSCRIPT_PATH aimed at someone
+// else's transcript is refused. An attributed owner is unrestricted.
+async function resolveScope(opts) {
+  let caller;
+  try { caller = await whoami(); } catch (e) { caller = { attributed: false, owner: false }; }
+  if (caller && caller.owner === true) {
+    const file = (!opts.all && !opts.project) ? (process.env.OC_TRANSCRIPT_PATH || null) : null;
+    if (!opts.all && !opts.project && !file) {
+      console.error("No current-project transcript (OC_TRANSCRIPT_PATH unset). Use --all, --project <name>, or run inside a bot-spawned task.");
+      process.exit(2);
+    }
+    return { file, project: opts.project, all: opts.all };
+  }
+  if (opts.all || opts.project || opts.rebuild) {
+    console.error("Searching or reindexing other rooms (--all / --project / --rebuild) is owner-only. Your search is limited to this room.");
+    process.exit(2);
+  }
+  const file = process.env.OC_TRANSCRIPT_PATH || null;
+  if (!file) {
+    console.error("No room transcript to search (OC_TRANSCRIPT_PATH unset).");
+    process.exit(2);
+  }
+  const owner = transcriptOwnerOf(file);
+  if (!caller || !caller.attributed || !caller.canonicalUserId || owner !== caller.canonicalUserId) {
+    console.error("That transcript is not yours to search — search is limited to your own room.");
+    process.exit(2);
+  }
+  return { file, project: null, all: false };
+}
+
+async function run(argv) {
   const opts = parseArgs(argv);
   if (opts.help) { printHelp(); process.exit(0); }
 
@@ -56,6 +92,10 @@ function run(argv) {
     process.exit(3);
   }
 
+  // Resolve (and room-restrict) the scope BEFORE any index write: a non-owner
+  // may not --rebuild the whole index either.
+  const scope = await resolveScope(opts);
+
   if (opts.rebuild) {
     const r = index.rebuild();
     console.error(`Rebuilt index: ${r.added} entries from ${r.files} transcript files.`);
@@ -67,13 +107,7 @@ function run(argv) {
 
   if (!opts.query) { printHelp(); process.exit(2); }
 
-  const file = (!opts.all && !opts.project) ? (process.env.OC_TRANSCRIPT_PATH || null) : null;
-  if (!opts.all && !opts.project && !file) {
-    console.error("No current-project transcript (OC_TRANSCRIPT_PATH unset). Use --all, --project <name>, or run inside a bot-spawned task.");
-    process.exit(2);
-  }
-
-  const { hits, error } = index.search(opts.query, { project: opts.project, file, limit: opts.limit, raw: opts.raw });
+  const { hits, error } = index.search(opts.query, { project: scope.project, file: scope.file, limit: opts.limit, raw: opts.raw });
   if (error) { console.error(`Query error: ${error}${opts.raw ? "" : " (internal — please report)"}`); process.exit(2); }
   if (hits.length === 0) {
     console.error(`No matches for ${JSON.stringify(opts.query)}${opts.all ? " across all projects" : ""}.`);

package/bin/transcript-window.js

@@ -10,6 +10,9 @@
 //   3. error out — we don't try to guess
 
 const fs = require("fs");
+const path = require("path");
+const { whoami } = require("./loopback-client");
+const { transcriptOwnerOf } = require(path.join(__dirname, "..", "project-transcripts"));
 
 const DEFAULTS = {
   before: 2,
@@ -78,6 +81,32 @@ function resolveTranscriptPath(flagPath) {
   return null;
 }
 
+// A non-owner may only read their OWN room's transcript: --path (an arbitrary
+// file, e.g. the owner's) is refused, and the default OC_TRANSCRIPT_PATH is
+// confirmed to belong to the caller (whoami — run-attested, not the process's
+// own env) so an env-forged path aimed elsewhere is refused. Returns the
+// transcript path to read, or exits with a refusal. Owner is unrestricted.
+async function resolveScopedTranscriptPath(opts) {
+  let caller;
+  try { caller = await whoami(); } catch (e) { caller = { attributed: false, owner: false }; }
+  if (caller && caller.owner === true) return resolveTranscriptPath(opts.path);
+  if (opts.path) {
+    console.error("Reading another transcript with --path is owner-only. You can read only your own room's transcript.");
+    process.exit(2);
+  }
+  const file = process.env.OC_TRANSCRIPT_PATH || null;
+  if (!file) {
+    console.error("No room transcript to read (OC_TRANSCRIPT_PATH unset).");
+    process.exit(2);
+  }
+  const owner = transcriptOwnerOf(file);
+  if (!caller || !caller.attributed || !caller.canonicalUserId || owner !== caller.canonicalUserId) {
+    console.error("That transcript is not yours to read — you can read only your own room's transcript.");
+    process.exit(2);
+  }
+  return file;
+}
+
 function loadTurns(transcriptPath) {
   const raw = fs.readFileSync(transcriptPath, "utf-8");
   const turns = [];
@@ -125,13 +154,13 @@ function formatTurn(turn, label, maxChars) {
   ].join("\n");
 }
 
-function run(argv) {
+async function run(argv) {
   const opts = parseArgs(argv);
   if (opts.help || !opts.pattern) {
     printHelp();
     process.exit(opts.help ? 0 : 2);
   }
-  const transcriptPath = resolveTranscriptPath(opts.path);
+  const transcriptPath = await resolveScopedTranscriptPath(opts);
   if (!transcriptPath) {
     console.error("No transcript path. Pass --path <file>, or run inside an active bot-spawned task (OC_TRANSCRIPT_PATH).");
     process.exit(2);

package/core/actions.js

@@ -741,15 +741,26 @@ async function handleAction(envelope) {
     const reach = parts[2]; // "room" | "all"
     if (reach !== "room" && reach !== "all") return;
     if (!rec) return send("That request expired — nothing to grant from it.");
+    // Destructive is never a standing permission: each destructive run gets
+    // its own card, however often the owner has approved one before.
+    if (String(rec.tier || "").toLowerCase() === "destructive") {
+      return send("Destructive actions always ask; no standing permission. Use Approve once for this run.");
+    }
     if (!rec.speakerId || !rec.room) return send("I can't tell who asked apart from where they asked — no grant written.");
+    // A grant covers one identifiable person. An anonymous admin, a channel
+    // post, a missing sender or the bot itself would hand it to whoever
+    // hides behind that id.
+    const grantsLib = require("./grants");
+    const refusal = grantsLib.principalRefusal({ adapter: rec.targetAdapter || rec.adapter, senderId: rec.speakerId, room: rec.room });
+    if (refusal) {
+      return send(`No standing permission for ${refusal} — a grant needs one identifiable person. Use Approve once for this request.`);
+    }
     // A reply/triage card only ever cleared talking; an action card carries the
     // tier it asked for. Never grant more than the card actually showed.
-    const capability = rec.kind === "action"
-      ? (String(rec.tier || "") === "destructive" ? "destructive" : "act")
-      : "read";
+    const capability = rec.kind === "action" ? "act" : "read";
     let record;
     try {
-      record = require("./grants").grant({
+      record = grantsLib.grant({
         adapter: rec.targetAdapter || rec.adapter,
         senderId: rec.speakerId,
         room: rec.room,

package/core/approvals.js

@@ -112,7 +112,7 @@ function prune() {
 // speaker), the vetted `payloadText` to deliver on a reply approval, the
 // `target*` external channel, and person/entity pointers for Always-allow.
 function create({
-  tool, verb = "", tier = "destructive", command = "", channelId = "", adapter = "",
+  tool, verb = "", tier = "", command = "", channelId = "", adapter = "",
   canonicalUserId = "", userId = "", provider = "", providerSettings = {},
   project = "", projectDir = "", sessionId = "", previousSessionId = "", originRunId = "",
   kind = "tool", approverAdapter = "", approverChannel = "",
@@ -205,10 +205,30 @@ function detach(id) {
   } finally { releaseRecordLock(held); }
 }
 
+// Risk tiers an approval can carry for a tool run. A record's `tier` is what
+// the owner saw on the card; reply/triage records carry non-tool tiers.
+const TIER_RANK = { "read-only": 0, write: 1, destructive: 2 };
+
+function riskTier(value) {
+  const tier = String(value || "").trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(TIER_RANK, tier) ? tier : "";
+}
+
+// The tier a redeemed approval authorizes: exactly the tier on the record the
+// owner approved. A record without one (created before tiers were recorded)
+// falls back to the tier the tool/verb declares for this run — never to
+// "destructive" by default.
+function approvedTier(record, runTier) {
+  return riskTier(record && record.tier) || riskTier(runTier) || "read-only";
+}
+
 // One-shot token redemption for the async path. Fail-closed on every branch:
 // only an approved, un-consumed, un-expired record whose stored command is
 // byte-identical to what is about to run can be consumed — and only once.
-function consume(id, commandLine) {
+// With `tier` (the run's resolved tier), a run that now resolves above the tier
+// the owner approved (the verb was reclassified since) is refused WITHOUT
+// consuming the token: an approval never stretches past what the card showed.
+function consume(id, commandLine, { tier = "" } = {}) {
   try { fileOf(id); }
   catch (_) { return { ok: false, reason: "unknown or expired approval id" }; }
   const held = acquireRecordLock(id);
@@ -231,6 +251,11 @@ function consume(id, commandLine) {
       : Buffer.byteLength(String(rec.command || "")) <= MAX_COMMAND_BYTES
         && candidate === String(rec.command || "");
     if (!matches) return { ok: false, reason: "command does not match the approved payload" };
+    const approved = riskTier(rec.tier);
+    const wanted = riskTier(tier);
+    if (approved && wanted && TIER_RANK[wanted] > TIER_RANK[approved]) {
+      return { ok: false, reason: `approval covers a ${approved} run, but this run is ${wanted}` };
+    }
     rec.consumedAt = new Date().toISOString();
     writeRecord(rec);
     return { ok: true, record: rec };
@@ -277,6 +302,7 @@ function markMined(ids) {
 module.exports = {
   APPROVALS_DIR,
   MAX_COMMAND_BYTES,
+  approvedTier,
   commandHash,
   consume,
   create,