opencode-matrixx 2.6.5 → 2.6.6

package/dist/index.js

@@ -44411,11 +44411,14 @@ var ModelFallbackEntrySchema = exports_external.object({
   variant: exports_external.string().optional()
 });
 var complexityDowngradeValueSchema = exports_external.string().refine((s) => {
-  if (s.includes("/")) {
-    const parts = s.split("/");
-    return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
-  }
-  return false;
+  if (!s.includes("/"))
+    return false;
+  if (s.startsWith("/") || s.endsWith("/"))
+    return false;
+  if (s.includes("//"))
+    return false;
+  const parts = s.split("/");
+  return parts.length >= 2 && parts.every((p) => p.length > 0);
 }, { message: "Must be <provider>/<model>" });
 var ComplexityDowngradesSchema = exports_external.record(exports_external.string(), exports_external.record(exports_external.string(), complexityDowngradeValueSchema));
 var AgentModelRequirementsSchema = exports_external.object({
@@ -48413,8 +48416,11 @@ function getPlanProgress(planPath) {
     const content = readFileSync10(planPath, "utf-8");
     const uncheckedMatches = content.match(/^[-*]\s*\[\s*\]/gm) || [];
     const checkedMatches = content.match(/^[-*]\s*\[[xX]\]/gm) || [];
-    const total = uncheckedMatches.length + checkedMatches.length;
-    const completed = checkedMatches.length;
+    const numberedUnchecked = content.match(/^[-*]\s*\[\s*\]\s*\d+\./gm) || [];
+    const numberedChecked = content.match(/^[-*]\s*\[[xX]\]\s*\d+\./gm) || [];
+    const useNumbered = numberedUnchecked.length + numberedChecked.length > 0;
+    const total = useNumbered ? numberedUnchecked.length + numberedChecked.length : uncheckedMatches.length + checkedMatches.length;
+    const completed = useNumbered ? numberedChecked.length : checkedMatches.length;
     return {
       total,
       completed,
@@ -52632,6 +52638,16 @@ function createBackgroundNotificationHook(manager) {
     event: eventHandler
   };
 }
+// src/hooks/background-task-blocker/hook.ts
+function createBackgroundTaskBlockerHook() {
+  return {
+    "tool.execute.before": async (input, _output) => {
+      if (input.tool === "background_task") {
+        throw new Error('Tool "background_task" is disabled. Use the "task" tool with category/subagent_type and run_in_background=true for agent delegation.');
+      }
+    }
+  };
+}
 // src/hooks/bash-file-read-guard.ts
 var WARNING_MESSAGE = "Prefer the Read tool over `cat`/`head`/`tail` for reading file contents. " + "The Read tool provides line numbers and hash anchors for precise editing.";
 var FILE_READ_PATTERNS = [
@@ -88724,8 +88740,6 @@ function createBackgroundOutput(manager, client2) {
     }
   });
 }
-// src/tools/background-task/create-background-task.ts
-init_logger();
 // src/tools/assembly/constants.ts
 var DEFAULT_VOTERS = 3;
 var DEFAULT_ROUNDS = 2;
@@ -91354,7 +91368,7 @@ async function pollSyncSession(ctx, client2, input) {
   let idleStallCount = 0;
   let lastMsgCount = 0;
   let stableIdlePolls = 0;
-  log("[task] Starting poll loop", { sessionID: input.sessionID, agentToUse: input.agentToUse });
+  log("[task] Starting poll loop", { sessionID: input.sessionID, agentToUse: input.agentToUse, maxPollTimeMs });
   while (Date.now() - pollStart < maxPollTimeMs) {
     if (ctx.abort?.aborted) {
       log("[task] Aborted by user", { sessionID: input.sessionID });
@@ -91732,6 +91746,7 @@ async function executeSyncTask(args, ctx, executorCtx, parentContext, agentToUse
   const toastManager = getTaskToastManager();
   let taskId;
   let syncSessionID;
+  let pollTimedOut = false;
   try {
     const createSessionResult = await deps.createSyncSession(client2, {
       parentSessionID: parentContext.sessionID,
@@ -91814,6 +91829,7 @@ async function executeSyncTask(args, ctx, executorCtx, parentContext, agentToUse
         }
       });
       if (pollError) {
+        pollTimedOut = pollError.startsWith("Poll timeout reached");
         return pollError;
       }
       const result = await deps.fetchSyncResult(client2, sessionID, undefined, {
@@ -91851,9 +91867,11 @@ session_id: ${sessionID}
   } finally {
     if (syncSessionID) {
       unregisterSubagentSession(syncSessionID);
-      client2.session.abort({ path: { id: syncSessionID } }).catch((err) => {
-        log("[delegate-task] Sync session abort failed:", err);
-      });
+      if (!pollTimedOut) {
+        client2.session.abort({ path: { id: syncSessionID } }).catch((err) => {
+          log("[delegate-task] Sync session abort failed:", err);
+        });
+      }
     }
   }
 }
@@ -93096,6 +93114,7 @@ function createToolGuardHooks(args) {
   const { ctx, pluginConfig, isHookEnabled, safeHookEnabled } = args;
   const evolutionEnabled = pluginConfig.evolution?.enabled === true;
   const safeHook = (hookName, factory) => safeCreateHook(hookName, factory, { enabled: safeHookEnabled });
+  const backgroundTaskBlocker = isHookEnabled("background-task-blocker") ? safeHook("background-task-blocker", () => createBackgroundTaskBlockerHook()) : null;
   const commentChecker = isHookEnabled("comment-checker") ? safeHook("comment-checker", () => createCommentCheckerHooks(pluginConfig.comment_checker)) : null;
   const toolOutputTruncator = isHookEnabled("tool-output-truncator") ? safeHook("tool-output-truncator", () => createToolOutputTruncatorHook(ctx, { experimental: pluginConfig.experimental })) : null;
   let directoryAgentsInjector = null;
@@ -93129,6 +93148,7 @@ function createToolGuardHooks(args) {
   const taskEditGuard = isHookEnabled("task-edit-guard") ? safeHook("task-edit-guard", () => createTaskEditGuardHook(ctx)) : null;
   const evolutionWatcher = evolutionEnabled && isHookEnabled("evolution-watcher") ? safeHook("evolution-watcher", () => createEvolutionWatcherHook(ctx, pluginConfig.evolution)) : null;
   return {
+    backgroundTaskBlocker,
     commentChecker,
     toolOutputTruncator,
     directoryAgentsInjector,
@@ -93488,6 +93508,10 @@ class ConcurrencyManager {
     return this.queues.get(model)?.length ?? 0;
   }
 }
+// src/features/background-agent/handle-index.ts
+import { existsSync as existsSync73, mkdirSync as mkdirSync19, readdirSync as readdirSync25, readFileSync as readFileSync43, renameSync as renameSync5, unlinkSync as unlinkSync12, writeFileSync as writeFileSync26 } from "fs";
+import { dirname as dirname19, join as join77 } from "path";
+
 // src/features/background-agent/constants.ts
 var TASK_TTL_MS = 30 * 60 * 1000;
 var MIN_STABILITY_TIME_MS2 = 10 * 1000;
@@ -93502,6 +93526,126 @@ var POLLING_INTERVAL_MS = 3000;
 var PRUNE_THROTTLE_MS = 30000;
 var TASK_CLEANUP_DELAY_MS = 10 * 60 * 1000;
 
+// src/features/background-agent/handle-index.ts
+var BG_HANDLE_DIR_NAME = "bg-handles";
+var BG_HANDLE_FILE_PREFIX = "bg_";
+var BgHandleSchema = exports_external.object({
+  taskId: exports_external.string(),
+  parentSessionID: exports_external.string(),
+  parentMessageID: exports_external.string(),
+  description: exports_external.string(),
+  agent: exports_external.string(),
+  status: exports_external.enum(["pending", "running", "completed", "error", "cancelled", "interrupt"]),
+  model: exports_external.object({
+    providerID: exports_external.string(),
+    modelID: exports_external.string(),
+    variant: exports_external.string().optional(),
+    temperature: exports_external.number().optional()
+  }).optional(),
+  category: exports_external.string().optional(),
+  concurrencyGroup: exports_external.string().optional(),
+  queuedAt: exports_external.number().optional(),
+  startedAt: exports_external.number().optional(),
+  completedAt: exports_external.number().optional()
+}).strict();
+function getBgHandleDir(directory) {
+  return join77(directory, ".matrixx", BG_HANDLE_DIR_NAME);
+}
+function getHandlePath(directory, taskId) {
+  return join77(getBgHandleDir(directory), `${taskId}.json`);
+}
+function ensureDir3(dirPath) {
+  if (!existsSync73(dirPath)) {
+    mkdirSync19(dirPath, { recursive: true });
+  }
+}
+function toHandle(task) {
+  return {
+    taskId: task.id,
+    parentSessionID: task.parentSessionID,
+    parentMessageID: task.parentMessageID,
+    description: task.description,
+    agent: task.agent,
+    status: task.status,
+    model: task.model,
+    category: task.category,
+    concurrencyGroup: task.concurrencyGroup,
+    queuedAt: task.queuedAt?.getTime(),
+    startedAt: task.startedAt?.getTime(),
+    completedAt: task.completedAt?.getTime()
+  };
+}
+function writeHandle(directory, task) {
+  const filePath = getHandlePath(directory, task.id);
+  ensureDir3(dirname19(filePath));
+  const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  try {
+    writeFileSync26(tempPath, JSON.stringify(toHandle(task), null, 2), "utf-8");
+    renameSync5(tempPath, filePath);
+  } catch (error95) {
+    try {
+      if (existsSync73(tempPath)) {
+        unlinkSync12(tempPath);
+      }
+    } catch {}
+    throw error95;
+  }
+}
+function readHandleFile(filePath) {
+  try {
+    if (!existsSync73(filePath)) {
+      return null;
+    }
+    const parsed = JSON.parse(readFileSync43(filePath, "utf-8"));
+    const result = BgHandleSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+function readHandles(directory) {
+  const dir = getBgHandleDir(directory);
+  if (!existsSync73(dir)) {
+    return [];
+  }
+  const handles = [];
+  for (const name of readdirSync25(dir)) {
+    if (!name.startsWith(BG_HANDLE_FILE_PREFIX) || !name.endsWith(".json")) {
+      continue;
+    }
+    const handle = readHandleFile(join77(dir, name));
+    if (handle) {
+      handles.push(handle);
+    }
+  }
+  return handles;
+}
+function sweepStaleHandles(directory, ttlMs = TASK_TTL_MS, now = Date.now()) {
+  const dir = getBgHandleDir(directory);
+  if (!existsSync73(dir)) {
+    return 0;
+  }
+  let removed = 0;
+  for (const name of readdirSync25(dir)) {
+    if (!name.startsWith(BG_HANDLE_FILE_PREFIX) || !name.endsWith(".json")) {
+      continue;
+    }
+    const filePath = join77(dir, name);
+    const handle = readHandleFile(filePath);
+    const timestamp = handle?.completedAt ?? handle?.startedAt ?? handle?.queuedAt;
+    if (handle && timestamp !== undefined && now - timestamp <= ttlMs) {
+      continue;
+    }
+    try {
+      unlinkSync12(filePath);
+      removed++;
+    } catch {}
+  }
+  if (removed > 0) {
+    log(`[bg-handles] Swept ${removed} stale handle file(s) from ${dir}`);
+  }
+  return removed;
+}
 // src/features/background-agent/error-helpers.ts
 function getErrorText(error95) {
   if (!error95)
@@ -93604,19 +93748,19 @@ function detectRepetitiveToolUse(window2) {
 }
 
 // src/features/background-agent/message-dir.ts
-import { existsSync as existsSync73, readdirSync as readdirSync25, readFileSync as readFileSync43 } from "fs";
-import { join as join77 } from "path";
+import { existsSync as existsSync74, readdirSync as readdirSync26, readFileSync as readFileSync44 } from "fs";
+import { join as join78 } from "path";
 var MESSAGE_DIR_CACHE_CAP = 1000;
 var messageDirCache = new Map;
 function computeMessageDir(sessionID) {
-  if (!existsSync73(MESSAGE_STORAGE))
+  if (!existsSync74(MESSAGE_STORAGE))
     return null;
-  const directPath = join77(MESSAGE_STORAGE, sessionID);
-  if (existsSync73(directPath))
+  const directPath = join78(MESSAGE_STORAGE, sessionID);
+  if (existsSync74(directPath))
     return directPath;
-  for (const dir of readdirSync25(MESSAGE_STORAGE)) {
-    const sessionPath = join77(MESSAGE_STORAGE, dir, sessionID);
-    if (existsSync73(sessionPath))
+  for (const dir of readdirSync26(MESSAGE_STORAGE)) {
+    const sessionPath = join78(MESSAGE_STORAGE, dir, sessionID);
+    if (existsSync74(sessionPath))
       return sessionPath;
   }
   return null;
@@ -93650,11 +93794,11 @@ function hasPartialAgentOrModel(message) {
 }
 function findNearestMessageExcludingCompaction(messageDir) {
   try {
-    const files = readdirSync25(messageDir).filter((name) => name.endsWith(".json")).sort().reverse();
+    const files = readdirSync26(messageDir).filter((name) => name.endsWith(".json")).sort().reverse();
     const parsedByFile = new Map;
     for (const file3 of files) {
       try {
-        const content = readFileSync43(join77(messageDir, file3), "utf-8");
+        const content = readFileSync44(join78(messageDir, file3), "utf-8");
         const parsed = JSON.parse(content);
         parsedByFile.set(file3, parsed);
         if (hasFullAgentAndModel(parsed)) {
@@ -93802,6 +93946,25 @@ class TaskHistory {
 }
 
 // src/features/background-agent/manager.ts
+function restoreTaskFromHandle(handle) {
+  const interrupted = handle.status === "running" || handle.status === "pending";
+  return {
+    id: handle.taskId,
+    parentSessionID: handle.parentSessionID,
+    parentMessageID: handle.parentMessageID,
+    description: handle.description,
+    prompt: "",
+    agent: handle.agent,
+    status: interrupted ? "interrupt" : handle.status,
+    queuedAt: handle.queuedAt !== undefined ? new Date(handle.queuedAt) : undefined,
+    startedAt: handle.startedAt !== undefined ? new Date(handle.startedAt) : undefined,
+    completedAt: handle.completedAt !== undefined ? new Date(handle.completedAt) : undefined,
+    model: handle.model,
+    category: handle.category,
+    concurrencyGroup: handle.concurrencyGroup
+  };
+}
+
 class BackgroundManager {
   static cleanupManagers = new Set;
   static cleanupRegistered = false;
@@ -93842,6 +94005,28 @@ class BackgroundManager {
     this.enableParentSessionNotifications = options?.enableParentSessionNotifications ?? true;
     this.registerProcessCleanup();
   }
+  persistHandle(task) {
+    try {
+      writeHandle(this.directory, task);
+    } catch (error95) {
+      log("[background-agent] Failed to persist background handle:", { taskId: task.id, error: error95 });
+    }
+  }
+  async restoreHandles() {
+    const swept = sweepStaleHandles(this.directory);
+    const handles = readHandles(this.directory);
+    let restored = 0;
+    for (const handle of handles) {
+      if (this.tasks.has(handle.taskId)) {
+        continue;
+      }
+      this.tasks.set(handle.taskId, restoreTaskFromHandle(handle));
+      restored++;
+    }
+    if (restored > 0 || swept > 0) {
+      log("[background-agent] Restored background handles:", { restored, swept });
+    }
+  }
   async launch(input) {
     log("[background-agent] launch() called with:", {
       agent: input.agent,
@@ -93993,6 +94178,7 @@ class BackgroundManager {
     };
     task.concurrencyKey = concurrencyKey;
     task.concurrencyGroup = concurrencyKey;
+    this.persistHandle(task);
     this.taskHistory.record(input.parentSessionID, { id: task.id, sessionID, agent: input.agent, description: input.description, status: "running", category: input.category, startedAt: task.startedAt });
     this.startPolling();
     log("[background-agent] Launching task:", { taskId: task.id, sessionID, agent: input.agent });
@@ -94044,6 +94230,7 @@ class BackgroundManager {
           existingTask.error = errorMessage;
         }
         existingTask.completedAt = new Date;
+        this.persistHandle(existingTask);
         if (existingTask.concurrencyKey) {
           this.concurrencyManager.release(existingTask.concurrencyKey);
           existingTask.concurrencyKey = undefined;
@@ -94146,6 +94333,7 @@ class BackgroundManager {
       concurrencyGroup
     };
     this.tasks.set(task.id, task);
+    this.persistHandle(task);
     registerSubagentSession(input.sessionID, input.parentSessionID);
     this.startPolling();
     this.taskHistory.record(input.parentSessionID, { id: task.id, sessionID: input.sessionID, agent: input.agent || "task", description: input.description, status: "running", startedAt: task.startedAt });
@@ -94192,6 +94380,7 @@ class BackgroundManager {
       existingTask.parentTools = input.parentTools;
     }
     existingTask.startedAt = new Date;
+    this.persistHandle(existingTask);
     existingTask.progress = {
       toolCalls: existingTask.progress?.toolCalls ?? 0,
       lastUpdate: new Date
@@ -94247,6 +94436,7 @@ class BackgroundManager {
       const errorMessage = error95 instanceof Error ? error95.message : String(error95);
       existingTask.error = errorMessage;
       existingTask.completedAt = new Date;
+      this.persistHandle(existingTask);
       if (existingTask.concurrencyKey) {
         this.concurrencyManager.release(existingTask.concurrencyKey);
         existingTask.concurrencyKey = undefined;
@@ -94411,6 +94601,7 @@ class BackgroundManager {
       task.status = "error";
       task.error = errorMessage ?? "Session error";
       task.completedAt = new Date;
+      this.persistHandle(task);
       this.taskHistory.record(task.parentSessionID, { id: task.id, sessionID: task.sessionID, agent: task.agent, description: task.description, status: "error", category: task.category, startedAt: task.startedAt, completedAt: task.completedAt });
       if (task.concurrencyKey) {
         this.concurrencyManager.release(task.concurrencyKey);
@@ -94579,6 +94770,7 @@ class BackgroundManager {
     }
     task.status = "cancelled";
     task.completedAt = new Date;
+    this.persistHandle(task);
     if (reason) {
       task.error = reason;
     }
@@ -94701,6 +94893,7 @@ class BackgroundManager {
     }
     task.status = "completed";
     task.completedAt = new Date;
+    this.persistHandle(task);
     this.taskHistory.record(task.parentSessionID, { id: task.id, sessionID: task.sessionID, agent: task.agent, description: task.description, status: "completed", category: task.category, startedAt: task.startedAt, completedAt: task.completedAt });
     if (task.concurrencyKey) {
       this.concurrencyManager.release(task.concurrencyKey);
@@ -94833,6 +95026,7 @@ class BackgroundManager {
         task.status = "error";
         task.error = errorMessage;
         task.completedAt = new Date;
+        this.persistHandle(task);
         if (task.concurrencyKey) {
           this.concurrencyManager.release(task.concurrencyKey);
           task.concurrencyKey = undefined;
@@ -94917,6 +95111,7 @@ class BackgroundManager {
         task.status = "cancelled";
         task.error = `Stale timeout (no activity for ${staleMinutes2}min since start)`;
         task.completedAt = new Date;
+        this.persistHandle(task);
         if (task.concurrencyKey) {
           this.concurrencyManager.release(task.concurrencyKey);
           task.concurrencyKey = undefined;
@@ -94945,6 +95140,7 @@ class BackgroundManager {
       task.status = "cancelled";
       task.error = `Stale timeout (no activity for ${staleMinutes}min)`;
       task.completedAt = new Date;
+      this.persistHandle(task);
       if (task.concurrencyKey) {
         this.concurrencyManager.release(task.concurrencyKey);
         task.concurrencyKey = undefined;
@@ -95836,9 +96032,9 @@ class TmuxSessionManager {
 var SESSION_TIMEOUT_MS3 = 10 * 60 * 1000;
 var MIN_STABILITY_TIME_MS4 = 10 * 1000;
 // src/agents/dynamic-agent-prompt-builder.ts
-import { existsSync as existsSync74, readFileSync as readFileSync44 } from "fs";
+import { existsSync as existsSync75, readFileSync as readFileSync45 } from "fs";
 import { homedir as homedir11 } from "os";
-import { join as join78 } from "path";
+import { join as join79 } from "path";
 init_logger();
 function categorizeTools(toolNames) {
   return toolNames.map((name) => {
@@ -96200,24 +96396,24 @@ function exploreCtxPart(hasGrepGlob) {
 function resolveContextModeDisciplinePath() {
   try {
     const resolved = __require.resolve("context-mode/configs/opencode/AGENTS.md");
-    if (existsSync74(resolved))
+    if (existsSync75(resolved))
       return resolved;
   } catch {}
   try {
     const cacheDir = getOpenCodeCacheDir();
-    const p = join78(cacheDir, "packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
-    if (existsSync74(p))
+    const p = join79(cacheDir, "packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
+    if (existsSync75(p))
       return p;
   } catch {}
   try {
-    const base = process.env.XDG_CACHE_HOME ?? join78(homedir11(), ".cache");
-    const p = join78(base, "opencode/packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
-    if (existsSync74(p))
+    const base = process.env.XDG_CACHE_HOME ?? join79(homedir11(), ".cache");
+    const p = join79(base, "opencode/packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
+    if (existsSync75(p))
       return p;
   } catch {}
   try {
-    const p2 = join78(homedir11(), ".cache/opencode/packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
-    if (existsSync74(p2))
+    const p2 = join79(homedir11(), ".cache/opencode/packages/context-mode@latest/node_modules/context-mode/configs/opencode/AGENTS.md");
+    if (existsSync75(p2))
       return p2;
   } catch {}
   return null;
@@ -96235,11 +96431,11 @@ function loadContextModeDiscipline(hasGrepGlob = true) {
     const p = resolveContextModeDisciplinePath();
     if (!p)
       throw new Error("discipline file not found");
-    const raw = readFileSync44(p, "utf8");
+    const raw = readFileSync45(p, "utf8");
     let version4 = "1.0.169";
     try {
       const pkgResolved = __require.resolve("context-mode/package.json");
-      const pkgRaw = readFileSync44(pkgResolved, "utf8");
+      const pkgRaw = readFileSync45(pkgResolved, "utf8");
       const pkg = JSON.parse(pkgRaw);
       if (pkg.version)
         version4 = pkg.version;
@@ -96286,11 +96482,11 @@ function loadCompactContextDiscipline(hasGrepGlob = true) {
     const p = resolveContextModeDisciplinePath();
     if (!p)
       throw new Error("discipline file not found");
-    const raw = readFileSync44(p, "utf8");
+    const raw = readFileSync45(p, "utf8");
     let version4 = "1.0.169";
     try {
       const pkgResolved = __require.resolve("context-mode/package.json");
-      const pkgRaw = readFileSync44(pkgResolved, "utf8");
+      const pkgRaw = readFileSync45(pkgResolved, "utf8");
       const pkg = JSON.parse(pkgRaw);
       if (pkg.version)
         version4 = pkg.version;
@@ -97359,7 +97555,7 @@ function createBddContractAgent(model) {
 createBddContractAgent.mode = MODE2;
 
 // src/agents/builtin-agents/resolve-file-uri.ts
-import { existsSync as existsSync75, readFileSync as readFileSync45 } from "fs";
+import { existsSync as existsSync76, readFileSync as readFileSync46 } from "fs";
 import { homedir as homedir12 } from "os";
 import { isAbsolute as isAbsolute6, resolve as resolve10 } from "path";
 function resolvePromptAppend(promptAppend, configDir) {
@@ -97374,11 +97570,11 @@ function resolvePromptAppend(promptAppend, configDir) {
   } catch {
     return `[WARNING: Malformed file URI (invalid percent-encoding): ${promptAppend}]`;
   }
-  if (!existsSync75(filePath)) {
+  if (!existsSync76(filePath)) {
     return `[WARNING: Could not resolve file URI: ${promptAppend}]`;
   }
   try {
-    return readFileSync45(filePath, "utf8");
+    return readFileSync46(filePath, "utf8");
   } catch {
     return `[WARNING: Could not read file: ${promptAppend}]`;
   }
@@ -99394,8 +99590,8 @@ Step 2: Get commit SHA for permalinks
         cd \${TMPDIR:-/tmp}/repo-name && git rev-parse HEAD
 
 Step 3: Find the implementation
-        - grep/ast_grep_search for function/class
-        - read the specific file
+        - ctx_search / ast_grep_search for function/class \u2014 NOT grep (blocked under enforce:true)
+        - ctx_execute_file for analysis (or read for targeted sections)
         - git blame for context if needed
 
 Step 4: Construct permalink
@@ -100544,8 +100740,8 @@ Your response has **FAILED** if:
 Use the right tool for the job:
 - **Semantic search** (definitions, references): LSP tools
 - **Structural patterns** (function shapes, class structures): ast_grep_search  
-- **Text patterns** (strings, comments, logs): grep (if available; otherwise ctx_search / ast_grep_search)
-- **File patterns** (find by name/extension): glob (if available; otherwise ctx_search / LSP)
+- **Text patterns** (strings, comments, logs): ctx_search (indexed KB) -> ctx_batch_execute / ctx_execute for multi-file analysis. ast_grep_search for structural patterns. grep/glob only as fallback when ctx_* unavailable.
+- **File patterns** (find by name/extension): ctx_search (indexed KB) -> LSP / ast_grep_search. glob only as fallback when ctx_* unavailable.
 - **History/evolution** (when added, who changed): git commands
 
 Flood with parallel calls. Cross-validate findings across multiple tools.`
@@ -100743,6 +100939,13 @@ This will:
 5. **Seraph Before Plan** - Always catch gaps before committing to plan
 6. **Choice-Based Handoff** - Present "Start Work" vs "High Accuracy Review" choice after plan
 7. **Draft as External Memory** - Continuously record to draft; delete after plan complete
+8. **Background-First Delegation** - Default to \`run_in_background=true\` for every delegation; never nest a blocking subagent call inside an already-blocking session
+
+### Delegation Policy (MANDATORY)
+
+- **Default to background mode**: every Oracle delegation passes \`run_in_background=true\`.
+- **Never nest a blocking subagent call** (\`run_in_background=false\`) inside an already-blocking session. Oracle may itself run under a fixed poll budget (default 600s); a nested blocking call consumes that budget and stalls at the timeout.
+- **Use sequential top-level calls instead**: fire the delegation in background, return to your work, then collect the result with \`background_output(task_id=...)\`.
 
 ---
 
@@ -100776,12 +100979,14 @@ var ORACLE_HIGH_ACCURACY_MODE = `# PHASE 3: PLAN GENERATION
 \`\`\`typescript
 // After generating initial plan
 while (true) {
-  const result = task(
+  // Fire Smith in background (never a blocking nested call), then collect its verdict.
+  const smithTask = task(
     subagent_type="smith",
     load_skills=[],
     prompt=".matrixx/plans/{name}.md",
-    run_in_background=false
+    run_in_background=true
   )
+  const result = background_output(task_id=smithTask.task_id)
 
   if (result.verdict === "OKAY") {
     break // Plan approved - exit loop
@@ -101386,7 +101591,7 @@ task(subagent_type="operator", load_skills=[], prompt="I'm designing architectur
 
 **Oracle Consultation** (recommend when stakes are high):
 \`\`\`typescript
-task(subagent_type="oracle", load_skills=[], prompt="Architecture consultation needed: [context]...", run_in_background=false)
+task(subagent_type="oracle", load_skills=[], prompt="Architecture consultation needed: [context]...", run_in_background=true)
 \`\`\`
 
 **Interview Focus:**
@@ -101548,12 +101753,14 @@ todoWrite([
 
 > **Edge \u2014 Trivial/Simple bypass:** If complexity is 1-2 (Trivial/Simple) and the request is ambiguous but single-scope (one domain, no architectural keywords), **bypass Seraph** and ask directly per Morpheus Phase 0 (ask ONE clarifying question).
 
-If gate **passes**, summon Seraph:
+If gate **passes**, summon Seraph in **background mode** (never blocking \u2014 see policy below):
 
 \`\`\`typescript
-task(
+// Fire Seraph in background \u2014 NEVER run_in_background=false from this session.
+const seraphTask = task(
   subagent_type="seraph",
   load_skills=[],
+  run_in_background=true,
   prompt=\`Review this planning session before I generate the work plan:
 
   **User's Goal**: {summarize what user wants}
@@ -101573,11 +101780,18 @@ task(
   3. Potential scope creep areas to lock down
   4. Assumptions I'm making that need validation
   5. Missing acceptance criteria
-  6. Edge cases not addressed\`,
-  run_in_background=false
+  6. Edge cases not addressed\`
 )
+
+// Continue drafting/other work, then collect once when needed:
+const seraphReview = background_output(task_id=seraphTask.task_id)
 \`\`\`
 
+> **NO-BLOCKING-NESTING POLICY (MANDATORY \u2014 applies to EVERY Oracle delegation):**
+> - **Default to background mode**: always pass \`run_in_background=true\`. Oracle's own invocations default to background; blocking is never the default.
+> - **Never nest a blocking subagent call** (\`run_in_background=false\`) inside your own session. Oracle may itself be running inside a fixed poll budget (default 600s); a blocking nested call consumes that same budget and stalls at the timeout.
+> - **Use sequential top-level calls instead**: fire the delegation in background, return to your work, then collect the result with \`background_output(task_id=...)\`. If a result is required before proceeding, collect it once and continue \u2014 never block on a nested subagent.
+
 If gate **does NOT pass**, skip Seraph and proceed directly to plan generation (note \`Seraph bypassed: complexity=X / no multi-component signal\` in summary).
 
 ## Post-Seraph: Auto-Generate Plan and Summarize
@@ -101923,7 +102137,7 @@ Parallel Speedup: ~40% faster than sequential
 
 | Wave | Tasks | Recommended Agents |
 |------|-------|-------------------|
-| 1 | 1, 5 | task(category="...", load_skills=[...], run_in_background=false) |
+| 1 | 1, 5 | task(category="...", load_skills=[...], run_in_background=true) |
 | 2 | 2, 3, 6 | dispatch parallel after Wave 1 completes |
 | 3 | 4 | final integration task |
 
@@ -103268,6 +103482,9 @@ function createManagers(args) {
     },
     enableParentSessionNotifications: backgroundNotificationHookEnabled
   });
+  backgroundManager.restoreHandles().catch((error95) => {
+    log("[index] Failed to restore background handles:", error95);
+  });
   initTaskToastManager(ctx.client);
   const configHandler = createConfigHandler({
     ctx: { directory: ctx.directory, client: ctx.client },
@@ -103809,6 +104026,7 @@ var HookNameEnum = exports_external.enum([
   "preemptive-compaction",
   "rules-injector",
   "background-notification",
+  "background-task-blocker",
   "auto-update-checker",
   "startup-toast",
   "keyword-detector",
@@ -103878,8 +104096,12 @@ var MatrixxSelfConfigSkillConfigSchema = exports_external.object({
 var providerModelSchema = exports_external.string().refine((s) => {
   if (!s.includes("/"))
     return false;
+  if (s.startsWith("/") || s.endsWith("/"))
+    return false;
+  if (s.includes("//"))
+    return false;
   const parts = s.split("/");
-  return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
+  return parts.length >= 2 && parts.every((p) => p.length > 0);
 }, { message: "Must be <provider>/<model>" });
 var ModelPresetEntrySchema = exports_external.object({
   model: providerModelSchema,
@@ -104794,6 +105016,7 @@ function createToolExecuteBeforeHandler2(args) {
   const taskEditGuardHook = hooks2.taskEditGuard?.["tool.execute.before"];
   const tasksTodowriteDisablerHook = hooks2.tasksTodowriteDisabler?.["tool.execute.before"];
   const oracleMdOnlyHook = hooks2.oracleMdOnly?.["tool.execute.before"];
+  const backgroundTaskBlockerHook = hooks2.backgroundTaskBlocker?.["tool.execute.before"];
   const contextModeEnforcerHook = hooks2.contextModeEnforcer?.["tool.execute.before"];
   const nonInteractiveEnvHook = hooks2.nonInteractiveEnv?.["tool.execute.before"];
   const bashFileReadGuardHook = hooks2.bashFileReadGuard?.["tool.execute.before"];
@@ -104814,7 +105037,8 @@ function createToolExecuteBeforeHandler2(args) {
       taskEditGuardHook?.(input, output),
       tasksTodowriteDisablerHook?.(input, output),
       oracleMdOnlyHook?.(input, output),
-      contextModeEnforcerHook?.(input, output)
+      contextModeEnforcerHook?.(input, output),
+      backgroundTaskBlockerHook?.(input, output)
     ]);
     let resolvePromise;
     if (input.tool === "task") {