0xray 3.5.0 → 3.5.1

package/AGENTS-consumer.md

@@ -4,7 +4,7 @@
 
 Quick reference for the 0xRay AI orchestration framework (shipped to your project on `npm install 0xray`).
 
-**v3.5.0** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
+**v3.5.1** — 7 MCP servers · 45 skills · 68 codex terms · 4 platform bridges
 
 ## Postinstall (automatic)
 

package/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.5.0**).
+Quick reference for the xray AI orchestration framework (**v3.5.1**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.5.0** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.5.1** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 ## Your AI Power Suit
 

package/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.5.0** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.5.1** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/AGENTS.md

@@ -1,6 +1,6 @@
 # xray Agents
 
-Quick reference for the xray AI orchestration framework (**v3.5.0**).
+Quick reference for the xray AI orchestration framework (**v3.5.1**).
 
 **42 agents** · **45 skills** · **7 consumer MCP servers** · **68 codex terms** · **3,226 tests**
 

package/dist/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [3.5.1] - 2026-06-19
+
+### ✨ Features
+- **Multi-host delegation gates** — `src/nucleus/delegation-gate.ts` SSOT; `evaluatePreToolGate` / `evaluatePostToolSpawn` shared across Grok, Hermes, OpenCode
+- **Hermes** — `pre_tool_call` returns `{"action":"block"}` via bridge `delegation-gate`; `post_tool_call` clears pending on `delegate_task`
+- **OpenCode** — `tool.execute.before` / `after` enforce delegation gate + post-spawn clear
+
+### ✅ Tests
+- `delegation-gate.test.ts`; `verify-delegation-gate-core.mjs`; `verify-hermes-delegation-gate.mjs`; shared `delegation-gate-fixture.mjs`
+- Grok hook-utils deduped — re-exports nucleus SSOT via `delegation-gate-runtime.mjs`
+
+### 📋 Deferred
+- **OpenClaw host veto** — no consumer tool-block API; observability-only until platform supports pre-tool deny
+
+---
+
 ## [3.5.0] - 2026-06-19
 
 ### ✨ Features

package/dist/README.md

@@ -1,6 +1,6 @@
 # xray — MCP-Centric AI Governance OS
 
-**v3.5.0** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
+**v3.5.1** — 42 agents · 45 skills · 7 MCP servers · 68 codex terms · 3,226 tests
 
 ## Your AI Power Suit
 

package/dist/SKILLS.md

@@ -1,6 +1,6 @@
 # 0xray Skills
 
-**v3.5.0** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
+**v3.5.1** — **45 skills** · invoked via `xray-skills` MCP · synced on postinstall
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) across the full software lifecycle. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`), agent `@mentions`, or platform skill directories after postinstall.
 

package/dist/integrations/grok/hooks/grok-hook-utils.js

@@ -6,6 +6,31 @@
 
 import fs from 'fs';
 import path from 'path';
+import {
+  checkPendingDelegationGate,
+  checkSubagentGate,
+  satisfyDelegationsFromToolInput,
+  isSubagentTool,
+  isOrchestrateToolEvent,
+  isReadOnlyTool,
+  isShellTool,
+  getActivePendingDelegations,
+  validateSpawnMatchesTodo,
+  updatePlanTodoStatusInPlace,
+} from '../../hooks/delegation-gate-runtime.mjs';
+
+export {
+  checkPendingDelegationGate,
+  checkSubagentGate,
+  satisfyDelegationsFromToolInput,
+  isSubagentTool,
+  isOrchestrateToolEvent,
+  isReadOnlyTool,
+  isShellTool,
+  getActivePendingDelegations,
+  validateSpawnMatchesTodo,
+  updatePlanTodoStatusInPlace,
+};
 
 export const LEAD_DEV_RULES = [
   'Phased plan + todos; assign best subagent; monitor output',
@@ -116,140 +141,6 @@ export function loadBlockingCodexTerms() {
   }
 }
 
-export function leadDevPlanPath(root = workspaceRoot()) {
-  return path.join(root, '.xray', 'state', 'lead-dev-plan.json');
-}
-
-const DEFAULT_PLAN_TTL_MS = 4 * 60 * 60 * 1000;
-
-export function loadPersistedLeadDevPlan(root = workspaceRoot()) {
-  const planPath = leadDevPlanPath(root);
-  if (!fs.existsSync(planPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(planPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-export function savePersistedLeadDevPlan(plan, root = workspaceRoot()) {
-  const planPath = leadDevPlanPath(root);
-  fs.mkdirSync(path.dirname(planPath), { recursive: true });
-  fs.writeFileSync(planPath, JSON.stringify(plan, null, 2));
-  return planPath;
-}
-
-export function getOutstandingPlanTodos(plan) {
-  if (!plan?.phases) return [];
-  return plan.phases.flatMap((p) => p.todos).filter(
-    (t) => t.status === 'pending' || t.status === 'in_progress',
-  );
-}
-
-export function getNextRequiredPlanTodo(plan) {
-  if (!plan?.phases) return null;
-  for (const phase of plan.phases) {
-    const next = phase.todos.find(
-      (t) => t.status === 'pending' || t.status === 'in_progress',
-    );
-    if (next) return next;
-  }
-  return null;
-}
-
-/** Todo-level persistence: plan stays valid while outstanding todos exist */
-export function hasValidLeadDevPlanForSpawn(root = workspaceRoot()) {
-  const plan = loadPersistedLeadDevPlan(root);
-  if (!plan?.active) return false;
-  const outstanding = getOutstandingPlanTodos(plan);
-  if (outstanding.length > 0) return true;
-  const persistedAt = plan.persistedAt;
-  if (!persistedAt) {
-    try {
-      const stat = fs.statSync(leadDevPlanPath(root));
-      return Date.now() - stat.mtimeMs <= DEFAULT_PLAN_TTL_MS;
-    } catch {
-      return false;
-    }
-  }
-  return Date.now() - new Date(persistedAt).getTime() <= DEFAULT_PLAN_TTL_MS;
-}
-
-export function hasFreshLeadDevPlan(maxAgeMs = DEFAULT_PLAN_TTL_MS) {
-  return hasValidLeadDevPlanForSpawn();
-}
-
-function normalizeSpawnAgent(agent) {
-  const key = String(agent || '').toLowerCase().trim();
-  const aliases = {
-    'bug-triage-specialist': 'bug-triage',
-    'code-reviewer': 'code-review',
-  };
-  return aliases[key] ?? key;
-}
-
-function agentsAlign(expected, actual) {
-  const e = normalizeSpawnAgent(expected);
-  const a = normalizeSpawnAgent(actual);
-  return e === a || e.includes(a) || a.includes(e);
-}
-
-export function validateSpawnMatchesTodo(toolInput, root = workspaceRoot(), expectedTodo = null) {
-  const plan = loadPersistedLeadDevPlan(root);
-  const nextTodo = expectedTodo ?? (plan ? getNextRequiredPlanTodo(plan) : null);
-  if (!nextTodo) return { valid: true };
-
-  const prompt = String(
-    toolInput.prompt || toolInput.description || toolInput.task || '',
-  ).toLowerCase();
-  const subagent = String(toolInput.subagent_type || toolInput.agent || '');
-  const explicitTodo = toolInput.planTodoId || toolInput.delegationId;
-
-  if (explicitTodo && explicitTodo === nextTodo.id) {
-    return { valid: true, expectedTodoId: nextTodo.id, hint: null };
-  }
-  if (prompt.includes(nextTodo.id.toLowerCase())) {
-    return { valid: true, expectedTodoId: nextTodo.id, hint: null };
-  }
-  if (prompt.includes(nextTodo.task.toLowerCase().slice(0, 30))) {
-    return { valid: true, expectedTodoId: nextTodo.id, hint: null };
-  }
-  if (subagent && agentsAlign(nextTodo.subagent, subagent) && prompt.length > 20) {
-    return { valid: true, expectedTodoId: nextTodo.id, hint: null };
-  }
-
-  return {
-    valid: false,
-    expectedTodoId: nextTodo.id,
-    reason: `Spawn must target plan todo ${nextTodo.id} before other work`,
-    gate: 'spawn-todo-persistence',
-    hint: {
-      tool: 'Task',
-      subagent_type: nextTodo.subagent,
-      planTodoId: nextTodo.id,
-      description: `Lead-dev todo ${nextTodo.id}: ${nextTodo.task}. Include plan todo id in Task prompt.`,
-    },
-  };
-}
-
-export function updatePlanTodoStatusInPlace(todoId, status, root = workspaceRoot()) {
-  const plan = loadPersistedLeadDevPlan(root);
-  if (!plan) return false;
-  let updated = false;
-  for (const phase of plan.phases) {
-    for (const todo of phase.todos) {
-      if (todo.id === todoId) {
-        todo.status = status;
-        updated = true;
-      }
-    }
-  }
-  if (updated) {
-    fs.writeFileSync(leadDevPlanPath(root), JSON.stringify(plan, null, 2));
-  }
-  return updated;
-}
-
 export function extractToolContext(event) {
   const toolName = event.toolName || process.env.TOOL_NAME || 'unknown';
   const toolInput = event.toolInput ?? {};
@@ -290,41 +181,6 @@ export function checkSurfaceArea(paths, root = workspaceRoot()) {
   return null;
 }
 
-export function checkSubagentGate(toolName, features, root = workspaceRoot(), sessionId = null, toolInput = {}) {
-  if (!features.lead_dev_mode) return null;
-  if (!isSubagentTool(toolName)) return null;
-
-  if (!hasValidLeadDevPlanForSpawn(root)) {
-    return {
-      reason:
-        'Codex 59/67: call xray-orchestrator analyze-complexity first — ' +
-        'writes .xray/state/lead-dev-plan.json required before spawn_subagent',
-      gate: 'spawn-plan-missing',
-    };
-  }
-
-  if (features.auto_chain_delegations === false) return null;
-
-  const pending = getActivePendingDelegations(root, sessionId);
-  const expectedTodo =
-    pending[0]?.planTodoId && loadPersistedLeadDevPlan(root)
-      ? loadPersistedLeadDevPlan(root).phases
-          .flatMap((p) => p.todos)
-          .find((t) => t.id === pending[0].planTodoId) ?? null
-      : null;
-
-  const validation = validateSpawnMatchesTodo(toolInput, root, expectedTodo);
-  if (!validation.valid) {
-    return {
-      reason: validation.reason,
-      gate: validation.gate,
-      hint: validation.hint,
-    };
-  }
-
-  return null;
-}
-
 export function checkFullTestSuite(cmd, features) {
   if (!features.per_suite_test_triage) return null;
   const cmdText = cmd.toLowerCase();
@@ -343,10 +199,6 @@ export function isWriteTool(toolName) {
   return WRITE_TOOLS.has(toolName) || /write|edit|replace/i.test(toolName);
 }
 
-export function isShellTool(toolName) {
-  return /terminal|bash|shell|run_terminal/i.test(toolName);
-}
-
 export async function readStdinJson() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -408,50 +260,6 @@ export function ensureSessionBoot(root = workspaceRoot(), source = '0xray/grok-b
   return writeSessionBoot(root, buildSessionBootPayload(root, source));
 }
 
-const READ_TOOLS = new Set([
-  'read_file',
-  'Read',
-  'grep',
-  'Grep',
-  'glob',
-  'Glob',
-  'list_dir',
-  'ListDir',
-  'web_search',
-  'WebSearch',
-  'codebase_search',
-  'SemanticSearch',
-]);
-
-const ORCHESTRATOR_CONSULT_TOOLS = new Set([
-  'analyze-complexity',
-  'analyze_complexity',
-  'get-orchestration-status',
-  'get_orchestration_status',
-  'orchestrate-task',
-  'orchestrate_task',
-]);
-
-export function pendingDelegationsPath(root = workspaceRoot()) {
-  return path.join(root, '.xray', 'state', 'pending-delegations.json');
-}
-
-export function loadPendingDelegationsState(root = workspaceRoot()) {
-  const filePath = pendingDelegationsPath(root);
-  if (!fs.existsSync(filePath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-export function savePendingDelegationsState(state, root = workspaceRoot()) {
-  const filePath = pendingDelegationsPath(root);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
-}
-
 export function resolveSessionId(event) {
   return (
     event.sessionId ||
@@ -460,176 +268,15 @@ export function resolveSessionId(event) {
   );
 }
 
-export function isPendingStateActive(state, sessionId) {
-  if (!state || !sessionId || state.sessionId !== sessionId) return false;
-  const age = Date.now() - new Date(state.createdAt).getTime();
-  if (age > (state.ttlMs ?? 4 * 60 * 60 * 1000)) return false;
-  return state.delegations?.some((d) => d.status === 'pending');
-}
-
-export function getActivePendingDelegations(root, sessionId) {
-  const state = loadPendingDelegationsState(root);
-  if (!isPendingStateActive(state, sessionId)) return [];
-  return state.delegations.filter((d) => d.status === 'pending');
-}
-
 export function clearPendingDelegationsForSessionChange(newSessionId, root = workspaceRoot()) {
-  const state = loadPendingDelegationsState(root);
-  if (!state) return false;
-  if (newSessionId && state.sessionId === newSessionId) return false;
+  const filePath = path.join(root, '.xray', 'state', 'pending-delegations.json');
+  if (!fs.existsSync(filePath)) return false;
   try {
-    fs.unlinkSync(pendingDelegationsPath(root));
+    const state = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (newSessionId && state.sessionId === newSessionId) return false;
+    fs.unlinkSync(filePath);
     return true;
   } catch {
     return false;
   }
-}
-
-function isFocusedTestCommand(cmd) {
-  const cmdText = (cmd || '').toLowerCase();
-  return (
-    /\b(npm\s+(run\s+)?test|vitest\s+run|pnpm\s+test|yarn\s+test)\b/.test(cmdText) &&
-    (/--\s+\S+\.test/.test(cmdText) || /vitest\s+run\s+\S+\.test/.test(cmdText))
-  );
-}
-
-function isReadOnlyTool(toolName) {
-  return READ_TOOLS.has(toolName) || /^(read|grep|glob|list)/i.test(toolName);
-}
-
-export function isSubagentTool(toolName) {
-  return SUBAGENT_TOOLS.has(toolName) || /^task$/i.test(toolName) || toolName === 'spawn_subagent';
-}
-
-function extractMcpToolName(toolInput) {
-  const candidates = [
-    toolInput.toolName,
-    toolInput.tool,
-    toolInput.name,
-    toolInput.mcpToolName,
-  ];
-  for (const c of candidates) {
-    if (c) return String(c);
-  }
-  const server = String(toolInput.server || toolInput.mcpServer || '');
-  const args = toolInput.arguments ?? toolInput.args ?? {};
-  if (args.toolName) return String(args.toolName);
-  if (server.includes('orchestrator') && args.name) return String(args.name);
-  return '';
-}
-
-function isOrchestratorConsultMcp(toolName, toolInput) {
-  if (!/mcp|CallMcpTool/i.test(toolName)) return false;
-  const inner = extractMcpToolName(toolInput).toLowerCase();
-  if (!inner) return false;
-  for (const t of ORCHESTRATOR_CONSULT_TOOLS) {
-    if (inner.includes(t) || inner.includes(t.replace(/-/g, '_'))) return true;
-  }
-  return false;
-}
-
-export function isOrchestrateToolEvent(toolName, toolInput = {}) {
-  const inner = extractMcpToolName(toolInput).toLowerCase();
-  if (/orchestrate[-_]?task/.test(inner)) return true;
-  const blob = JSON.stringify(toolInput).toLowerCase();
-  return /orchestrate[-_]?task/.test(blob);
-}
-
-export function satisfyDelegationsFromToolInput(toolInput, root = workspaceRoot()) {
-  const state = loadPendingDelegationsState(root);
-  if (!state) return { satisfied: [], clearedAll: false };
-
-  const prompt = String(
-    toolInput.prompt || toolInput.description || toolInput.task || '',
-  ).toLowerCase();
-  const subagent = String(toolInput.subagent_type || toolInput.agent || '').toLowerCase();
-  const delegationId = toolInput.delegationId || toolInput.delegation_id;
-
-  const pending = state.delegations.filter((d) => d.status === 'pending');
-  if (pending.length === 0) return { satisfied: [], clearedAll: false };
-
-  let matches = [];
-  if (delegationId) {
-    matches = pending.filter((d) => d.id === delegationId);
-  } else {
-    for (const d of pending) {
-      if (d.planTodoId && prompt.includes(d.planTodoId.toLowerCase())) {
-        matches.push(d);
-        break;
-      }
-      if (prompt.includes(d.taskId.toLowerCase())) {
-        matches.push(d);
-        break;
-      }
-      if (subagent && d.agent.toLowerCase().includes(subagent)) {
-        matches.push(d);
-        break;
-      }
-    }
-  }
-
-  if (matches.length === 0 && pending.length === 1) {
-    const only = pending[0];
-    const hint = (only.spawnHint?.description || '').toLowerCase();
-    if (prompt && hint && prompt.includes(hint.slice(0, 30))) {
-      matches = [only];
-    }
-  }
-
-  if (matches.length === 0) return { satisfied: [], clearedAll: false };
-
-  const now = new Date().toISOString();
-  const ids = new Set(matches.map((m) => m.id));
-  for (const d of state.delegations) {
-    if (ids.has(d.id) && d.status === 'pending') {
-      d.status = 'satisfied';
-      d.satisfiedAt = now;
-    }
-  }
-  savePendingDelegationsState(state, root);
-  for (const m of matches) {
-    if (m.planTodoId) {
-      updatePlanTodoStatusInPlace(m.planTodoId, 'in_progress', root);
-    }
-  }
-  const clearedAll = !state.delegations.some((d) => d.status === 'pending');
-  return { satisfied: matches, clearedAll };
-}
-
-/**
- * Surgical gate: block writes and unrelated work while pending delegations exist.
- * Allows read-only tools, orchestrator consult MCP, focused test shell, and Task/spawn.
- */
-export function checkPendingDelegationGate(toolName, toolInput, features, root, sessionId) {
-  if (!features.lead_dev_mode || features.auto_chain_delegations === false) return null;
-  if (!sessionId) return null;
-
-  const pending = getActivePendingDelegations(root, sessionId);
-  if (pending.length === 0) return null;
-
-  if (isSubagentTool(toolName)) return null;
-
-  if (isReadOnlyTool(toolName)) return null;
-
-  if (isOrchestratorConsultMcp(toolName, toolInput)) return null;
-
-  if (isShellTool(toolName)) {
-    const cmd = String(toolInput.command || '');
-    if (isFocusedTestCommand(cmd)) return null;
-  }
-
-  const primary = pending[0];
-  return {
-    reason: 'Pending implementation delegation — spawn host Task before other work',
-    gate: 'auto-chain-pending',
-    hint: primary.spawnHint ?? {
-      tool: 'Task',
-      subagent_type: primary.agent,
-      description: primary.taskDescription,
-      planTodoId: primary.planTodoId,
-      delegationId: primary.id,
-    },
-    pendingCount: pending.length,
-    delegationId: primary.id,
-  };
 }

package/dist/integrations/hermes-agent/__init__.py

@@ -187,17 +187,52 @@ def _is_xray_mcp(tool_name: str) -> bool:
     return tool_name.startswith("mcp_xray_")
 
 
+def _delegation_gate_block(tool_name: str, args: dict, task_id: str, **kwargs):
+    """3.5.1 multi-host parity — block via nucleus delegation-gate SSOT."""
+    session_id = (
+        kwargs.get("session_id")
+        or kwargs.get("sessionId")
+        or task_id
+        or ""
+    )
+    bridge_result = _call_bridge(
+        {
+            "command": "delegation-gate",
+            "phase": "pre",
+            "tool": tool_name,
+            "args": args or {},
+            "sessionId": session_id,
+            "host": "hermes",
+        },
+        timeout=10,
+    )
+    if bridge_result.get("allow") is False:
+        reason = bridge_result.get("reason", "Delegation gate blocked this tool")
+        gate = bridge_result.get("gate", "delegation-gate")
+        _log_to_file(
+            "activity.log",
+            f"[delegation-gate] deny tool={tool_name} gate={gate} reason={reason}",
+        )
+        return {"action": "block", "message": reason}
+    return None
+
+
 def _on_pre_tool_call(tool_name: str, args: dict, task_id: str, **kwargs):
     """Fires before ANY tool executes.
 
     Pipeline:
       1. Track stats
       2. Log tool-start event to disk
-      3. For code-producing tools: run quality gate + pre-processors via bridge
-      4. For non-code tools: nudge if Xray alternative exists
+      3. Delegation gate (pending + spawn todo) — may block tool
+      4. For code-producing tools: run quality gate + pre-processors via bridge
+      5. For non-code tools: nudge if Xray alternative exists
     """
     _session_stats["total_tool_calls"] += 1
 
+    block = _delegation_gate_block(tool_name, args, task_id, **kwargs)
+    if block:
+        return block
+
     # Log start event
     _log_tool_event("start", tool_name, args)
 
@@ -329,9 +364,21 @@ def _on_post_tool_call(tool_name: str, args: dict, result, task_id: str, **kwarg
     # Record outcome for the inference feedback loop
     _record_tool_outcome(tool_name, args or {}, error is None)
 
-    # delegate_task: validate all files the subagent changed
+    # delegate_task: clear pending delegations + validate subagent changes
     if tool_name == "delegate_task":
         tid = kwargs.get("task_id", "") or args.get("task_id", "") or task_id
+        session_id = kwargs.get("session_id") or kwargs.get("sessionId") or tid
+        _call_bridge(
+            {
+                "command": "delegation-gate",
+                "phase": "post",
+                "tool": tool_name,
+                "args": args or {},
+                "sessionId": session_id,
+                "host": "hermes",
+            },
+            timeout=10,
+        )
         if tid:
             _validate_subagent_changes(tid)
         return