0xray 3.4.10 → 3.5.1

package/scripts/mjs/verify-delegation-gate-core.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Shared 4/4 delegation gate fixture against nucleus SSOT (any host adapter).
+ * Usage: node scripts/mjs/verify-delegation-gate-core.mjs [--host=grok|hermes|opencode]
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  FIXTURE_SESSION_ID,
+  seedDelegationGateFixture,
+  seedSpawnTodoPlan,
+} from './delegation-gate-fixture.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '../..');
+
+const hostArg = process.argv.find((a) => a.startsWith('--host='));
+const host = hostArg?.split('=')[1] || 'generic';
+
+const { evaluatePreToolGate, loadDelegationGateFeatures } = await import(
+  join(packageRoot, 'dist/integrations/hooks/delegation-gate-runtime.mjs')
+);
+
+const WRITE_TOOL =
+  host === 'hermes' ? 'write_file' : host === 'opencode' ? 'write' : 'search_replace';
+const READ_TOOL = host === 'hermes' ? 'read_file' : 'read_file';
+const SPAWN_TOOL =
+  host === 'hermes' ? 'delegate_task' : host === 'opencode' ? 'task' : 'Task';
+
+let failed = 0;
+function pass(n) {
+  console.log(`✅ ${n}`);
+}
+function fail(n, d = '') {
+  failed++;
+  console.error(`❌ ${n}${d ? ` — ${d}` : ''}`);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'xray-gate-core-'));
+seedDelegationGateFixture(tmp);
+
+const ctx = () => ({
+  projectRoot: tmp,
+  sessionId: FIXTURE_SESSION_ID,
+  features: loadDelegationGateFeatures(tmp),
+  host,
+});
+
+try {
+  const deny = evaluatePreToolGate(
+    WRITE_TOOL,
+    host === 'opencode'
+      ? { filePath: 'src/a.ts', content: 'x' }
+      : { path: 'src/a.ts', new_string: 'x', content: 'x' },
+    ctx(),
+  );
+  if (!deny.allow && deny.gate === 'auto-chain-pending') {
+    pass('denies write while pending');
+  } else {
+    fail('write deny', JSON.stringify(deny));
+  }
+
+  const allowRead = evaluatePreToolGate(READ_TOOL, { path: 'src/a.ts' }, ctx());
+  if (allowRead.allow) pass('allows read while pending');
+  else fail('read allow', JSON.stringify(allowRead));
+
+  const allowSpawn = evaluatePreToolGate(
+    SPAWN_TOOL,
+    { prompt: 'plan todo 2.1 swap deps', subagent_type: 'backend-engineer' },
+    ctx(),
+  );
+  if (allowSpawn.allow) pass('allows spawn while pending');
+  else fail('spawn allow', JSON.stringify(allowSpawn));
+
+  seedSpawnTodoPlan(tmp);
+  const denyWrongTodo = evaluatePreToolGate(
+    SPAWN_TOOL,
+    { prompt: 'explore only', subagent_type: 'explore' },
+    ctx(),
+  );
+  if (!denyWrongTodo.allow && denyWrongTodo.gate === 'spawn-todo-persistence') {
+    pass('denies spawn skipping required plan todo');
+  } else {
+    fail('spawn todo persistence', JSON.stringify(denyWrongTodo));
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+const label = host === 'generic' ? 'core' : host;
+console.log(
+  '\n' +
+    (failed === 0
+      ? `🎉 Delegation gate verify passed (4/4) [${label}].`
+      : `⚠️  ${failed} gate check(s) failed [${label}].`),
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/mjs/verify-grok-delegation-gate.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Hook fixture verify — PreToolUse delegation gate with seeded pending-delegations.json.
+ * Run: node scripts/mjs/verify-grok-delegation-gate.mjs
+ */
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  FIXTURE_SESSION_ID,
+  seedDelegationGateFixture,
+  seedSpawnTodoPlan,
+} from './delegation-gate-fixture.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '../..');
+const preToolHook = join(packageRoot, 'dist/integrations/grok/hooks/pre-tool-use.js');
+
+let failed = 0;
+function pass(n) {
+  console.log(`✅ ${n}`);
+}
+function fail(n, d = '') {
+  failed++;
+  console.error(`❌ ${n}${d ? ` — ${d}` : ''}`);
+}
+
+function runHook(fixture, env = {}) {
+  const payload = JSON.stringify(fixture);
+  const out = execSync(`printf '%s' '${payload.replace(/'/g, "'\\''")}' | node "${preToolHook}"`, {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(out.trim());
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'xray-gate-verify-'));
+seedDelegationGateFixture(tmp);
+
+const baseEnv = {
+  GROK_WORKSPACE_ROOT: tmp,
+  GROK_SESSION_ID: FIXTURE_SESSION_ID,
+};
+
+try {
+  const deny = runHook(
+    {
+      toolName: 'search_replace',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { path: 'src/a.ts', new_string: 'x' },
+    },
+    baseEnv,
+  );
+  if (deny.decision === 'deny' && deny.gate === 'auto-chain-pending') {
+    pass('PreToolUse denies write while pending');
+  } else {
+    fail('write deny', JSON.stringify(deny));
+  }
+
+  const allowRead = runHook(
+    {
+      toolName: 'read_file',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { path: 'src/a.ts' },
+    },
+    baseEnv,
+  );
+  if (allowRead.decision === 'allow') pass('PreToolUse allows read while pending');
+  else fail('read allow', JSON.stringify(allowRead));
+
+  const allowTask = runHook(
+    {
+      toolName: 'Task',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { prompt: 'plan todo 2.1 swap deps', subagent_type: 'backend-engineer' },
+    },
+    baseEnv,
+  );
+  if (allowTask.decision === 'allow') pass('PreToolUse allows Task while pending');
+  else fail('Task allow', JSON.stringify(allowTask));
+
+  seedSpawnTodoPlan(tmp);
+
+  const denyWrongTodo = runHook(
+    {
+      toolName: 'Task',
+      workspaceRoot: tmp,
+      sessionId: 'verify-gate',
+      toolInput: { prompt: 'explore only', subagent_type: 'explore' },
+    },
+    baseEnv,
+  );
+  if (denyWrongTodo.decision === 'deny' && denyWrongTodo.gate === 'spawn-todo-persistence') {
+    pass('PreToolUse denies spawn skipping required plan todo');
+  } else {
+    fail('spawn todo persistence', JSON.stringify(denyWrongTodo));
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(
+  '\n' +
+    (failed === 0
+      ? '🎉 Grok delegation gate verify passed (4/4).'
+      : `⚠️  ${failed} gate check(s) failed.`),
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/mjs/verify-hermes-delegation-gate.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Hermes bridge delegation gate fixture (4/4) — uses bridge delegation-gate command.
+ */
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  FIXTURE_SESSION_ID,
+  seedDelegationGateFixture,
+  seedSpawnTodoPlan,
+} from './delegation-gate-fixture.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '../..');
+const bridge = join(packageRoot, 'dist/integrations/hermes-agent/bridge.mjs');
+
+let failed = 0;
+function pass(n) {
+  console.log(`✅ ${n}`);
+}
+function fail(n, d = '') {
+  failed++;
+  console.error(`❌ ${n}${d ? ` — ${d}` : ''}`);
+}
+
+function runBridge(payload, cwd) {
+  const json = JSON.stringify(payload).replace(/'/g, "'\\''");
+  const out = execSync(`node "${bridge}" delegation-gate --cwd "${cwd}" '${json}'`, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, XRAY_ROOT: cwd },
+  });
+  return JSON.parse(out.trim());
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'xray-hermes-gate-'));
+seedDelegationGateFixture(tmp);
+
+const base = {
+  command: 'delegation-gate',
+  phase: 'pre',
+  sessionId: FIXTURE_SESSION_ID,
+  host: 'hermes',
+};
+
+try {
+  const deny = runBridge({ ...base, tool: 'write_file', args: { path: 'src/a.ts', content: 'x' } }, tmp);
+  if (deny.allow === false && deny.gate === 'auto-chain-pending') pass('bridge denies write while pending');
+  else fail('write deny', JSON.stringify(deny));
+
+  const allowRead = runBridge({ ...base, tool: 'read_file', args: { path: 'src/a.ts' } }, tmp);
+  if (allowRead.allow === true) pass('bridge allows read while pending');
+  else fail('read allow', JSON.stringify(allowRead));
+
+  const allowSpawn = runBridge(
+    {
+      ...base,
+      tool: 'delegate_task',
+      args: { prompt: 'plan todo 2.1 swap deps', subagent_type: 'backend-engineer' },
+    },
+    tmp,
+  );
+  if (allowSpawn.allow === true) pass('bridge allows delegate_task while pending');
+  else fail('spawn allow', JSON.stringify(allowSpawn));
+
+  seedSpawnTodoPlan(tmp);
+  const denyTodo = runBridge(
+    { ...base, tool: 'delegate_task', args: { prompt: 'explore only', subagent_type: 'explore' } },
+    tmp,
+  );
+  if (denyTodo.allow === false && denyTodo.gate === 'spawn-todo-persistence') {
+    pass('bridge denies spawn skipping required plan todo');
+  } else {
+    fail('spawn todo persistence', JSON.stringify(denyTodo));
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(
+  '\n' +
+    (failed === 0
+      ? '🎉 Hermes delegation gate verify passed (4/4).'
+      : `⚠️  ${failed} Hermes gate check(s) failed.`),
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/mjs/verify-orchestrator-behavior.mjs

@@ -3,6 +3,7 @@
  * Consumer behavior verify — orchestrator honesty (ships in 0xray tarball).
  * Run: node node_modules/0xray/scripts/mjs/verify-orchestrator-behavior.mjs
  */
+import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 
@@ -113,10 +114,55 @@ if (text.includes('Deferred') && text.includes('❌ FAILED')) {
   fail('defer honesty', text.slice(0, 200));
 }
 
+// 6. delegations[] block in response
+if (text.includes('delegations') && text.includes('spawnHint')) {
+  pass('orchestrate-task includes delegations[] JSON block');
+} else {
+  fail('delegations block', 'missing JSON delegations in response');
+}
+
+// 7. pending-delegations.json written on defer (consumer cwd, not package root)
+const pendingPath = join(process.cwd(), '.xray', 'state', 'pending-delegations.json');
+if (existsSync(pendingPath)) {
+  try {
+    const pending = JSON.parse(readFileSync(pendingPath, 'utf8'));
+    if (pending.delegations?.some((d) => d.status === 'pending' && d.agent === 'backend-engineer')) {
+      pass('pending-delegations.json recorded on defer');
+    } else {
+      fail('pending file content', 'no pending backend-engineer delegation');
+    }
+  } catch (e) {
+    fail('pending file parse', e.message);
+  }
+} else {
+  fail('pending-delegations.json', 'file missing after defer');
+}
+
+// 8. spawnHint includes Task tool
+try {
+  const match = text.match(/```json\n([\s\S]*?)\n```/);
+  const block = match ? JSON.parse(match[1]) : null;
+  const hint = block?.delegations?.[0]?.spawnHint;
+  if (hint?.tool === 'Task' && hint?.subagent_type) {
+    pass('delegations spawnHint routes to host Task');
+  } else {
+    fail('spawnHint', JSON.stringify(hint));
+  }
+} catch (e) {
+  fail('spawnHint parse', e.message);
+}
+
+try {
+  if (existsSync(pendingPath)) unlinkSync(pendingPath);
+} catch {
+  /* cleanup best-effort */
+}
+
+const total = 8;
 console.log(
   '\n' +
     (failed === 0
-      ? '🎉 Orchestrator behavior verify passed (5/5).'
+      ? `🎉 Orchestrator behavior verify passed (${total}/${total}).`
       : `⚠️  ${failed} behavior check(s) failed.`),
 );
 process.exit(failed === 0 ? 0 : 1);

package/scripts/node/universal-version-manager.js

@@ -152,7 +152,7 @@ const OFFICIAL_VERSIONS = {
   framework: {
     version: PACKAGE_VERSION,
       displayName: "xray: Self-Healing AI Governance OS",
-      lastUpdated: "2026-06-17",
+      lastUpdated: "2026-06-19",
     // Counts (auto-calculated, but can be overridden)
     ...CALCULATED_COUNTS,
   },

package/src/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -42,6 +42,21 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/post-tool-use.js"
+            ],
+            "timeout": 15000
+          }
+        ]
+      }
     ]
   }
 }

package/src/mcps/orchestrator/handlers/complexity-handler.ts

@@ -10,6 +10,8 @@ import {
   isLeadDevModeActive,
   persistLeadDevPlan,
 } from '../../../nucleus/autonomy-kernel.js';
+import { bindPlanToSession } from '../../../nucleus/lead-dev-plan-persistence.js';
+import { clearPendingDelegations } from '../../../nucleus/pending-delegations.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { addObservations, extractComplexityObservations } from '../aside-context.js';
 import type { OrchestrationTask, ComplexityAnalysis } from '../types.js';
@@ -65,7 +67,7 @@ export class ComplexityHandler {
    * Handle analyze-complexity request
    */
   async handleAnalyzeComplexity(
-    args: { tasks: AnalyzeComplexityInput[] },
+    args: { tasks: AnalyzeComplexityInput[]; sessionId?: string },
     asideId?: string,
   ): Promise<{ content: Array<{ type: string; text: string }> }> {
     const tasks = normalizeAnalyzeTasks(args.tasks ?? []);
@@ -102,13 +104,18 @@ export class ComplexityHandler {
 
       if (leadDevPlan) {
         try {
+          const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
+          clearPendingDelegations();
           const planPath = persistLeadDevPlan(leadDevPlan);
+          const bound = bindPlanToSession(sessionId);
           await frameworkLogger.log(
             'orchestrator.server',
             'lead-dev-plan-persisted',
             'info',
             {
               planPath,
+              sessionId,
+              planGeneration: bound?.planGeneration,
               phaseCount: leadDevPlan.phases.length,
               todoCount: leadDevPlan.phases.reduce((n, p) => n + p.todos.length, 0),
             },

package/src/mcps/orchestrator/handlers/task-handler.ts

@@ -9,6 +9,11 @@ import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { mcpClientManager } from '../../../mcps/mcp-client.js';
 import { addObservations, extractOrchestrationObservations, spawnAside } from '../aside-context.js';
 import { getProvider } from '../config/memory-routing-bridge.js';
+import {
+  delegationSummaryForResponse,
+  recordDeferredDelegations,
+  type PendingDelegation,
+} from '../../../nucleus/pending-delegations.js';
 import type { OrchestrationResult, OrchestrationTask } from '../types.js';
 
 export interface TaskHandlerDeps {
@@ -66,6 +71,7 @@ export class TaskHandler {
     };
 
     const startTime = Date.now();
+    let pendingDelegations: PendingDelegation[] = [];
 
     try {
       // Validate tasks
@@ -90,6 +96,16 @@ export class TaskHandler {
 
       const results = await this.executePlan(executionPlan, sessionId, timeout);
 
+      if (results.deferredRecords.length > 0) {
+        pendingDelegations = recordDeferredDelegations(sessionId, results.deferredRecords);
+        await frameworkLogger.log(
+          'orchestrator.task-handler',
+          'pending-delegations-recorded',
+          'info',
+          { count: pendingDelegations.length, sessionId },
+        );
+      }
+
       // Feed per-task outcomes back to memory provider (not aggregate session stats)
       if (memoryProvider.ingestFeedback) {
         const outcomeByKey = new Map(
@@ -150,7 +166,12 @@ export class TaskHandler {
 
     orchestrationResult.duration = Date.now() - startTime;
 
-    const response = this.formatOrchestrationResponse(description, orchestrationResult, executionMode);
+    const response = this.formatOrchestrationResponse(
+      description,
+      orchestrationResult,
+      executionMode,
+      pendingDelegations,
+    );
 
     return { content: [{ type: 'text', text: response }] };
   }
@@ -173,6 +194,12 @@ export class TaskHandler {
     bottlenecks: string[];
     recommendations: string[];
     agentOutputs?: Record<string, string>;
+    deferredRecords: Array<{
+      taskId: string;
+      agent: string;
+      description: string;
+      type?: string;
+    }>;
     taskOutcomes: Array<{
       taskId: string;
       agent: string;
@@ -185,6 +212,12 @@ export class TaskHandler {
     let failedTasks = 0;
     let deferredTasks = 0;
     const agentOutputs: Record<string, string> = {};
+    const deferredRecords: Array<{
+      taskId: string;
+      agent: string;
+      description: string;
+      type?: string;
+    }> = [];
     const taskOutcomes: Array<{
       taskId: string;
       agent: string;
@@ -245,6 +278,12 @@ export class TaskHandler {
       } else {
         for (const task of tasks) {
           deferredTasks++;
+          deferredRecords.push({
+            taskId: task.id,
+            agent,
+            description: task.description,
+            type: task.type,
+          });
           taskOutcomes.push({
             taskId: task.id,
             agent,
@@ -288,6 +327,7 @@ export class TaskHandler {
       bottlenecks,
       recommendations,
       agentOutputs,
+      deferredRecords,
       taskOutcomes,
     };
   }
@@ -329,8 +369,18 @@ export class TaskHandler {
   private formatOrchestrationResponse(
     description: string,
     result: OrchestrationResult,
-    executionMode: string
+    executionMode: string,
+    pendingDelegations: PendingDelegation[] = [],
   ): string {
+    const delegationsBlock =
+      pendingDelegations.length > 0
+        ? `\n**Delegations (host Task required):**\n\`\`\`json\n${JSON.stringify(
+            { delegations: delegationSummaryForResponse(pendingDelegations) },
+            null,
+            2,
+          )}\n\`\`\`\n`
+        : '';
+
     return `🎯 Orchestration Complete: "${description}"
 
 **Session ID:** ${result.sessionId}
@@ -355,6 +405,6 @@ ${result.recommendations.length > 0 ? result.recommendations.map((r) => `•
 
 ${result.agentOutputs && Object.keys(result.agentOutputs).length > 0 
   ? `**Agent Outputs (real MCP responses):**\n${Object.entries(result.agentOutputs).map(([k, v]) => `• ${k}: ${v.substring(0, 200)}${v.length > 200 ? '...' : ''}`).join('\n')}\n`
-  : ''}`;
+  : ''}${delegationsBlock}`;
   }
 }

package/xray/features.json

@@ -35,7 +35,8 @@
     "per_suite_test_triage": true,
     "phased_plan_threshold": 25,
     "auto_consult_major_work": true,
-    "no_new_surface": true
+    "no_new_surface": true,
+    "auto_chain_delegations": true
   },
   "autonomous_reporting": {
     "enabled": true,