role-os 2.7.1 → 2.9.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);
 `;
 }