0xray 3.4.10 → 3.5.0

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

@@ -7,6 +7,7 @@
 import {
   checkCodexPatterns,
   checkFullTestSuite,
+  checkPendingDelegationGate,
   checkSubagentGate,
   checkSurfaceArea,
   ensureSessionBoot,
@@ -14,18 +15,20 @@ import {
   isWriteTool,
   loadFeatures,
   readStdinJson,
+  resolveSessionId,
   workspaceRoot,
 } from './grok-hook-utils.js';
 import { appendHookActivity } from './grok-hook-activity.js';
 
-function finish(root, decision, reason, hint, toolName) {
-  const out = { decision };
+function finish(root, decision, reason, hint, toolName, extra = {}) {
+  const out = { decision, ...extra };
   if (reason) out.reason = reason;
   if (hint) out.hint = hint;
   console.log(JSON.stringify(out));
   appendHookActivity(root, 'grok-pre-tool-use', decision, decision === 'deny' ? 'error' : 'info', {
     tool: toolName,
     reason: reason || hint || null,
+    gate: extra.gate || null,
     livePath: true,
   });
   process.exit(0);
@@ -43,10 +46,44 @@ async function main() {
     const features = loadFeatures();
     const ctx = extractFromEvent(event);
     toolName = ctx.toolName;
-    const { paths, content, cmd } = ctx;
+    const { paths, content, cmd, toolInput } = ctx;
+    const sessionId = resolveSessionId(event);
+
+    const delegationBlock = checkPendingDelegationGate(
+      toolName,
+      toolInput,
+      features,
+      eventRoot,
+      sessionId,
+    );
+    if (delegationBlock) {
+      finish(
+        eventRoot,
+        'deny',
+        delegationBlock.reason,
+        delegationBlock.hint,
+        toolName,
+        { gate: delegationBlock.gate },
+      );
+    }
 
-    const subagentBlock = checkSubagentGate(toolName, features);
-    if (subagentBlock) finish(eventRoot, 'deny', subagentBlock, null, toolName);
+    const subagentBlock = checkSubagentGate(
+      toolName,
+      features,
+      eventRoot,
+      sessionId,
+      toolInput,
+    );
+    if (subagentBlock) {
+      finish(
+        eventRoot,
+        'deny',
+        subagentBlock.reason || subagentBlock,
+        subagentBlock.hint || null,
+        toolName,
+        { gate: subagentBlock.gate || 'spawn-gate' },
+      );
+    }
 
     if (features.no_new_surface && isWriteTool(toolName) && paths.length) {
       const surfaceBlock = checkSurfaceArea(paths, eventRoot);
@@ -95,6 +132,7 @@ function extractFromEvent(event) {
 
   return {
     toolName,
+    toolInput,
     paths,
     content,
     cmd: String(toolInput.command || ''),

package/dist/integrations/grok/hooks/session-start.js

@@ -6,8 +6,10 @@
 
 import {
   buildSessionBootPayload,
+  clearPendingDelegationsForSessionChange,
   ensureSessionBoot,
   readStdinJson,
+  resolveSessionId,
   workspaceRoot,
   writeSessionBoot,
 } from './grok-hook-utils.js';
@@ -20,6 +22,12 @@ async function main() {
   try {
     const event = await readStdinJson();
     const eventRoot = event.workspaceRoot || event.cwd || root;
+    const sessionId = resolveSessionId(event);
+    if (clearPendingDelegationsForSessionChange(sessionId, eventRoot)) {
+      appendHookActivity(eventRoot, 'grok-session-start', 'stale-pending-cleared', 'info', {
+        sessionId,
+      });
+    }
     const source =
       HOOK_EVENT === 'user_prompt_submit'
         ? '0xray/grok-user-prompt-submit'

package/dist/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/dist/mcps/orchestrator/handlers/complexity-handler.d.ts

@@ -26,6 +26,7 @@ export declare class ComplexityHandler {
      */
     handleAnalyzeComplexity(args: {
         tasks: AnalyzeComplexityInput[];
+        sessionId?: string;
     }, asideId?: string): Promise<{
         content: Array<{
             type: string;

package/dist/mcps/orchestrator/handlers/complexity-handler.js

@@ -5,6 +5,8 @@
  */
 import { frameworkLogger } from '../../../core/framework-logger.js';
 import { buildLeadDevPlan, 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';
 function normalizeAnalyzeTasks(raw) {
@@ -63,9 +65,14 @@ export class ComplexityHandler {
                 : null;
             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/dist/mcps/orchestrator/handlers/task-handler.js

@@ -8,6 +8,7 @@ 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, } from '../../../nucleus/pending-delegations.js';
 /**
  * Task Handler
  * Processes orchestrate-task requests
@@ -31,6 +32,7 @@ export class TaskHandler {
             recommendations: [],
         };
         const startTime = Date.now();
+        let pendingDelegations = [];
         try {
             // Validate tasks
             const validation = this.planner.validateTasks(tasks);
@@ -50,6 +52,10 @@ 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(results.taskOutcomes.map((o) => [`${o.agent}:${o.taskId}`, o]));
@@ -100,7 +106,7 @@ export class TaskHandler {
             orchestrationResult.recommendations.push(`Orchestration error: ${error instanceof Error ? error.message : String(error)}`);
         }
         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 }] };
     }
     /**
@@ -114,6 +120,7 @@ export class TaskHandler {
         let failedTasks = 0;
         let deferredTasks = 0;
         const agentOutputs = {};
+        const deferredRecords = [];
         const taskOutcomes = [];
         const skillServers = new Set([
             'code-review', 'code-reviewer',
@@ -167,6 +174,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,
@@ -199,6 +212,7 @@ export class TaskHandler {
             bottlenecks,
             recommendations,
             agentOutputs,
+            deferredRecords,
             taskOutcomes,
         };
     }
@@ -232,7 +246,10 @@ export class TaskHandler {
     /**
      * Format orchestration response
      */
-    formatOrchestrationResponse(description, result, executionMode) {
+    formatOrchestrationResponse(description, result, executionMode, pendingDelegations = []) {
+        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}
@@ -257,6 +274,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/dist/nucleus/lead-dev-plan-persistence.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Todo-level lead-dev plan persistence — spawn gate survives beyond 4h mtime
+ * while outstanding todos remain. SSOT for plan todo status sync.
+ */
+import type { LeadDevPlan, LeadDevTodo } from './autonomy-kernel.js';
+export interface PersistedLeadDevPlan extends LeadDevPlan {
+    persistedAt?: string;
+    sessionId?: string;
+    planGeneration?: number;
+}
+export interface SpawnTodoValidation {
+    valid: boolean;
+    reason?: string;
+    gate?: string;
+    hint?: Record<string, unknown>;
+    expectedTodoId?: string | null;
+}
+export declare function leadDevPlanStatePath(projectRoot?: string): string;
+export declare function loadPersistedLeadDevPlan(projectRoot?: string): PersistedLeadDevPlan | null;
+export declare function savePersistedLeadDevPlan(plan: PersistedLeadDevPlan, projectRoot?: string): string;
+export declare function allPlanTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+export declare function getOutstandingTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+/** First outstanding todo in phase order */
+export declare function getNextRequiredTodo(plan: PersistedLeadDevPlan): LeadDevTodo | null;
+/**
+ * Plan valid for spawn when active and either:
+ * - outstanding todos remain (ignores 4h mtime), or
+ * - all todos complete and persistedAt within TTL
+ */
+export declare function hasValidLeadDevPlanForSpawn(projectRoot?: string, _sessionId?: string | null): boolean;
+export declare function updatePlanTodoStatus(todoId: string, status: LeadDevTodo['status'], projectRoot?: string): boolean;
+export declare function bindPlanToSession(sessionId: string, projectRoot?: string): PersistedLeadDevPlan | null;
+export interface SpawnToolInput {
+    prompt?: string;
+    description?: string;
+    task?: string;
+    subagent_type?: string;
+    agent?: string;
+    delegationId?: string;
+    planTodoId?: string;
+}
+export declare function validateSpawnMatchesTodo(toolInput: SpawnToolInput, projectRoot?: string, expectedTodo?: LeadDevTodo | null): SpawnTodoValidation;
+export declare function markTodoInProgressOnSpawn(toolInput: SpawnToolInput, projectRoot?: string): string | null;

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

@@ -0,0 +1,155 @@
+/**
+ * Todo-level lead-dev plan persistence — spawn gate survives beyond 4h mtime
+ * while outstanding todos remain. SSOT for plan todo status sync.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DEFAULT_PENDING_TTL_MS } from './pending-delegations.js';
+export function leadDevPlanStatePath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.xray', 'state', 'lead-dev-plan.json');
+}
+export function loadPersistedLeadDevPlan(projectRoot = process.cwd()) {
+    const planPath = leadDevPlanStatePath(projectRoot);
+    if (!fs.existsSync(planPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(planPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function savePersistedLeadDevPlan(plan, projectRoot = process.cwd()) {
+    const planPath = leadDevPlanStatePath(projectRoot);
+    fs.mkdirSync(path.dirname(planPath), { recursive: true });
+    fs.writeFileSync(planPath, JSON.stringify(plan, null, 2));
+    return planPath;
+}
+export function allPlanTodos(plan) {
+    return plan.phases.flatMap((p) => p.todos);
+}
+export function getOutstandingTodos(plan) {
+    return allPlanTodos(plan).filter((t) => t.status === 'pending' || t.status === 'in_progress');
+}
+/** First outstanding todo in phase order */
+export function getNextRequiredTodo(plan) {
+    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;
+}
+/**
+ * Plan valid for spawn when active and either:
+ * - outstanding todos remain (ignores 4h mtime), or
+ * - all todos complete and persistedAt within TTL
+ */
+export function hasValidLeadDevPlanForSpawn(projectRoot = process.cwd(), _sessionId) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    if (!plan?.active)
+        return false;
+    const outstanding = getOutstandingTodos(plan);
+    if (outstanding.length > 0)
+        return true;
+    const persistedAt = plan.persistedAt;
+    if (!persistedAt) {
+        try {
+            const stat = fs.statSync(leadDevPlanStatePath(projectRoot));
+            return Date.now() - stat.mtimeMs <= DEFAULT_PENDING_TTL_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+    return Date.now() - new Date(persistedAt).getTime() <= DEFAULT_PENDING_TTL_MS;
+}
+export function updatePlanTodoStatus(todoId, status, projectRoot = process.cwd()) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    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)
+        savePersistedLeadDevPlan(plan, projectRoot);
+    return updated;
+}
+export function bindPlanToSession(sessionId, projectRoot = process.cwd()) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    if (!plan)
+        return null;
+    const generation = (plan.planGeneration ?? 0) + 1;
+    const next = {
+        ...plan,
+        sessionId,
+        planGeneration: generation,
+        persistedAt: new Date().toISOString(),
+    };
+    savePersistedLeadDevPlan(next, projectRoot);
+    return next;
+}
+function normalizeAgent(agent) {
+    const key = agent.toLowerCase().trim();
+    const aliases = {
+        'bug-triage-specialist': 'bug-triage',
+        'code-reviewer': 'code-review',
+    };
+    return aliases[key] ?? key;
+}
+function agentsAlign(expected, actual) {
+    const e = normalizeAgent(expected);
+    const a = normalizeAgent(actual);
+    return e === a || e.includes(a) || a.includes(e);
+}
+export function validateSpawnMatchesTodo(toolInput, projectRoot = process.cwd(), expectedTodo) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    const nextTodo = expectedTodo ?? (plan ? getNextRequiredTodo(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 };
+    }
+    if (prompt.includes(nextTodo.id.toLowerCase())) {
+        return { valid: true, expectedTodoId: nextTodo.id };
+    }
+    if (prompt.includes(nextTodo.task.toLowerCase().slice(0, 30))) {
+        return { valid: true, expectedTodoId: nextTodo.id };
+    }
+    if (subagent && agentsAlign(nextTodo.subagent, subagent) && prompt.length > 20) {
+        return { valid: true, expectedTodoId: nextTodo.id };
+    }
+    return {
+        valid: false,
+        reason: `Spawn must target plan todo ${nextTodo.id} before other work`,
+        gate: 'spawn-todo-persistence',
+        expectedTodoId: nextTodo.id,
+        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 markTodoInProgressOnSpawn(toolInput, projectRoot = process.cwd()) {
+    const plan = loadPersistedLeadDevPlan(projectRoot);
+    if (!plan)
+        return null;
+    const validation = validateSpawnMatchesTodo(toolInput, projectRoot);
+    if (!validation.valid || !validation.expectedTodoId)
+        return null;
+    updatePlanTodoStatus(validation.expectedTodoId, 'in_progress', projectRoot);
+    return validation.expectedTodoId;
+}

package/dist/nucleus/pending-delegations.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Pending delegations SSOT — written by task-handler on delegate-deferred.
+ * Grok hooks read the same file; PostToolUse never re-parses MCP output.
+ */
+import type { LeadDevPlan, LeadDevTodo } from './autonomy-kernel.js';
+export declare const DEFAULT_PENDING_TTL_MS: number;
+export type DelegationMatchMethod = 'taskId' | 'description' | 'agent-only' | 'none';
+export interface SpawnHint {
+    tool: 'Task';
+    subagent_type: string;
+    description: string;
+    planTodoId: string | null;
+    delegationId: string;
+}
+export interface PendingDelegation {
+    id: string;
+    taskId: string;
+    agent: string;
+    taskDescription: string;
+    taskType: string;
+    sessionId: string;
+    planTodoId: string | null;
+    planTodoTask: string | null;
+    matchMethod: DelegationMatchMethod;
+    matchConfidence: number;
+    status: 'pending' | 'satisfied';
+    createdAt: string;
+    satisfiedAt: string | null;
+    spawnHint: SpawnHint;
+}
+export interface PendingDelegationsState {
+    sessionId: string;
+    createdAt: string;
+    ttlMs: number;
+    delegations: PendingDelegation[];
+}
+export interface DeferredTaskRecord {
+    taskId: string;
+    agent: string;
+    description: string;
+    type?: string;
+}
+export declare function pendingDelegationsPath(projectRoot?: string): string;
+export declare function leadDevPlanPath(projectRoot?: string): string;
+export declare function isAutoChainDelegationsEnabled(projectRoot?: string): boolean;
+export declare function matchPlanTodo(agent: string, taskDescription: string, taskId: string, plan: LeadDevPlan | null): {
+    todo: LeadDevTodo | null;
+    method: DelegationMatchMethod;
+    confidence: number;
+};
+export declare function mapSubagentToTaskType(agent: string): string;
+export declare function buildSpawnHint(delegation: Pick<PendingDelegation, 'id' | 'agent' | 'taskDescription' | 'planTodoId' | 'planTodoTask'>): SpawnHint;
+export declare function loadPendingDelegationsState(projectRoot?: string): PendingDelegationsState | null;
+export declare function savePendingDelegationsState(state: PendingDelegationsState, projectRoot?: string): string;
+export declare function recordDeferredDelegations(sessionId: string, deferrals: DeferredTaskRecord[], projectRoot?: string): PendingDelegation[];
+export declare function isPendingStateActive(state: PendingDelegationsState | null, sessionId: string | null | undefined): boolean;
+export declare function getActivePendingDelegations(sessionId: string | null | undefined, projectRoot?: string): PendingDelegation[];
+export interface SatisfyDelegationInput {
+    delegationId?: string;
+    taskId?: string;
+    planTodoId?: string;
+    agent?: string;
+    toolPrompt?: string;
+}
+export declare function satisfyDelegation(input: SatisfyDelegationInput, projectRoot?: string): {
+    satisfied: PendingDelegation[];
+    clearedAll: boolean;
+};
+export declare function clearPendingDelegations(projectRoot?: string): boolean;
+export declare function clearPendingDelegationsForSessionChange(newSessionId: string | null | undefined, projectRoot?: string): boolean;
+export declare function delegationSummaryForResponse(delegations: PendingDelegation[]): Array<Record<string, unknown>>;