role-os 2.7.0 → 2.8.0

package/src/hooks.mjs

@@ -21,6 +21,8 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { schemaFloor, contractFloor } from "./specialist/conformance-consult.mjs";
+import { capabilityGate } from "./specialist/capability-gate.mjs";
 
 // ── Hook script generators ────────────────────────────────────────────────────
 
@@ -188,14 +190,57 @@ export function onPromptSubmit(input) {
   return {};
 }
 
+const TOOL_CONTRACTS_FILE = ".claude/role-os/tool-contracts.json";
+
+/**
+ * Load the Tool-Call Conformance contract catalog from the repo (the rollout's per-tool knowledge base):
+ * { "<tool_name>": { contract, params, constraints, state_struct? } }. Fail-safe — a missing or malformed
+ * file yields {} (conformance simply does not run), so this never breaks a tool call.
+ * @param {string} cwd
+ * @returns {Record<string, object>}
+ */
+export function loadToolContracts(cwd) {
+  try {
+    const p = join(cwd, TOOL_CONTRACTS_FILE);
+    if (!existsSync(p)) return {};
+    return JSON.parse(readFileSync(p, "utf-8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Deterministic conformance ADVISORY for a tool call — wedge #1's live seam. Runs the schema floor
+ * (L1-L3) + the computable contract floor (L4) against the catalogued tool. Returns an advisory string
+ * only when the floor PROVES a violation; otherwise null. Never throws, never denies — the watcher is
+ * advisory + fail-open by design (a false "conformant" is the costly error, never a blocked good call).
+ */
+export function conformanceAdvisory(cwd, toolName, toolInput, opts = {}) {
+  try {
+    const catalog = opts.toolContracts || loadToolContracts(cwd);
+    const entry = catalog && catalog[toolName];
+    if (!entry) return null;
+    const tool = { name: toolName, contract: entry.contract, params: entry.params || [], constraints: entry.constraints || [] };
+    const call = toolInput && typeof toolInput === "object" ? toolInput : {};
+    const v = [...schemaFloor(tool, call).violations, ...contractFloor(tool, call, entry.state_struct || null).violations];
+    if (!v.length) return null;
+    return `Tool-Call Conformance (advisory): the "${toolName}" call appears NONCONFORMANT — ${v.join("; ")}. The deterministic floor proved this; review before relying on the result.`;
+  } catch {
+    return null; // a hook must never break a tool call
+  }
+}
+
 /**
  * PreToolUse hook logic.
- * Checks tool usage against active role envelope.
+ * Records tool usage, flags write tools without a route card, and (wedge #1) attaches an ADVISORY
+ * Tool-Call Conformance verdict from the deterministic floor when the tool is catalogued. Advisory only
+ * — it never denies a call.
  *
  * @param {object} input - { tool_name, tool_input, session_id, cwd }
+ * @param {object} [opts] - { toolContracts } to inject a catalog (tests); defaults to loadToolContracts(cwd)
  * @returns {{ allow?: boolean, deny?: { reason: string }, addContext?: string }}
  */
-export function onPreToolUse(input) {
+export function onPreToolUse(input, opts = {}) {
   const cwd = input.cwd || process.cwd();
   const state = getSessionState(cwd);
   const toolName = input.tool_name || "";
@@ -206,23 +251,33 @@ export function onPreToolUse(input) {
     saveSessionState(cwd, state);
   }
 
+  // Capability gate (opt-in via ROLEOS_CAPABILITY_GATE, fail-closed): an irreversible action without
+  // a granted capability is DENIED — bounds what a wrong verdict (honest or adversarial) can DO
+  // (POLA / CaMeL). Default OFF => pure no-op. Distinct from the advisory conformance floor below.
+  const cap = capabilityGate(cwd, toolName, input.tool_input, opts);
+  if (cap.denied) return { deny: { reason: cap.reason } };
+
+  const notes = [];
+
   // Advisory: flag write tools without route card after substantial prompts
   const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
   if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
-    return {
-      addContext: `Write tool "${toolName}" used without a route card. If this is substantial work, consider routing first.`,
-    };
+    notes.push(`Write tool "${toolName}" used without a route card. If this is substantial work, consider routing first.`);
   }
 
+  // Wedge #1: deterministic conformance floor (advisory, fail-open) on the proposed call
+  const conf = conformanceAdvisory(cwd, toolName, input.tool_input, opts);
+  if (conf) notes.push(conf);
+
   // If a role is active, read-only tools are always fine
   if (state.activeRole && state.activePack) {
     const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
     if (readOnlyTools.includes(toolName)) {
-      return { allow: true };
+      return notes.length ? { allow: true, addContext: notes.join(" ") } : { allow: true };
     }
   }
 
-  return {};
+  return notes.length ? { addContext: notes.join(" ") } : {};
 }
 
 /**
@@ -343,10 +398,15 @@ writeFileSync(join(stateDir, "session-state.json"), JSON.stringify(state, null,
 
 const hasRoleOs = existsSync(join(cwd, ".claude", "agents"));
 if (hasRoleOs) {
+  // SessionStart wire protocol (current Claude Code): hookSpecificOutput.additionalContext + exit 0.
   console.log(JSON.stringify({
-    addContext: "Role OS is active. For non-trivial tasks, run /roleos-route first.",
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: "Role OS is active. For non-trivial tasks, run /roleos-route first.",
+    },
   }));
 }
+process.exit(0);
 `;
 }
 
@@ -376,16 +436,21 @@ if (isSubstantial) state.substantivePrompts = (state.substantivePrompts || 0) +
 writeFileSync(statePath, JSON.stringify(state, null, 2));
 
 if (isSubstantial && (state.substantivePrompts || 0) >= 2 && !state.routeCardPresent) {
+  // UserPromptSubmit wire protocol (current Claude Code): hookSpecificOutput.additionalContext + exit 0.
   console.log(JSON.stringify({
-    addContext: "No Role OS route card yet. Consider /roleos-route to classify this task.",
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: "No Role OS route card yet. Consider /roleos-route to classify this task.",
+    },
   }));
 }
+process.exit(0);
 `;
 }
 
 function generatePreToolUseScript() {
   return `#!/usr/bin/env node
-// Role OS PreToolUse hook — enforce role-specific tool law
+// Role OS PreToolUse hook — enforce role-specific tool law + Tool-Call Conformance floor (advisory)
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
@@ -405,13 +470,48 @@ if (!state.toolsUsed.includes(toolName)) {
   writeFileSync(statePath, JSON.stringify(state, null, 2));
 }
 
-// Advisory: flag write tools without route card
+const notes = [];
 const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
 if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
+  notes.push(\`Write tool "\${toolName}" used without route card. Consider /roleos-route.\`);
+}
+
+// Tool-Call Conformance floor (advisory, deterministic). Best-effort: runs only when this tool has a
+// .claude/role-os/tool-contracts.json catalog entry AND the role-os library is resolvable. ANY failure
+// is a silent no-op — a hook must never break a tool call; the watcher is advisory + fail-open.
+try {
+  const catPath = join(cwd, ".claude", "role-os", "tool-contracts.json");
+  if (existsSync(catPath)) {
+    const catalog = JSON.parse(readFileSync(catPath, "utf-8"));
+    const entry = catalog && catalog[toolName];
+    if (entry) {
+      const { schemaFloor, contractFloor } = await import("role-os/src/specialist/conformance-consult.mjs");
+      const tool = { name: toolName, contract: entry.contract, params: entry.params || [], constraints: entry.constraints || [] };
+      const call = (input.tool_input && typeof input.tool_input === "object") ? input.tool_input : {};
+      const v = [...schemaFloor(tool, call).violations, ...contractFloor(tool, call, entry.state_struct || null).violations];
+      if (v.length) notes.push(\`Tool-Call Conformance (advisory): "\${toolName}" appears NONCONFORMANT — \${v.join("; ")}.\`);
+    }
+  }
+} catch { /* role-os not resolvable here, or internal error -> no-op (never block a tool call) */ }
+
+// Capability gate (opt-in via ROLEOS_CAPABILITY_GATE, FAIL-CLOSED): an irreversible action without a
+// granted capability is DENIED (exit 2 blocks). Default OFF => no-op. Bounds what a wrong verdict can
+// DO (POLA / CaMeL). Best-effort: if role-os is not resolvable here a hook-resolution failure must not
+// itself block a call; the in-process onPreToolUse path still enforces it where role-os is resolvable.
+try {
+  const { capabilityGate } = await import("role-os/src/specialist/capability-gate.mjs");
+  const cap = capabilityGate(cwd, toolName, input.tool_input || {});
+  if (cap.denied) { process.stderr.write(cap.reason + "\\n"); process.exit(2); }
+} catch { /* role-os not resolvable / internal error -> no-op (in-process path enforces) */ }
+
+// PreToolUse wire protocol (current Claude Code): inject advisory context via
+// hookSpecificOutput.additionalContext + exit 0. A bare { addContext } is IGNORED; exit 2 would BLOCK.
+if (notes.length) {
   console.log(JSON.stringify({
-    addContext: \`Write tool "\${toolName}" used without route card. Consider /roleos-route.\`,
+    hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: notes.join(" ") },
   }));
 }
+process.exit(0);
 `;
 }
 
@@ -431,10 +531,15 @@ if (existsSync(statePath)) {
 }
 
 if (state.activeRole) {
+  // SubagentStart wire protocol (current Claude Code): hookSpecificOutput.additionalContext + exit 0.
   console.log(JSON.stringify({
-    addContext: \`Role OS active. Role: \${state.activeRole}. Pack: \${state.activePack || "free routing"}. Follow role contract.\`,
+    hookSpecificOutput: {
+      hookEventName: "SubagentStart",
+      additionalContext: \`Role OS active. Role: \${state.activeRole}. Pack: \${state.activePack || "free routing"}. Follow role contract.\`,
+    },
   }));
 }
+process.exit(0);
 `;
 }
 
@@ -461,9 +566,15 @@ if (!state.routeCardPresent) warnings.push("No route card produced.");
 if (!state.outcomeRecorded) warnings.push("No outcome artifact recorded.");
 
 if (warnings.length > 0) {
+  // Stop wire protocol (current Claude Code): advisory context via hookSpecificOutput.additionalContext
+  // + exit 0 lets the session end with a note. { decision: "block" } would PREVENT stopping (not wanted here).
   console.log(JSON.stringify({
-    addContext: \`Role OS audit: \${warnings.join(" ")} Consider documenting the outcome.\`,
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: \`Role OS audit: \${warnings.join(" ")} Consider documenting the outcome.\`,
+    },
   }));
 }
+process.exit(0);
 `;
 }

package/src/specialist/capability-gate.mjs

@@ -0,0 +1,124 @@
+/**
+ * Capability gate — deterministic least-privilege (POLA) on IRREVERSIBLE tool calls. The one
+ * security primitive worth owning internally (memory: oversight-specialist-mint-strategy.md,
+ * 2026-06-08 posture): it bounds what any agent action can DO, so a WRONG verdict — an honest crew
+ * mistake OR (later) an adversarial flip — can never trigger an unauthorized irreversible action.
+ * The PREVENTIVE complement to NAMED_COMPENSATORS (which undoes an irreversible action; this stops
+ * the unauthorized one before it happens). Same action set, two halves.
+ *
+ * Grounded in the object-capability model / POLA and CaMeL (Debenedetti et al. 2025,
+ * arXiv:2503.18813: control/data-flow separation + capabilities, model UNMODIFIED). Deterministic,
+ * NO model — least-privilege, not an arms race.
+ *
+ * Safe by construction:
+ *   - OPT-IN, default OFF (ROLEOS_CAPABILITY_GATE). Disabled => never denies (pure no-op), so it can
+ *     never disrupt an existing flow until the director turns it on.
+ *   - Scoped to a SMALL gated set (the NAMED_COMPENSATORS irreversible-action list). Every non-gated
+ *     tool and every read-only tool is untouched.
+ *   - FAIL-CLOSED for the gated set: a gated action with NO matching capability grant is denied, with
+ *     a reason telling the director how to grant it. (Distinct from the conformance floor, which is
+ *     advisory / fail-open — a missed nonconformance is cheap; an unauthorized irreversible action is
+ *     not, so its asymmetry runs the other way.)
+ *
+ * The grant manifest (`.claude/role-os/capabilities.json`, director-authored) maps an action id to a
+ * grant, e.g.: { "npm:publish": { "granted": true, "scope": "@mcptoolshop/roll", "expires": "2026-07-01" } }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CAPABILITIES_FILE = ".claude/role-os/capabilities.json";
+
+/** Opt-in flag, mirroring conformanceConsultEnabled(). Default OFF. */
+export function capabilityGateEnabled() {
+  const v = process.env.ROLEOS_CAPABILITY_GATE;
+  return v === "1" || v === "true";
+}
+
+const _bash = (re) => (toolName, call) =>
+  toolName === "Bash" && typeof call?.command === "string" && re.test(call.command);
+
+/**
+ * The GATED SET — the irreversible / world-touching actions from the NAMED_COMPENSATORS standard.
+ * Each entry: { id, label, test(toolName, call) -> boolean }. Detection is deterministic + pattern-
+ * based and errs toward FLAGGING (a benign match just needs a one-line grant), never toward missing
+ * an irreversible action.
+ */
+export const GATED_ACTIONS = [
+  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\s+publish\b/) },
+  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\s+upload\b|\buv\s+publish\b/) },
+  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\s+release\s+create\b/) },
+  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\s+pr\s+create\b/) },
+  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\s+repo\s+(?:edit|delete)\b/) },
+  { id: "git:push", label: "git push", test: _bash(/\bgit\s+push\b/) },
+  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\s+deploy\b/) },
+];
+
+/** Read the director's capability manifest, or {} if absent/malformed (=> nothing granted). */
+export function loadCapabilities(cwd) {
+  try {
+    const p = join(cwd, CAPABILITIES_FILE);
+    if (!existsSync(p)) return {};
+    const data = JSON.parse(readFileSync(p, "utf-8"));
+    return data && typeof data === "object" ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Is `actionId` granted (granted:true and not expired) in the manifest? */
+function _granted(manifest, actionId, now) {
+  const g = manifest && manifest[actionId];
+  if (!g || typeof g !== "object" || g.granted !== true) return false;
+  if (typeof g.expires === "string") {
+    const t = Date.parse(g.expires);
+    if (!Number.isNaN(t) && t < now) return false; // grant expired
+  }
+  return true;
+}
+
+/**
+ * Capability gate for a proposed tool call.
+ *
+ * OPT-IN: when disabled it ALWAYS returns { denied:false } (pure no-op). When enabled, a gated
+ * irreversible action is allowed ONLY if the manifest grants its capability id; otherwise it is
+ * DENIED (fail-closed) with a reason telling the director how to grant it.
+ *
+ * @param {string} cwd
+ * @param {string} toolName
+ * @param {object} toolInput
+ * @param {object} [opts] - { force } run the gate regardless of the env flag (tests);
+ *   { capabilities } inject a manifest (tests); { now } epoch ms for expiry (tests)
+ * @returns {{ denied: boolean, action?: string, reason?: string }}
+ */
+export function capabilityGate(cwd, toolName, toolInput, opts = {}) {
+  if (!opts.force && !capabilityGateEnabled()) return { denied: false };
+  let action;
+  try {
+    const call = toolInput && typeof toolInput === "object" ? toolInput : {};
+    action = GATED_ACTIONS.find((a) => a.test(toolName, call));
+    if (!action) return { denied: false }; // not an irreversible action -> allow
+    const manifest = opts.capabilities || loadCapabilities(cwd);
+    const now = typeof opts.now === "number" ? opts.now : Date.now();
+    if (_granted(manifest, action.id, now)) return { denied: false };
+    return {
+      denied: true,
+      action: action.id,
+      reason:
+        `Capability gate: "${action.label}" is an irreversible action requiring an explicit grant. ` +
+        `No capability "${action.id}" is granted in ${CAPABILITIES_FILE}. To authorize it, the ` +
+        `director adds {"${action.id}": {"granted": true}} (optionally with "scope"/"expires").`,
+    };
+  } catch {
+    // A gate that errors must not silently allow an irreversible action: if a gated action matched
+    // but the grant cannot be evaluated, fail CLOSED (deny). If nothing matched, allow.
+    if (action) {
+      return {
+        denied: true,
+        action: action.id,
+        reason: `Capability gate errored evaluating the grant for "${action.id}"; failing closed on an irreversible action.`,
+      };
+    }
+    return { denied: false };
+  }
+}