0xray 3.5.3 → 3.5.4

package/dist/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.4] - 2026-06-19
+
+### ✨ Features
+- **Synthesis consult receipt gate** — s.1–s.3 todos require `.xray/state/synthesis-consult-{id}.json` before completion; `evaluatePostToolSpawn` records receipts from subagent output; Grok post-tool hook wired
+
+### ✅ Tests
+- `synthesis-consult-receipt.test.ts`; E2E/outcome verifiers write fixture receipts
+
+---
+
 ## [3.5.3] - 2026-06-19
 
 ### 🔄 Changes

package/dist/integrations/grok/hooks/post-tool-use.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Grok PostToolUse — auto-chain observability + targeted clear on Task spawn.
+ * Grok PostToolUse — auto-chain observability + consult receipt gate on Task spawn.
  * Passive hook: stdout ignored by Grok; side effects only.
  */
 
@@ -10,12 +10,24 @@ import {
   isSubagentTool,
   readStdinJson,
   resolveSessionId,
-  satisfyDelegationsFromToolInput,
-  validateSpawnMatchesTodo,
-  updatePlanTodoStatusInPlace,
   workspaceRoot,
 } from './grok-hook-utils.js';
 import { appendHookActivity } from './grok-hook-activity.js';
+import {
+  evaluatePostToolSpawn,
+  isOrchestrateToolEvent as gateIsOrchestrateToolEvent,
+} from '../../hooks/delegation-gate-runtime.mjs';
+
+function extractToolOutput(event) {
+  return (
+    event.toolOutput ??
+    event.toolResult ??
+    event.result ??
+    event.output ??
+    event.tool_output ??
+    null
+  );
+}
 
 async function main() {
   const root = workspaceRoot();
@@ -25,7 +37,7 @@ async function main() {
     const sessionId = resolveSessionId(event);
     const { toolName, toolInput } = extractToolContext(event);
 
-    if (isOrchestrateToolEvent(toolName, toolInput)) {
+    if (isOrchestrateToolEvent(toolName, toolInput) || gateIsOrchestrateToolEvent(toolName, toolInput)) {
       appendHookActivity(eventRoot, 'grok-post-tool-use', 'auto-chain-pending', 'info', {
         tool: toolName,
         sessionId,
@@ -34,18 +46,19 @@ async function main() {
     }
 
     if (isSubagentTool(toolName)) {
-      const spawnCheck = validateSpawnMatchesTodo(toolInput, eventRoot);
-      if (spawnCheck.valid && spawnCheck.expectedTodoId) {
-        updatePlanTodoStatusInPlace(spawnCheck.expectedTodoId, 'completed', eventRoot);
-      }
+      const spawnResult = evaluatePostToolSpawn(toolName, toolInput, eventRoot, {
+        toolOutput: extractToolOutput(event),
+        sessionId,
+      });
 
-      const result = satisfyDelegationsFromToolInput(toolInput, eventRoot);
-      if (result.satisfied.length > 0) {
+      if (spawnResult.satisfied.length > 0 || spawnResult.expectedTodoId) {
         appendHookActivity(eventRoot, 'grok-post-tool-use', 'auto-chain-cleared', 'success', {
           tool: toolName,
-          satisfied: result.satisfied.map((d) => d.id),
-          clearedAll: result.clearedAll,
-          planTodoId: spawnCheck.expectedTodoId ?? null,
+          satisfied: spawnResult.satisfied.map((d) => d.id),
+          clearedAll: spawnResult.clearedAll,
+          planTodoId: spawnResult.expectedTodoId ?? null,
+          receiptRecorded: spawnResult.receiptRecorded ?? false,
+          todoCompleted: spawnResult.todoCompleted ?? false,
         });
       }
     }

package/dist/integrations/hooks/delegation-gate-runtime.mjs

@@ -72,4 +72,10 @@ export const {
   validateSpawnMatchesTodo,
   updatePlanTodoStatus,
   updatePlanTodoStatusInPlace,
+  writeSynthesisConsultReceipt,
+  hasValidSynthesisConsultReceipt,
+  tryRecordSynthesisConsultReceipt,
+  buildReceiptFromConsultOutput,
+  parseConsultVerdictFromText,
+  isSynthesisConsultTodoId,
 } = gate;

package/dist/nucleus/delegation-gate.d.ts

@@ -7,6 +7,7 @@ import { type PendingDelegation } from './pending-delegations.js';
 export { getActivePendingDelegations } from './pending-delegations.js';
 import { updatePlanTodoStatus, type SpawnToolInput } from './lead-dev-plan-persistence.js';
 export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
+export { buildReceiptFromConsultOutput, hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, loadSynthesisConsultReceipt, parseConsultVerdictFromText, tryRecordSynthesisConsultReceipt, writeSynthesisConsultReceipt, type SynthesisConsultReceipt, type SynthesisConsultVerdict, } from './synthesis-consult-receipt.js';
 export declare const updatePlanTodoStatusInPlace: typeof updatePlanTodoStatus;
 export type DelegationGateHost = 'grok' | 'hermes' | 'opencode' | 'openclaw' | 'generic';
 export interface DelegationGateFeatures {
@@ -57,6 +58,12 @@ export interface PostToolSpawnResult {
     satisfied: PendingDelegation[];
     clearedAll: boolean;
     expectedTodoId?: string | null;
+    receiptRecorded?: boolean;
+    todoCompleted?: boolean;
+}
+export interface PostToolSpawnOptions {
+    toolOutput?: unknown;
+    sessionId?: string | null;
 }
 export declare function loadDelegationGateFeatures(projectRoot?: string): DelegationGateFeatures;
 export declare function normalizeHostToolInput(toolInput: ToolGateInput): SpawnToolInput & {
@@ -77,7 +84,7 @@ export declare function evaluatePendingDelegationGate(toolName: string, toolInpu
  * pending gate, then spawn todo gate for subagent tools.
  */
 export declare function evaluatePreToolGate(toolName: string, toolInput: ToolGateInput, ctx: PreToolGateContext): PreToolGateResult;
-export declare function evaluatePostToolSpawn(toolName: string, toolInput: ToolGateInput, projectRoot: string): PostToolSpawnResult;
+export declare function evaluatePostToolSpawn(toolName: string, toolInput: ToolGateInput, projectRoot: string, options?: PostToolSpawnOptions): PostToolSpawnResult;
 export declare function isOrchestrateToolEvent(toolName: string, toolInput?: ToolGateInput): boolean;
 /** Back-compat shims for Grok hook-utils and tests. */
 export declare function checkPendingDelegationGate(toolName: string, toolInput: ToolGateInput, features: DelegationGateFeatures, projectRoot: string, sessionId: string | null): PreToolGateDeny | null;

package/dist/nucleus/delegation-gate.js

@@ -7,9 +7,11 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getActivePendingDelegations, satisfyDelegation, } from './pending-delegations.js';
 export { getActivePendingDelegations } from './pending-delegations.js';
-import { allPlanTodos, areSynthesisConsultTodosComplete, hasValidLeadDevPlanForSpawn, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, getNextRequiredTodo, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
+import { allPlanTodos, areSynthesisConsultTodosComplete, getSynthesisConsultTodos, hasValidLeadDevPlanForSpawn, isSynthesisRealignmentPlan, loadPersistedLeadDevPlan, getNextRequiredTodo, validateSpawnMatchesTodo, updatePlanTodoStatus, } from './lead-dev-plan-persistence.js';
 import { getSynthesisDueReason, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
+import { isSynthesisConsultTodoId, tryRecordSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
 export { validateSpawnMatchesTodo, updatePlanTodoStatus, savePersistedLeadDevPlan, } from './lead-dev-plan-persistence.js';
+export { buildReceiptFromConsultOutput, hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, loadSynthesisConsultReceipt, parseConsultVerdictFromText, tryRecordSynthesisConsultReceipt, writeSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
 export const updatePlanTodoStatusInPlace = updatePlanTodoStatus;
 const READ_TOOLS = new Set([
     'read_file',
@@ -285,7 +287,7 @@ export function evaluatePreToolGate(toolName, toolInput, ctx) {
         return spawnBlock;
     return { allow: true };
 }
-export function evaluatePostToolSpawn(toolName, toolInput, projectRoot) {
+export function evaluatePostToolSpawn(toolName, toolInput, projectRoot, options = {}) {
     const normalized = normalizeHostToolInput(toolInput);
     const spawnCheck = validateSpawnMatchesTodo(normalized, projectRoot);
     const satisfyInput = {
@@ -299,12 +301,31 @@ export function evaluatePostToolSpawn(toolName, toolInput, projectRoot) {
     if (normalized.planTodoId)
         satisfyInput.planTodoId = normalized.planTodoId;
     const result = satisfyDelegation(satisfyInput, projectRoot);
-    if (spawnCheck.valid && spawnCheck.expectedTodoId) {
-        updatePlanTodoStatus(spawnCheck.expectedTodoId, 'completed', projectRoot);
+    let receiptRecorded = false;
+    let todoCompleted = false;
+    const expectedTodoId = spawnCheck.expectedTodoId ?? null;
+    if (spawnCheck.valid && expectedTodoId) {
+        const plan = loadPersistedLeadDevPlan(projectRoot);
+        const sessionId = options.sessionId ?? plan?.sessionId ?? null;
+        const consultTodo = plan
+            ? getSynthesisConsultTodos(plan).find((t) => t.id === expectedTodoId)
+            : undefined;
+        if (isSynthesisConsultTodoId(expectedTodoId) &&
+            consultTodo &&
+            sessionId &&
+            options.toolOutput != null) {
+            const receipt = tryRecordSynthesisConsultReceipt(expectedTodoId, consultTodo.subagent, sessionId, options.toolOutput, projectRoot);
+            receiptRecorded = receipt != null;
+        }
+        if (updatePlanTodoStatus(expectedTodoId, 'completed', projectRoot)) {
+            todoCompleted = true;
+        }
     }
     return {
         ...result,
-        expectedTodoId: spawnCheck.expectedTodoId ?? null,
+        expectedTodoId,
+        receiptRecorded,
+        todoCompleted,
     };
 }
 export function isOrchestrateToolEvent(toolName, toolInput = {}) {

package/dist/nucleus/lead-dev-plan-persistence.js

@@ -7,6 +7,7 @@ import * as path from 'path';
 import { SYNTHESIS_REALIGNMENT_PHASE_ID } from './autonomy-kernel.js';
 import { DEFAULT_PENDING_TTL_MS } from './pending-delegations.js';
 import { completeSynthesisCheckpoint, getSynthesisCheckpointSessionId, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
+import { hasValidSynthesisConsultReceipt, isSynthesisConsultTodoId, } from './synthesis-consult-receipt.js';
 export function leadDevPlanStatePath(projectRoot = process.cwd()) {
     return path.join(projectRoot, '.xray', 'state', 'lead-dev-plan.json');
 }
@@ -101,6 +102,27 @@ export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd()
     const plan = loadPersistedLeadDevPlan(projectRoot);
     if (!plan)
         return false;
+    let targetTodo;
+    for (const phase of plan.phases) {
+        for (const todo of phase.todos) {
+            if (todo.id === todoId) {
+                targetTodo = todo;
+                break;
+            }
+        }
+        if (targetTodo)
+            break;
+    }
+    if (status === 'completed' && isSynthesisConsultTodoId(todoId)) {
+        const receiptExpected = {};
+        if (plan.sessionId !== undefined)
+            receiptExpected.sessionId = plan.sessionId;
+        if (targetTodo?.subagent)
+            receiptExpected.subagent = targetTodo.subagent;
+        if (!hasValidSynthesisConsultReceipt(todoId, projectRoot, receiptExpected)) {
+            return false;
+        }
+    }
     let updated = false;
     for (const phase of plan.phases) {
         for (const todo of phase.todos) {

package/dist/nucleus/synthesis-consult-receipt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Synthesis consult receipt SSOT — outcome-based completion for s.N todos.
+ * Receipts live at `.xray/state/synthesis-consult-{todoId}.json`.
+ */
+export type SynthesisConsultVerdict = 'PASS' | 'CONDITIONAL' | 'FAIL';
+export interface SynthesisConsultReceipt {
+    sessionId: string;
+    subagent: string;
+    verdict: SynthesisConsultVerdict;
+    topRisks: string[];
+    hardeningNote: string;
+    todoId?: string;
+    recordedAt?: string;
+}
+export declare function isSynthesisConsultTodoId(todoId: string): boolean;
+export declare function synthesisConsultReceiptPath(todoId: string, projectRoot?: string): string;
+export declare function loadSynthesisConsultReceipt(todoId: string, projectRoot?: string): SynthesisConsultReceipt | null;
+export declare function writeSynthesisConsultReceipt(todoId: string, receipt: SynthesisConsultReceipt, projectRoot?: string): string;
+export declare function validateSynthesisConsultReceipt(receipt: SynthesisConsultReceipt, todoId: string, expected?: {
+    sessionId?: string | null;
+    subagent?: string;
+}): boolean;
+export declare function hasValidSynthesisConsultReceipt(todoId: string, projectRoot?: string, expected?: {
+    sessionId?: string | null;
+    subagent?: string;
+}): boolean;
+export declare function parseConsultVerdictFromText(text: string): SynthesisConsultVerdict | null;
+export declare function extractTopRisksFromText(text: string, max?: number): string[];
+export declare function extractHardeningNoteFromText(text: string, maxChars?: number): string;
+export declare function coerceToolOutputText(output: unknown): string;
+export declare function buildReceiptFromConsultOutput(todoId: string, subagent: string, sessionId: string, outputText: string): SynthesisConsultReceipt | null;
+export declare function tryRecordSynthesisConsultReceipt(todoId: string, subagent: string, sessionId: string, output: unknown, projectRoot?: string): SynthesisConsultReceipt | null;

package/dist/nucleus/synthesis-consult-receipt.js

@@ -0,0 +1,155 @@
+/**
+ * Synthesis consult receipt SSOT — outcome-based completion for s.N todos.
+ * Receipts live at `.xray/state/synthesis-consult-{todoId}.json`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const CONSULT_TODO_PATTERN = /^s\.\d+$/;
+export function isSynthesisConsultTodoId(todoId) {
+    return CONSULT_TODO_PATTERN.test(todoId);
+}
+export function synthesisConsultReceiptPath(todoId, projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', `synthesis-consult-${todoId}.json`);
+}
+export function loadSynthesisConsultReceipt(todoId, projectRoot = process.cwd()) {
+    const receiptPath = synthesisConsultReceiptPath(todoId, projectRoot);
+    if (!fs.existsSync(receiptPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSynthesisConsultReceipt(todoId, receipt, projectRoot = process.cwd()) {
+    const receiptPath = synthesisConsultReceiptPath(todoId, projectRoot);
+    fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
+    const payload = {
+        ...receipt,
+        todoId,
+        recordedAt: receipt.recordedAt ?? new Date().toISOString(),
+    };
+    fs.writeFileSync(receiptPath, JSON.stringify(payload, null, 2));
+    return receiptPath;
+}
+function normalizeSubagent(agent) {
+    const key = agent.toLowerCase().trim();
+    const aliases = {
+        'bug-triage-specialist': 'bug-triage',
+        'code-reviewer': 'code-review',
+    };
+    return aliases[key] ?? key;
+}
+function subagentsAlign(expected, actual) {
+    const e = normalizeSubagent(expected);
+    const a = normalizeSubagent(actual);
+    return e === a || e.includes(a) || a.includes(e);
+}
+function isValidVerdict(value) {
+    return value === 'PASS' || value === 'CONDITIONAL' || value === 'FAIL';
+}
+export function validateSynthesisConsultReceipt(receipt, todoId, expected) {
+    if (!receipt.sessionId || !receipt.subagent || !isValidVerdict(receipt.verdict)) {
+        return false;
+    }
+    if (!Array.isArray(receipt.topRisks))
+        return false;
+    if (typeof receipt.hardeningNote !== 'string')
+        return false;
+    if (expected?.sessionId && receipt.sessionId !== expected.sessionId)
+        return false;
+    if (expected?.subagent && !subagentsAlign(expected.subagent, receipt.subagent)) {
+        return false;
+    }
+    if (receipt.todoId && receipt.todoId !== todoId)
+        return false;
+    return true;
+}
+export function hasValidSynthesisConsultReceipt(todoId, projectRoot = process.cwd(), expected) {
+    const receipt = loadSynthesisConsultReceipt(todoId, projectRoot);
+    if (!receipt)
+        return false;
+    return validateSynthesisConsultReceipt(receipt, todoId, expected);
+}
+export function parseConsultVerdictFromText(text) {
+    const normalized = text.toUpperCase();
+    if (/\bCONDITIONAL(\s+PASS)?\b/.test(normalized))
+        return 'CONDITIONAL';
+    if (/\b(?:PASS|SHIP)\b/.test(normalized))
+        return 'PASS';
+    if (/\bFAIL\b/.test(normalized))
+        return 'FAIL';
+    return null;
+}
+export function extractTopRisksFromText(text, max = 5) {
+    const risks = [];
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (/^(?:[-*•]|\d+\.)\s*(?:risk|top\s*risk)/i.test(trimmed)) {
+            risks.push(trimmed.replace(/^[-*•\d.]+\s*/i, '').slice(0, 240));
+        }
+        else if (/^risk\s*:/i.test(trimmed)) {
+            risks.push(trimmed.replace(/^risk\s*:\s*/i, '').slice(0, 240));
+        }
+        if (risks.length >= max)
+            break;
+    }
+    return risks;
+}
+export function extractHardeningNoteFromText(text, maxChars = 500) {
+    const match = text.match(/(?:hardening|recommend(?:ation)?s?)\s*[:\n]([\s\S]{0,800})/i);
+    if (match?.[1])
+        return match[1].trim().slice(0, maxChars);
+    const lines = text.split('\n').filter((l) => l.trim().length > 0);
+    return lines.slice(-3).join(' ').slice(0, maxChars);
+}
+export function coerceToolOutputText(output) {
+    if (typeof output === 'string')
+        return output;
+    if (output == null)
+        return '';
+    if (typeof output === 'object') {
+        const obj = output;
+        if (typeof obj.text === 'string')
+            return obj.text;
+        if (typeof obj.content === 'string')
+            return obj.content;
+        if (typeof obj.message === 'string')
+            return obj.message;
+        try {
+            return JSON.stringify(output);
+        }
+        catch {
+            return String(output);
+        }
+    }
+    return String(output);
+}
+export function buildReceiptFromConsultOutput(todoId, subagent, sessionId, outputText) {
+    const text = outputText.trim();
+    if (!text)
+        return null;
+    const verdict = parseConsultVerdictFromText(text);
+    if (!verdict)
+        return null;
+    return {
+        sessionId,
+        subagent,
+        verdict,
+        topRisks: extractTopRisksFromText(text),
+        hardeningNote: extractHardeningNoteFromText(text),
+        todoId,
+    };
+}
+export function tryRecordSynthesisConsultReceipt(todoId, subagent, sessionId, output, projectRoot = process.cwd()) {
+    const receipt = buildReceiptFromConsultOutput(todoId, subagent, sessionId, coerceToolOutputText(output));
+    if (!receipt || !validateSynthesisConsultReceipt(receipt, todoId, { sessionId, subagent })) {
+        return null;
+    }
+    writeSynthesisConsultReceipt(todoId, receipt, projectRoot);
+    return receipt;
+}

package/dist/plugin/xray-codex-injection.js

@@ -182,7 +182,7 @@ export default async function xrayCodexPlugin(input) {
             const { tool, args, result } = input;
             if (isSubagentTool(tool)) {
                 try {
-                    const spawnResult = evaluatePostToolSpawn(tool, (args ?? {}), directory);
+                    const spawnResult = evaluatePostToolSpawn(tool, (args ?? {}), directory, { toolOutput: result });
                     if (spawnResult.satisfied.length > 0) {
                         logger.log(`🔗 Delegation gate post: satisfied ${spawnResult.satisfied.map((d) => d.id).join(", ")}`);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.5.3",
+  "version": "3.5.4",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",