@inetafrica/open-claudia 2.7.1 → 2.7.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v2.7.2
+- **Credential confinement — keyring creds now live ONLY inside tool runs (enforcement 5b).** Until now `botSubprocessEnv()` merged the whole operational keyring into *every* agent subprocess, so the agent's own Bash (and any sub-agent) could `curl` a prod API with `$inet_central_user` directly — the tool layer was optional. That merge is gone: agent shells and sub-agents run cred-free, and `tools.runEnv(tool)` injects **only the keys a tool declares via `--requires`**, read fresh from the keyring at run time (least privilege; `process.env` still wins on conflict). Audited all 11 live tools before shipping: every keyring key read is already declared, so nothing breaks. The system prompt's Preauth bullet now tells the truth, and `keyring list` no longer claims env-wide availability.
+- **Tool-first deny-gate on the agent's shell (enforcement 5b).** A PreToolUse hook (wired via `--settings` into the main runner *and* sub-agent spawns; new `core/tool-guard.js` + `open-claudia deny-gate-hook`) blocks raw operational commands against known prod surfaces and redirects to the covering tool by name — or to the exact `tool scaffold` command when nothing covers the surface yet. v1 rules are deliberately high-precision: an **acting** binary (curl/wget/ssh/mongosh/…) aimed at `central.inet.africa`, `ticketcentral`, `10.200.0.0/16`, `kubectl exec … mongo(sh)`, or `ssh codersafrica@` — while `grep`/`cat`/`ping` mentioning the same surfaces, read-only `kubectl`, and plain `git push` stay free (reading is always allowed; acting goes through tools). Quotes count as command separators so `bash -c "curl …"` can't dodge the gate. Every failure mode in the gate fails OPEN — a broken guard must never brick the shell. This gate is the honest enforcement for surfaces where confinement is toothless (kubectl/ssh use ambient creds, not keyring keys); the accepted residual dodge is writing the command into a script file first.
+- **`keyring exec --reason "<why>" -- <cmd>` — the logged escape hatch.** Confinement without a pressure valve just breeds invisible workarounds (`keyring get` + copy-paste). A genuine one-off no tool covers yet runs through `keyring exec`: full keyring in env for exactly one command, reason mandatory, and the bypass recorded to `~/.open-claudia/tool-guard.jsonl` alongside every deny — the audit stream the 5c KPI pass will read to decide which tools to scaffold next. New `test-tool-guard.js` covers the rule matrix, hook protocol (exit 2/stderr deny, fail-open), audit trail, settings writer idempotency, and env confinement; `test-tools.js` extends to least-privilege injection.
+
 ## v2.7.1
 - **The system prompt now teaches tool-FIRST, not tool-after (enforcement 5d).** The fixed "Reusable tools" section in `core/system-prompt.js` was the root cause of the baseline failure: it taught "crystallise the script you just wrote" — do the work raw, save a tool afterwards. Rewritten as "Tools are the interface": before operational work, walk the loop **search → use (read TOOL.md first, never guess args) → extend the missing verb → scaffold first** — and only then do the work *through* the tool. Raw one-liners and heredocs are demoted to probing/diagnosis; a broken tool gets fixed or journaled (`tool note --issue`), never routed around. The section also documents the risk gate honestly: the `--yes`/`--yes-destructive` flag is the agent's mechanical acknowledgment *after* the user approves — it never replaces asking first.
 - **Tool-scout: operational turns can no longer meet silence (enforcement 5a).** Today an empty tool match is silent, and silence reads as permission to improvise. The discoverer now runs a pattern-based scout (no LLM, ~zero cost) over each seeds/full-tier turn: a table of high-precision operational domains — named hosts (central.inet.africa, ticket-central, chat-central, git.coders.africa…), prod IP ranges, infra commands (kubectl, argocd, mongosh…) — each with a `covers` matcher against the tool registry. When a turn trips a domain: if a registry tool covers it but wasn't auto-surfaced, the block points at it by name (`tool show X`, then work through it); if **nothing** covers it, the block says so and hands over the exact scaffold command (`tool scaffold <suggested-name> --risk write`). Domains already covered by a surfaced tool stay quiet, and non-operational chatter never trips the patterns (precision over recall — they expand from audit evidence later, per 5c). Gap signals flow into recall metrics (`toolGaps`) and the engine result for future `/tooltrace` surfacing. Extends `test-recall-discoverer.js` with pure-function and through-the-engine scout coverage.

package/bin/cli.js

@@ -134,6 +134,23 @@ switch (command) {
     require(path.join(botDir, "setup.js"));
     break;
 
+  // PreToolUse hook target (tool-first deny-gate, 5b). Claude pipes the tool
+  // payload on stdin; exit 2 + stderr = deny (message fed back to the model),
+  // exit 0 = allow. Every failure mode fails OPEN — a broken gate must never
+  // brick the agent's shell.
+  case "deny-gate-hook": {
+    let code = 0;
+    try {
+      const payload = fs.readFileSync(0, "utf-8");
+      const { runHook } = require(path.join(botDir, "core", "tool-guard"));
+      const res = runHook(payload);
+      if (res.stderr) console.error(res.stderr);
+      code = res.exit;
+    } catch (e) { code = 0; }
+    process.exit(code);
+    break;
+  }
+
   case "start": {
     const skipHealthCheck = args.includes("--skip-health") || args.includes("--force");
     const botFile = getBotFile();

package/bin/keyring.js

@@ -5,6 +5,13 @@
 //   open-claudia keyring set <name> <value> — store/replace a credential
 //   open-claudia keyring remove <name>     — delete one
 //   open-claudia keyring path              — print the file path
+//   open-claudia keyring exec --reason "<why>" -- <cmd> [args...]
+//       — logged escape hatch (5b): run ONE command with the full keyring in
+//         env. Confinement means the agent shell holds no creds and tool runs
+//         get only their --requires keys; when a genuine one-off needs a cred
+//         and no tool covers it yet, this is the honest path — the reason is
+//         mandatory and every use lands in the guard log for the KPI pass.
+//         Shell features need an explicit shell: ... -- bash -c "curl … | jq".
 //
 // For genuine personal secrets the bot should NOT use unattended, use the
 // vault (/vault) instead — it stays encrypted and locked.
@@ -20,12 +27,48 @@ function run(args) {
       const entries = keyring.list();
       const names = Object.keys(entries);
       if (names.length === 0) return console.log(`Keyring is empty (${keyring.KEYRING_FILE}).`);
-      console.log(`${names.length} credential(s) — available to the agent as env vars:\n`);
+      console.log(`${names.length} credential(s) — injected only into tool runs that declare them (--requires):\n`);
       for (const k of names) console.log(`${k} = ${entries[k]}`);
       console.log(`\nFile: ${keyring.KEYRING_FILE}`);
       break;
     }
 
+    // Logged escape hatch (5b): full-keyring env for ONE command, reason
+    // mandatory, bypass recorded to the guard log. This is the pressure valve
+    // that keeps confinement honest — without it, the workaround would be
+    // `keyring get` + copy-paste, which is worse and invisible.
+    case "exec": {
+      const sep = rest.indexOf("--");
+      const flagArgs = sep === -1 ? rest : rest.slice(0, sep);
+      const cmdArgv = sep === -1 ? [] : rest.slice(sep + 1);
+      let reason = "";
+      for (let i = 0; i < flagArgs.length; i++) {
+        if (flagArgs[i] === "--reason") reason = flagArgs[i + 1] || "";
+        else if (flagArgs[i].startsWith("--reason=")) reason = flagArgs[i].slice(9);
+      }
+      if (!reason.trim() || cmdArgv.length === 0) {
+        console.error('Usage: keyring exec --reason "<why no tool covers this>" -- <cmd> [args...]');
+        console.error("The reason is mandatory — every exec is logged as a confinement bypass.");
+        process.exitCode = 1; return;
+      }
+      try {
+        require("../core/tool-guard").logGuardEvent({
+          kind: "bypass", reason: reason.trim(), command: cmdArgv.join(" ").slice(0, 300),
+        });
+      } catch (e) { /* logging is best-effort */ }
+      const { spawnSync } = require("child_process");
+      let base;
+      try { base = require("../core/config").botSubprocessEnv(); }
+      catch (e) { base = { ...process.env }; }
+      const r = spawnSync(cmdArgv[0], cmdArgv.slice(1), {
+        stdio: "inherit",
+        env: { ...keyring.all(), ...base },
+      });
+      if (r.error) { console.error(`keyring exec failed: ${r.error.message}`); process.exitCode = 1; return; }
+      process.exitCode = typeof r.status === "number" ? r.status : 1;
+      break;
+    }
+
     case "get": {
       const key = rest[0];
       if (!key) { console.error("Usage: keyring get <name>"); process.exitCode = 1; return; }
@@ -57,7 +100,7 @@ function run(args) {
       break;
 
     default:
-      console.log('Usage: open-claudia keyring [list|get <name>|set <name> <value>|remove <name>|path]');
+      console.log('Usage: open-claudia keyring [list|get <name>|set <name> <value>|remove <name>|path|exec --reason "<why>" -- <cmd>]');
   }
 }
 

package/bin/tool.js

@@ -34,9 +34,10 @@
 // secrets BLOCK a save; other lints (requires/keyring mismatch, syntax,
 // dangling pack link) stay advisory.
 //
-// Credentials: a tool runs with the operational keyring merged into its env, so
-// reference creds as $NAME inside the script. `open-claudia keyring list` shows
-// what's available; never hardcode secrets in a tool.
+// Credentials (least-privilege, 5b): a tool run receives ONLY the keyring keys
+// 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.
 
 const { spawnSync } = require("child_process");
 const tools = require("../core/tools");
@@ -325,7 +326,7 @@ function run(args) {
         process.exitCode = 1; return;
       }
       const started = Date.now();
-      const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env: tools.runEnv() });
+      const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env: tools.runEnv(t) });
       const ms = Date.now() - started;
       if (r.error) {
         tools.recordRunResult(t.name, { args: toolArgs, exit: -1, ms });

package/core/config.js

@@ -219,16 +219,12 @@ function loadChannels() {
 }
 
 function botSubprocessEnv() {
-  const base = { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() };
-  // Merge operational keyring creds so the agent can *use* what it remembered.
-  // Read fresh each spawn so a cred set mid-session is live next turn without a
-  // restart. process.env wins on conflict — bot infra config is authoritative.
-  try {
-    const keyring = require("./keyring");
-    return { ...keyring.all(), ...base };
-  } catch (e) {
-    return base;
-  }
+  // Credential confinement (5b): the operational keyring is deliberately NOT
+  // merged here. Agent shells, sub-agents, and every other bot subprocess run
+  // cred-free; keyring values enter ONLY tool-run subprocesses (tools.runEnv —
+  // the keys a tool declares via --requires) and the logged escape hatch
+  // (`keyring exec --reason`). See core/tool-guard.js for the deny-gate half.
+  return { ...process.env, PATH: FULL_PATH, HOME: process.env.HOME || require("os").homedir() };
 }
 
 module.exports = {

package/core/handlers.js

@@ -1512,10 +1512,12 @@ register({
 module.exports.PENDING_VAULT_TTL_MS = PENDING_VAULT_TTL_MS;
 
 // ── Keyring (operational, plaintext) ───────────────────────────────
-// Unlike the vault, the keyring is always available to the agent (no
-// password, no lock) so it can repeat work you've shown it once. Use it for
-// creds the agent is allowed to use unattended; use /vault for personal
-// secrets it must not. Values are injected into the agent's env each turn.
+// Unlike the vault, the keyring is always available (no password, no lock) so
+// the agent can repeat work you've shown it once. Use it for creds the agent
+// is allowed to use unattended; use /vault for personal secrets it must not.
+// Confinement (5b): values are injected only into tool runs that declare them
+// via --requires (plus the logged `keyring exec` escape hatch) — never into
+// the agent's own shell.
 
 register({
   name: "keyring", description: "Manage operational credentials (plaintext, agent-usable)", args: "[set|get|remove] ...",
@@ -1528,7 +1530,7 @@ register({
       if (names.length === 0) {
         return send("Keyring is empty.\n\nStore a credential the agent can reuse:\n/keyring set <name> <value>\n\n(For personal secrets the agent should NOT use on its own, use /vault instead.)");
       }
-      return send("Keyring (available to the agent as env vars):\n\n" + names.map((k) => `${k}: ${entries[k]}`).join("\n") + "\n\nGet a value: /keyring get <name>");
+      return send("Keyring (injected into tool runs that declare them via --requires):\n\n" + names.map((k) => `${k}: ${entries[k]}`).join("\n") + "\n\nGet a value: /keyring get <name>");
     }
 
     const setMatch = tail.match(/^set\s+(\S+)\s+([\s\S]+)$/);
@@ -1538,7 +1540,7 @@ register({
       const value = setMatch[2].trim();
       keyring.set(setMatch[1], value);
       registerSecrets([value]);
-      return send(`Stored ${setMatch[1]}. I deleted your message. It's available to the agent from the next turn.`);
+      return send(`Stored ${setMatch[1]}. I deleted your message. Tools that declare it via --requires can use it from their next run.`);
     }
 
     const getMatch = tail.match(/^get\s+(\S+)$/);

package/core/keyring.js

@@ -12,9 +12,11 @@
 // (chmod 600) + log redaction, not encryption. Keep genuine personal secrets
 // in the vault; keep "creds the agent is allowed to use on its own" here.
 //
-// Values set here flow to every agent subprocess via botSubprocessEnv()
-// (config.js), so a credential stored once is present as an env var on the
-// next turn — no restart needed.
+// Confinement (5b): values do NOT flow into agent shells or sub-agents.
+// They are injected only into `tool run` subprocesses — and only the keys a
+// tool declares via --requires (tools.runEnv) — plus the logged escape hatch
+// `keyring exec --reason`. Read fresh each run, so a credential stored once
+// is live for the next tool run with no restart.
 
 const fs = require("fs");
 const path = require("path");

package/core/runner.js

@@ -296,6 +296,9 @@ async function buildClaudeArgs(prompt, opts = {}) {
   if (settings.backend === "codex") return buildCodexArgs(prompt, opts);
   const args = ["-p", "--verbose", "--output-format", "stream-json",
     "--append-system-prompt", buildSystemPrompt()];
+  // Tool-first deny-gate (5b): PreToolUse hook on Bash via --settings. A
+  // failure to write the settings file just means no gate this turn (fail-open).
+  try { args.push("--settings", require("./tool-guard").ensureHookSettings()); } catch (e) {}
   const transcriptInfo = transcriptProjectInfo(state);
   if (transcriptInfo) args.push("--add-dir", transcriptInfo.transcriptsDir);
   if (opts.resumeSessionId) args.push("--resume", opts.resumeSessionId);

package/core/subagent.js

@@ -64,6 +64,9 @@ async function spawnSubagent(prompt, opts = {}) {
     // to make a sub-agent genuinely read-only (e.g. the dream's introspection).
     if (opts.allowedTools) args.push("--allowedTools", [].concat(opts.allowedTools).join(","));
     if (opts.disallowedTools) args.push("--disallowedTools", [].concat(opts.disallowedTools).join(","));
+    // Sub-agents get the same tool-first deny-gate as the main agent (5b) —
+    // they also hold no keyring creds (botSubprocessEnv is cred-free).
+    try { args.push("--settings", require("./tool-guard").ensureHookSettings()); } catch (e) {}
     args.push(
       "--output-format", opts.json ? "json" : "text",
       "--verbose",

package/core/system-prompt.js

@@ -96,7 +96,8 @@ Raw shell one-liners and heredocs are for probing and diagnosis only — never t
 
 - Risk gate: read-only tools run freely; write-tier needs \`--yes\`; destructive needs \`--yes-destructive\`. The flag is your mechanical acknowledgment AFTER the user approves the action — it never replaces asking first.
 - 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: the operational keyring is merged into tool runs — and into your own Bash. Reference creds as \`$inet_central_user\` etc. (\`open-claudia keyring list\` shows names); declare a tool's needs via \`--requires\` so a missing key reports before the run; never write a secret into a tool file (saves are refused).
+- 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\`.
 ${listing}`;
 }

package/core/tool-guard.js

@@ -0,0 +1,163 @@
+// Tool-first deny-gate (enforcement 5b): a PreToolUse hook on the agent's Bash
+// that blocks RAW operational commands against known production surfaces and
+// redirects to the reusable tool (or a scaffold, or the logged escape hatch).
+//
+// Why a hook and not prompt text: prompt guidance is advice the model can
+// drift past; a hook is fixed code behaviour. Why these patterns: v1 is
+// deliberately high-precision — only an ACTING network/exec binary aimed at a
+// known prod surface trips it, so `grep central.inet.africa src/api.js` (read/
+// diagnosis) stays free while `curl central.inet.africa/...` (the operational
+// action) is denied. Reading is always allowed; acting goes through tools.
+//
+// Honest coverage: this gate + the audit log ARE the enforcement for surfaces
+// where credential confinement is toothless (kubectl/ssh use ambient creds,
+// not keyring keys). A script-file dodge (write the curl into a .sh and run
+// it) slips through — accepted as best-effort; the dream's KPI pass reads the
+// guard log to spot chronic bypassing.
+//
+// Fail-open doctrine: any error in the gate itself must NEVER brick the
+// agent's shell — parse failures, fs errors, unknown payloads all allow.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+
+const GUARD_LOG = process.env.TOOL_GUARD_LOG || path.join(CONFIG_DIR, "tool-guard.jsonl");
+const SETTINGS_FILE = process.env.DENY_GATE_SETTINGS || path.join(CONFIG_DIR, "deny-gate.settings.json");
+
+// The authorised channels themselves must never be denied.
+const ALLOW_RE = /^\s*open-claudia\s+(?:tool\s+run|keyring\s+exec)\b/;
+
+// An acting network/DB/shell-access binary at a command position (start of
+// string or after a separator). Deliberately excludes read-only diagnosis
+// (ping, dig, nslookup, traceroute) and non-network tools — mentioning a host
+// in grep/cat/echo is probing, not operating. Quotes count as separators so
+// `bash -c "curl …"` doesn't dodge the gate (cost: `echo "curl <prod-url>"`
+// is a rare false positive — the deny message explains the way through).
+const NET_CMD_RE = /(?:^|[|;&(`'"]|\$\()\s*(?:sudo\s+)?(?:curl|wget|http|https|httpie|xh|aria2c|ssh|scp|sftp|rsync|nc|ncat|telnet|socat|mongo|mongosh|psql|mysql|redis-cli)\b/;
+
+// v1 rules — each fires on (needsNetCmd ? NET_CMD_RE && target : raw).
+// `redirect` is what the model sees instead of silence: the covering tool by
+// name, or the exact scaffold command when nothing covers the surface yet.
+const RULES = [
+  {
+    id: "ticket-central-api",
+    label: "ticket-central API",
+    target: /ticketcentral/i,
+    needsNetCmd: true,
+    redirect: 'No tool fronts ticket-central yet — scaffold first: open-claudia tool scaffold kticket --desc "ticket-central API" --risk write',
+  },
+  {
+    id: "inet-central-api",
+    label: "inet-central platform API",
+    target: /(?:^|[^a-z0-9.-])central\.inet\.africa/i,
+    needsNetCmd: true,
+    redirect: "Use the reusable tool: open-claudia tool show inet-central-cli, then tool run inet-central-cli …",
+  },
+  {
+    id: "prod-network",
+    label: "production network host (10.200.0.0/16)",
+    target: /\b10\.200\.\d{1,3}\.\d{1,3}\b/,
+    needsNetCmd: true,
+    redirect: "Front prod-network access with a reusable tool (open-claudia tool search <device/system>), or scaffold one.",
+  },
+  {
+    id: "in-cluster-mongo",
+    label: "in-cluster MongoDB via kubectl exec",
+    raw: /\bkubectl\s+exec\b[^\n]*\bmongo(?:sh)?\b/i,
+    redirect: "Use the reusable tool: open-claudia tool show prod-k8s (it fronts in-cluster mongosh), then tool run prod-k8s …",
+  },
+  {
+    id: "gitlab-ssh",
+    label: "GitLab host shell (ssh codersafrica@)",
+    raw: /\bssh\s+\S*codersafrica@/i,
+    redirect: 'No tool fronts GitLab host ops yet — scaffold first: open-claudia tool scaffold gitlab-ops --desc "GitLab / coders.africa host ops" --risk write. (Plain git push/pull is unaffected.)',
+  },
+];
+
+// Pure: null (allow) or the matched rule.
+function matchRule(command) {
+  const cmd = String(command || "");
+  if (!cmd.trim()) return null;
+  if (ALLOW_RE.test(cmd)) return null;
+  for (const rule of RULES) {
+    if (rule.raw) {
+      if (rule.raw.test(cmd)) return rule;
+    } else if (rule.target.test(cmd) && NET_CMD_RE.test(cmd)) {
+      return rule;
+    }
+  }
+  return null;
+}
+
+function denyMessage(rule) {
+  return (
+    `⛔ Tool-first deny-gate: raw ${rule.label} access from the agent shell is blocked.\n` +
+    `${rule.redirect}\n` +
+    `Genuine one-off with no tool? Escape hatch (logged): open-claudia keyring exec --reason "<why>" -- <command>`
+  );
+}
+
+// Append-only audit trail — read by the 5c KPI pass. Best-effort: a logging
+// failure must not turn into a denial or a crash.
+function logGuardEvent(evt) {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...evt });
+    fs.appendFileSync(GUARD_LOG, line + "\n");
+  } catch (e) { /* best effort */ }
+}
+
+// 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).
+function runHook(payload) {
+  let data = payload;
+  try {
+    if (typeof payload === "string") data = JSON.parse(payload);
+  } catch (e) {
+    return { exit: 0, stderr: "" };
+  }
+  try {
+    if (!data || data.tool_name !== "Bash") return { exit: 0, stderr: "" };
+    const command = data.tool_input && data.tool_input.command;
+    const rule = matchRule(command);
+    if (!rule) return { exit: 0, stderr: "" };
+    logGuardEvent({ kind: "deny", rule: rule.id, command: String(command).slice(0, 300) });
+    return { exit: 2, stderr: denyMessage(rule) };
+  } catch (e) {
+    return { exit: 0, stderr: "" };
+  }
+}
+
+// The claude --settings payload wiring the hook in. Absolute node + cli paths
+// so it works regardless of the subprocess PATH; 10s timeout so a hung gate
+// can't stall a turn (hook timeout → claude proceeds, i.e. fail-open).
+function hookSettings() {
+  const cli = path.resolve(__dirname, "..", "bin", "cli.js");
+  return {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "Bash",
+          hooks: [
+            { type: "command", command: `${JSON.stringify(process.execPath)} ${JSON.stringify(cli)} deny-gate-hook`, timeout: 10 },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+// Write (or refresh) the settings file and return its path for --settings.
+// Content-compared so repeated spawns don't churn the file. Throws only up to
+// the caller's try/catch — a failure there just means no gate this turn.
+function ensureHookSettings() {
+  const body = JSON.stringify(hookSettings(), null, 2) + "\n";
+  try {
+    if (fs.readFileSync(SETTINGS_FILE, "utf-8") === body) return SETTINGS_FILE;
+  } catch (e) { /* missing/unreadable → write */ }
+  fs.writeFileSync(SETTINGS_FILE, body);
+  return SETTINGS_FILE;
+}
+
+module.exports = { RULES, GUARD_LOG, SETTINGS_FILE, matchRule, denyMessage, logGuardEvent, runHook, hookSettings, ensureHookSettings };

package/core/tools.js

@@ -15,10 +15,11 @@
 // 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()). 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.
+// Preauth, least-privilege (5b): a tool run receives ONLY the keyring keys it
+// declares via --requires (see runEnv(tool)) — the agent's own shell holds no
+// keyring creds at all. 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
@@ -628,17 +629,26 @@ function runGate(tool, argv = []) {
   };
 }
 
-// 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).
-function runEnv() {
-  try { return require("./config").botSubprocessEnv(); }
-  catch (e) {
+// Env for running a tool: the bot's cred-free subprocess env plus ONLY the
+// keyring keys this tool declares via --requires — least-privilege credential
+// injection (5b). Undeclared keys never reach the subprocess; process.env wins
+// on conflict (bot infra config stays authoritative). Keys read fresh each run
+// so a cred set mid-session is live immediately.
+function runEnv(tool) {
+  let base;
+  try { base = require("./config").botSubprocessEnv(); }
+  catch (e) { base = { ...process.env }; }
+  const requires = (tool && tool.requires) || [];
+  if (requires.length) {
     try {
       const keyring = require("./keyring");
-      return { ...keyring.all(), ...process.env };
-    } catch (e2) { return { ...process.env }; }
+      for (const k of requires) {
+        const v = keyring.get(k);
+        if (v !== null && base[k] === undefined) base[k] = v;
+      }
+    } catch (e) { /* keyring unavailable — the tool runs without creds */ }
   }
+  return base;
 }
 
 // Which of a tool's required keyring keys are actually present right now — used

package/package.json

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

package/test-tool-guard.js

@@ -0,0 +1,92 @@
+// Tool-first deny-gate + credential confinement (5b). Contract: an ACTING
+// network/DB/shell command aimed at a known prod surface is denied with a
+// redirect to the covering tool (or a scaffold command, plus the logged escape
+// hatch); probing/diagnosis that merely MENTIONS a surface stays free; the
+// authorised channels (tool run / keyring exec) are never denied; every guard
+// failure mode fails OPEN. Confinement: botSubprocessEnv carries NO keyring
+// values (least-privilege runEnv injection is covered in test-tools.js).
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tool-guard-"));
+process.env.TOOL_GUARD_LOG = path.join(tmp, "guard.jsonl");
+process.env.DENY_GATE_SETTINGS = path.join(tmp, "deny-gate.settings.json");
+process.env.KEYRING_FILE = path.join(tmp, "keyring.json");
+
+const guard = require("./core/tool-guard");
+
+// ── denies: acting command × prod surface ──
+assert.strictEqual(guard.matchRule("curl -s https://central.inet.africa/api/v1/users").id, "inet-central-api");
+assert.strictEqual(guard.matchRule("wget http://ticketcentral.inet.africa/tickets").id, "ticket-central-api");
+assert.strictEqual(guard.matchRule("ssh admin@10.200.3.14").id, "prod-network");
+assert.strictEqual(guard.matchRule('kubectl exec -it mongo-0 -- mongosh --eval "db.users.find()"').id, "in-cluster-mongo");
+assert.strictEqual(guard.matchRule("ssh codersafrica@git.coders.africa").id, "gitlab-ssh");
+assert.strictEqual(guard.matchRule("echo start && curl https://central.inet.africa/x").id, "inet-central-api",
+  "acting binary after && still trips the gate");
+assert.strictEqual(guard.matchRule('bash -c "curl https://central.inet.africa/x"').id, "inet-central-api",
+  "bash -c wrapping does not dodge the gate (quotes count as separators)");
+
+// ── allows: probing, diagnosis, unrelated work, the authorised channels ──
+assert.strictEqual(guard.matchRule("grep -rn central.inet.africa src/"), null, "grep mentioning a host is probing, not operating");
+assert.strictEqual(guard.matchRule("cat notes/10.200.1.1.md"), null, "no acting net command → allow");
+assert.strictEqual(guard.matchRule("ping 10.200.1.1"), null, "ping is read-only diagnosis");
+assert.strictEqual(guard.matchRule("kubectl get pods -A"), null, "read-only kubectl is not gated");
+assert.strictEqual(guard.matchRule("kubectl logs api-7f9 -n prod"), null, "kubectl logs is not gated");
+assert.strictEqual(guard.matchRule("git push origin main"), null, "GitOps flow unaffected");
+assert.strictEqual(guard.matchRule("curl https://api.github.com/repos"), null, "non-prod hosts are not gated");
+assert.strictEqual(guard.matchRule("open-claudia tool run inet-central-cli users list"), null, "tool run is the authorised channel");
+assert.strictEqual(guard.matchRule('open-claudia keyring exec --reason "x" -- curl https://central.inet.africa/x'), null,
+  "keyring exec is the logged escape hatch, never denied");
+assert.strictEqual(guard.matchRule(""), null, "empty command → allow");
+assert.strictEqual(guard.matchRule("see the ticketcentral docs for details"), null, "mentioning a surface without acting → allow");
+
+// ── deny message: names the covering tool / scaffold command + escape hatch ──
+const msg = guard.denyMessage(guard.matchRule("curl https://central.inet.africa/x"));
+assert.ok(/inet-central-cli/.test(msg), "deny names the covering tool");
+assert.ok(/keyring exec --reason/.test(msg), "deny names the escape hatch");
+assert.ok(/tool scaffold kticket/.test(guard.denyMessage(guard.matchRule("curl http://ticketcentral.inet.africa/x"))),
+  "no covering tool → scaffold-first redirect with the exact command");
+assert.ok(/prod-k8s/.test(guard.denyMessage(guard.matchRule("kubectl exec mongo-0 -- mongosh"))),
+  "in-cluster mongo redirects to prod-k8s");
+
+// ── runHook protocol: exit 2 + stderr on deny, exit 0 on allow, fail-open ──
+const deny = guard.runHook(JSON.stringify({ tool_name: "Bash", tool_input: { command: "curl https://central.inet.africa/x" } }));
+assert.strictEqual(deny.exit, 2, "deny → exit 2 (blocking)");
+assert.ok(/deny-gate/.test(deny.stderr), "deny → stderr message for the model");
+assert.strictEqual(guard.runHook(JSON.stringify({ tool_name: "Bash", tool_input: { command: "ls -la" } })).exit, 0, "benign Bash → allow");
+assert.strictEqual(guard.runHook(JSON.stringify({ tool_name: "Read", tool_input: { file_path: "/etc/hosts" } })).exit, 0, "non-Bash tools are never gated");
+assert.strictEqual(guard.runHook("not json{{{").exit, 0, "unparseable payload fails OPEN");
+assert.strictEqual(guard.runHook(null).exit, 0, "null payload fails OPEN");
+assert.strictEqual(guard.runHook(JSON.stringify({ tool_name: "Bash" })).exit, 0, "missing tool_input fails OPEN");
+
+// ── audit trail: denies + bypasses land in the guard log (5c KPI source) ──
+guard.logGuardEvent({ kind: "bypass", reason: "no tool yet", command: "curl x" });
+const lines = fs.readFileSync(process.env.TOOL_GUARD_LOG, "utf-8").trim().split("\n").map((l) => JSON.parse(l));
+assert.ok(lines.some((l) => l.kind === "deny" && l.rule === "inet-central-api"), "runHook deny is logged");
+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");
+
+// ── 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)");
+const settings = JSON.parse(fs.readFileSync(sPath, "utf-8"));
+const pre = settings.hooks.PreToolUse;
+assert.strictEqual(pre[0].matcher, "Bash", "hook is scoped to the Bash tool");
+assert.ok(/deny-gate-hook/.test(pre[0].hooks[0].command), "hook invokes the CLI hook entry");
+assert.ok(pre[0].hooks[0].command.includes(process.execPath), "hook uses an absolute node path (subprocess PATH independent)");
+assert.ok(pre[0].hooks[0].timeout > 0, "hook carries a timeout so a hung gate fails open");
+// second call with the file read-only: content-compare must skip the write
+fs.chmodSync(sPath, 0o444);
+assert.strictEqual(guard.ensureHookSettings(), sPath, "unchanged settings are not rewritten");
+fs.chmodSync(sPath, 0o644);
+
+// ── credential confinement: agent subprocess env carries NO keyring values ──
+fs.writeFileSync(process.env.KEYRING_FILE, JSON.stringify({ confined_secret: "must-not-leak" }));
+const { botSubprocessEnv } = require("./core/config");
+const env = botSubprocessEnv();
+assert.strictEqual(env.confined_secret, undefined, "keyring values never reach agent/sub-agent shells (5b)");
+assert.ok(env.PATH, "subprocess env still carries PATH");
+
+console.log("tool guard OK");

package/test-tools.js

@@ -1,8 +1,9 @@
 // Reusable tools: a script the agent crystallises must register with a parseable
 // header, live in the git-tracked directory layout (tool + TOOL.md + state.json),
-// run with the keyring merged into its env (preauth), be risk-gated, and be
-// findable by the always-on tool index. Exercises core/tools.js + core/tool-repo.js
-// in an isolated TOOLS_DIR so nothing touches the real ~/.open-claudia/tools.
+// run with ONLY its declared --requires keyring keys injected (least-privilege
+// preauth, 5b), be risk-gated, and be findable by the always-on tool index.
+// Exercises core/tools.js + core/tool-repo.js in an isolated TOOLS_DIR +
+// KEYRING_FILE so nothing touches the real ~/.open-claudia.
 const assert = require("assert");
 const fs = require("fs");
 const os = require("os");
@@ -10,6 +11,7 @@ const path = require("path");
 
 const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tools-test-"));
 process.env.TOOLS_DIR = path.join(tmp, "tools");
+process.env.KEYRING_FILE = path.join(tmp, "keyring.json");
 
 const tools = require("./core/tools");
 const repo = require("./core/tool-repo");
@@ -101,9 +103,23 @@ assert.ok(!missing.includes("api_key"), "a key present in env is not 'missing'")
 assert.ok(missing.includes("api_secret"), "a key absent everywhere is 'missing'");
 delete process.env.api_key;
 
-// ── runEnv returns an env object (keyring merged or graceful fallback) ──
-const env = tools.runEnv();
+// ── runEnv (5b least-privilege): only the tool's declared --requires keys are
+//    injected from the keyring; undeclared keys stay OUT; process.env wins on
+//    conflict; a tool with no requires gets no keyring keys at all ──
+fs.writeFileSync(process.env.KEYRING_FILE, JSON.stringify({
+  api_key: "from-keyring", api_secret: "s3cret-from-keyring", unrelated_key: "never-injected",
+}));
+process.env.api_key = "env-wins";
+const env = tools.runEnv(tools.findTool("hello")); // requires: api_key, api_secret
 assert.ok(env && typeof env === "object" && env.PATH, "runEnv yields an env object carrying PATH");
+assert.strictEqual(env.api_secret, "s3cret-from-keyring", "a declared --requires key is injected from the keyring");
+assert.strictEqual(env.api_key, "env-wins", "process.env wins over the keyring on conflict");
+assert.strictEqual(env.unrelated_key, undefined, "an undeclared keyring key never reaches a tool run");
+const envNoReq = tools.runEnv(tools.findTool("peek")); // no requires declared
+assert.strictEqual(envNoReq.api_secret, undefined, "a tool with no requires gets no keyring keys");
+assert.strictEqual(tools.runEnv().unrelated_key, undefined, "runEnv without a tool injects nothing");
+delete process.env.api_key;
+fs.writeFileSync(process.env.KEYRING_FILE, "{}");
 
 // ── toolNameFromPath recognises legacy flat files and the directory layout's
 //    agent-editable members; state.json and outside paths do not resolve ──