@probelabs/probe 0.6.0-rc230 → 0.6.0-rc232

package/build/agent/ProbeAgent.js

@@ -357,6 +357,10 @@ export class ProbeAgent {
     // Each ProbeAgent instance has its own limits, not shared globally
     this.delegationManager = new DelegationManager();
 
+    // Optional global concurrency limiter shared across all ProbeAgent instances.
+    // When set, every AI API call acquires a slot before calling the provider.
+    this.concurrencyLimiter = options.concurrencyLimiter || null;
+
     // Request timeout configuration (default 2 minutes)
     // Validates env var to prevent NaN or unreasonable values
     this.requestTimeout = options.requestTimeout ?? (() => {
@@ -824,6 +828,7 @@ export class ProbeAgent {
       provider: this.clientApiProvider,
       model: this.clientApiModel,
       delegationManager: this.delegationManager,  // Per-instance delegation limits
+      concurrencyLimiter: this.concurrencyLimiter,  // Global AI concurrency limiter
       isToolAllowed
     };
 
@@ -1363,6 +1368,16 @@ export class ProbeAgent {
    * @private
    */
   async streamTextWithRetryAndFallback(options) {
+    // Acquire global concurrency slot if limiter is configured
+    const limiter = this.concurrencyLimiter;
+    if (limiter) {
+      await limiter.acquire(null);
+      if (this.debug) {
+        const stats = limiter.getStats();
+        console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+      }
+    }
+
     // Create AbortController for overall operation timeout
     const controller = new AbortController();
     const timeoutState = { timeoutId: null };
@@ -1382,12 +1397,10 @@ export class ProbeAgent {
       const useClaudeCode = this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true';
       const useCodex = this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true';
 
+      let result;
       if (useClaudeCode || useCodex) {
         try {
-          const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-          if (result) {
-            return result;
-          }
+          result = await this._tryEngineStreamPath(options, controller, timeoutState);
         } catch (error) {
           if (this.debug) {
             const engineType = useClaudeCode ? 'Claude Code' : 'Codex';
@@ -1397,8 +1410,43 @@ export class ProbeAgent {
         }
       }
 
-      // Use Vercel AI SDK with retry/fallback
-      return await this._executeWithVercelProvider(options, controller);
+      if (!result) {
+        // Use Vercel AI SDK with retry/fallback
+        result = await this._executeWithVercelProvider(options, controller);
+      }
+
+      // Wrap textStream so limiter slot is held until stream completes
+      if (limiter && result.textStream) {
+        const originalStream = result.textStream;
+        const debug = this.debug;
+        result.textStream = (async function* () {
+          try {
+            for await (const chunk of originalStream) {
+              yield chunk;
+            }
+          } finally {
+            limiter.release(null);
+            if (debug) {
+              const stats = limiter.getStats();
+              console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+            }
+          }
+        })();
+      } else if (limiter) {
+        // No textStream (shouldn't happen, but release just in case)
+        limiter.release(null);
+      }
+
+      return result;
+    } catch (error) {
+      // Release on error if limiter was acquired
+      if (limiter) {
+        limiter.release(null);
+        if (this.debug) {
+          console.log(`[DEBUG] Released global AI concurrency slot on error`);
+        }
+      }
+      throw error;
     } finally {
       // Clean up timeout (for non-engine paths; engine paths clean up in the generator)
       if (timeoutState.timeoutId) {
@@ -2496,10 +2544,9 @@ ${extractGuidance}
       toolDefinitions += `${taskToolDefinition}\n`;
     }
 
-    // Always include attempt_completion (unless explicitly disabled in raw AI mode)
-    if (isToolAllowed('attempt_completion')) {
-      toolDefinitions += `${attemptCompletionToolDefinition}\n`;
-    }
+    // Always include attempt_completion unconditionally - it's a completion signal, not a tool
+    // This ensures agents can always complete their work, regardless of tool restrictions
+    toolDefinitions += `${attemptCompletionToolDefinition}\n`;
 
     // Delegate tool (require both enableDelegate flag AND allowedTools permission)
     // Place after attempt_completion as it's an optional tool
@@ -3304,8 +3351,9 @@ Follow these instructions carefully:
           if (this.enableSkills && this.allowedTools.isEnabled('listSkills')) validTools.push('listSkills');
           if (this.enableSkills && this.allowedTools.isEnabled('useSkill')) validTools.push('useSkill');
           if (this.allowedTools.isEnabled('readImage')) validTools.push('readImage');
-          // Always allow attempt_completion - it's a completion signal, not a tool
+          // Always allow attempt_completion in validTools - it's a completion signal, not a tool
           // This ensures agents can complete even when disableTools: true is set (fixes #333)
+          // The tool DEFINITION may be hidden in raw AI mode, but we still need to recognize it
           validTools.push('attempt_completion');
 
           // Edit tools (require both allowEdit flag AND allowedTools permission)

package/build/agent/index.js

@@ -3859,8 +3859,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -3936,8 +3938,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -4034,10 +4038,10 @@ var init_delegate = __esm({
     "use strict";
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];
@@ -9199,7 +9203,15 @@ function createTaskTool(options = {}) {
           });
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        let tasks = rawTasks;
+        if (typeof rawTasks === "string") {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e) {
+            return `Error: Invalid tasks JSON - ${e.message}`;
+          }
+        }
         switch (action) {
           case "create": {
             if (tasks && Array.isArray(tasks)) {
@@ -9374,7 +9386,8 @@ var init_taskTool = __esm({
     });
     taskSchema = external_exports.object({
       action: external_exports.enum(["create", "update", "complete", "delete", "list"]),
-      tasks: external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])).optional(),
+      // Accept both array and JSON string (AI models sometimes serialize as string)
+      tasks: external_exports.union([external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])), external_exports.string()]).optional(),
       id: external_exports.string().optional(),
       title: external_exports.string().optional(),
       description: external_exports.string().optional(),
@@ -9485,6 +9498,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" \u2192 ONE task (same type of fix across files)
+- "Update API + tests + docs" \u2192 THREE tasks (different types of work)
+- "Implement feature in 5 files" \u2192 ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file \u274C
+- One task per function \u274C
+- One task per repository (when same type of work) \u274C
+
+**Good patterns**:
+- One task per distinct deliverable \u2713
+- One task per phase (implement, test, document) \u2713
+- One task per different type of work \u2713
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected \u2192 Add new tasks
 - A single task covers too much scope \u2192 Split into smaller tasks
@@ -55823,6 +55855,7 @@ var require_pattern = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     var code_1 = require_code2();
+    var util_1 = require_util3();
     var codegen_1 = require_codegen();
     var error = {
       message: ({ schemaCode }) => (0, codegen_1.str)`must match pattern "${schemaCode}"`,
@@ -55835,10 +55868,18 @@ var require_pattern = __commonJS({
       $data: true,
       error,
       code(cxt) {
-        const { data, $data, schema, schemaCode, it } = cxt;
+        const { gen, data, $data, schema, schemaCode, it } = cxt;
         const u = it.opts.unicodeRegExp ? "u" : "";
-        const regExp = $data ? (0, codegen_1._)`(new RegExp(${schemaCode}, ${u}))` : (0, code_1.usePattern)(cxt, schema);
-        cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+        if ($data) {
+          const { regExp } = it.opts.code;
+          const regExpCode = regExp.code === "new RegExp" ? (0, codegen_1._)`new RegExp` : (0, util_1.useFunc)(gen, regExp);
+          const valid = gen.let("valid");
+          gen.try(() => gen.assign(valid, (0, codegen_1._)`${regExpCode}(${schemaCode}, ${u}).test(${data})`), () => gen.assign(valid, false));
+          cxt.fail$data((0, codegen_1._)`!${valid}`);
+        } else {
+          const regExp = (0, code_1.usePattern)(cxt, schema);
+          cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+        }
       }
     };
     exports2.default = def;
@@ -70535,6 +70576,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -70911,6 +70953,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -71332,6 +71376,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -71345,12 +71397,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -71358,7 +71408,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);
@@ -72250,10 +72330,8 @@ Workspace: ${this.allowedFolders.join(", ")}`;
           toolDefinitions += `${taskToolDefinition}
 `;
         }
-        if (isToolAllowed("attempt_completion")) {
-          toolDefinitions += `${attemptCompletionToolDefinition}
+        toolDefinitions += `${attemptCompletionToolDefinition}
 `;
-        }
         if (this.enableDelegate && isToolAllowed("delegate")) {
           toolDefinitions += `${delegateToolDefinition}
 `;

package/build/agent/tasks/taskTool.js

@@ -23,7 +23,8 @@ export const taskItemSchema = z.object({
  */
 export const taskSchema = z.object({
   action: z.enum(['create', 'update', 'complete', 'delete', 'list']),
-  tasks: z.array(z.union([z.string(), taskItemSchema])).optional(),
+  // Accept both array and JSON string (AI models sometimes serialize as string)
+  tasks: z.union([z.array(z.union([z.string(), taskItemSchema])), z.string()]).optional(),
   id: z.string().optional(),
   title: z.string().optional(),
   description: z.string().optional(),
@@ -142,6 +143,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" → ONE task (same type of fix across files)
+- "Update API + tests + docs" → THREE tasks (different types of work)
+- "Implement feature in 5 files" → ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file ❌
+- One task per function ❌
+- One task per repository (when same type of work) ❌
+
+**Good patterns**:
+- One task per distinct deliverable ✓
+- One task per phase (implement, test, document) ✓
+- One task per different type of work ✓
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected → Add new tasks
 - A single task covers too much scope → Split into smaller tasks
@@ -314,7 +334,17 @@ export function createTaskTool(options = {}) {
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
 
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+
+        // Parse tasks if passed as JSON string (common AI model behavior)
+        let tasks = rawTasks;
+        if (typeof rawTasks === 'string') {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e) {
+            return `Error: Invalid tasks JSON - ${e.message}`;
+          }
+        }
 
         switch (action) {
           case 'create': {

package/build/delegate.js

@@ -19,11 +19,14 @@ import { ProbeAgent } from './agent/ProbeAgent.js';
  * - For long-running processes, periodic cleanup of stale sessions may be needed
  */
 class DelegationManager {
-	constructor() {
-		this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
-		this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
+	constructor(options = {}) {
+		this.maxConcurrent = options.maxConcurrent
+			?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
+		this.maxPerSession = options.maxPerSession
+			?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
 		// Default queue timeout: 60 seconds. Set DELEGATION_QUEUE_TIMEOUT=0 to disable.
-		this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
+		this.defaultQueueTimeout = options.queueTimeout
+			?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
 
 		// Track delegations per session with timestamp for potential TTL cleanup
 		// Map<string, { count: number, lastUpdated: number }>
@@ -353,6 +356,7 @@ const DEFAULT_DELEGATE_TIMEOUT = parseInt(process.env.DELEGATE_TIMEOUT, 10) || 3
  * @param {boolean} [options.enableMcp=false] - Enable MCP tool integration (inherited from parent)
  * @param {Object} [options.mcpConfig] - MCP configuration object (inherited from parent)
  * @param {string} [options.mcpConfigPath] - Path to MCP configuration file (inherited from parent)
+ * @param {Object} [options.concurrencyLimiter=null] - Global AI concurrency limiter (DelegationManager instance)
  * @returns {Promise<string>} The response from the delegate agent
  */
 export async function delegate({
@@ -379,7 +383,8 @@ export async function delegate({
 	enableMcp = false,
 	mcpConfig = null,
 	mcpConfigPath = null,
-	delegationManager = null  // Optional per-instance manager, falls back to default singleton
+	delegationManager = null,  // Optional per-instance manager, falls back to default singleton
+	concurrencyLimiter = null  // Optional global AI concurrency limiter
 }) {
 	if (!task || typeof task !== 'string') {
 		throw new Error('Task parameter is required and must be a string');
@@ -464,7 +469,8 @@ export async function delegate({
 			enableTasks, // Inherit from parent (subagent gets isolated TaskManager)
 			enableMcp,   // Inherit from parent (subagent creates own MCPXmlBridge)
 			mcpConfig,   // Inherit from parent
-			mcpConfigPath // Inherit from parent
+			mcpConfigPath, // Inherit from parent
+			concurrencyLimiter // Inherit global AI concurrency limiter
 		});
 
 		if (debug) {

package/cjs/agent/ProbeAgent.cjs

@@ -30969,8 +30969,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -31046,8 +31048,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -31145,10 +31149,10 @@ var init_delegate = __esm({
     import_crypto2 = require("crypto");
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];
@@ -36310,7 +36314,15 @@ function createTaskTool(options = {}) {
           });
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        let tasks = rawTasks;
+        if (typeof rawTasks === "string") {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e4) {
+            return `Error: Invalid tasks JSON - ${e4.message}`;
+          }
+        }
         switch (action) {
           case "create": {
             if (tasks && Array.isArray(tasks)) {
@@ -36485,7 +36497,8 @@ var init_taskTool = __esm({
     });
     taskSchema = external_exports.object({
       action: external_exports.enum(["create", "update", "complete", "delete", "list"]),
-      tasks: external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])).optional(),
+      // Accept both array and JSON string (AI models sometimes serialize as string)
+      tasks: external_exports.union([external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])), external_exports.string()]).optional(),
       id: external_exports.string().optional(),
       title: external_exports.string().optional(),
       description: external_exports.string().optional(),
@@ -36596,6 +36609,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" \u2192 ONE task (same type of fix across files)
+- "Update API + tests + docs" \u2192 THREE tasks (different types of work)
+- "Implement feature in 5 files" \u2192 ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file \u274C
+- One task per function \u274C
+- One task per repository (when same type of work) \u274C
+
+**Good patterns**:
+- One task per distinct deliverable \u2713
+- One task per phase (implement, test, document) \u2713
+- One task per different type of work \u2713
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected \u2192 Add new tasks
 - A single task covers too much scope \u2192 Split into smaller tasks
@@ -82501,6 +82533,7 @@ var require_pattern = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     var code_1 = require_code2();
+    var util_1 = require_util3();
     var codegen_1 = require_codegen();
     var error2 = {
       message: ({ schemaCode }) => (0, codegen_1.str)`must match pattern "${schemaCode}"`,
@@ -82513,10 +82546,18 @@ var require_pattern = __commonJS({
       $data: true,
       error: error2,
       code(cxt) {
-        const { data: data2, $data, schema, schemaCode, it } = cxt;
+        const { gen, data: data2, $data, schema, schemaCode, it } = cxt;
         const u4 = it.opts.unicodeRegExp ? "u" : "";
-        const regExp = $data ? (0, codegen_1._)`(new RegExp(${schemaCode}, ${u4}))` : (0, code_1.usePattern)(cxt, schema);
-        cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data2})`);
+        if ($data) {
+          const { regExp } = it.opts.code;
+          const regExpCode = regExp.code === "new RegExp" ? (0, codegen_1._)`new RegExp` : (0, util_1.useFunc)(gen, regExp);
+          const valid = gen.let("valid");
+          gen.try(() => gen.assign(valid, (0, codegen_1._)`${regExpCode}(${schemaCode}, ${u4}).test(${data2})`), () => gen.assign(valid, false));
+          cxt.fail$data((0, codegen_1._)`!${valid}`);
+        } else {
+          const regExp = (0, code_1.usePattern)(cxt, schema);
+          cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data2})`);
+        }
       }
     };
     exports2.default = def;
@@ -97212,6 +97253,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -97588,6 +97630,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -98009,6 +98053,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -98022,12 +98074,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error2) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -98035,7 +98085,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error2) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error2;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);
@@ -98927,10 +99007,8 @@ Workspace: ${this.allowedFolders.join(", ")}`;
           toolDefinitions += `${taskToolDefinition}
 `;
         }
-        if (isToolAllowed("attempt_completion")) {
-          toolDefinitions += `${attemptCompletionToolDefinition}
+        toolDefinitions += `${attemptCompletionToolDefinition}
 `;
-        }
         if (this.enableDelegate && isToolAllowed("delegate")) {
           toolDefinitions += `${delegateToolDefinition}
 `;

package/cjs/index.cjs

@@ -35480,7 +35480,15 @@ function createTaskTool(options = {}) {
           });
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        let tasks = rawTasks;
+        if (typeof rawTasks === "string") {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e4) {
+            return `Error: Invalid tasks JSON - ${e4.message}`;
+          }
+        }
         switch (action) {
           case "create": {
             if (tasks && Array.isArray(tasks)) {
@@ -35655,7 +35663,8 @@ var init_taskTool = __esm({
     });
     taskSchema = external_exports.object({
       action: external_exports.enum(["create", "update", "complete", "delete", "list"]),
-      tasks: external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])).optional(),
+      // Accept both array and JSON string (AI models sometimes serialize as string)
+      tasks: external_exports.union([external_exports.array(external_exports.union([external_exports.string(), taskItemSchema])), external_exports.string()]).optional(),
       id: external_exports.string().optional(),
       title: external_exports.string().optional(),
       description: external_exports.string().optional(),
@@ -35766,6 +35775,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" \u2192 ONE task (same type of fix across files)
+- "Update API + tests + docs" \u2192 THREE tasks (different types of work)
+- "Implement feature in 5 files" \u2192 ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file \u274C
+- One task per function \u274C
+- One task per repository (when same type of work) \u274C
+
+**Good patterns**:
+- One task per distinct deliverable \u2713
+- One task per phase (implement, test, document) \u2713
+- One task per different type of work \u2713
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected \u2192 Add new tasks
 - A single task covers too much scope \u2192 Split into smaller tasks
@@ -79234,6 +79262,7 @@ var require_pattern = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     var code_1 = require_code2();
+    var util_1 = require_util3();
     var codegen_1 = require_codegen();
     var error2 = {
       message: ({ schemaCode }) => (0, codegen_1.str)`must match pattern "${schemaCode}"`,
@@ -79246,10 +79275,18 @@ var require_pattern = __commonJS({
       $data: true,
       error: error2,
       code(cxt) {
-        const { data: data2, $data, schema, schemaCode, it } = cxt;
+        const { gen, data: data2, $data, schema, schemaCode, it } = cxt;
         const u4 = it.opts.unicodeRegExp ? "u" : "";
-        const regExp = $data ? (0, codegen_1._)`(new RegExp(${schemaCode}, ${u4}))` : (0, code_1.usePattern)(cxt, schema);
-        cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data2})`);
+        if ($data) {
+          const { regExp } = it.opts.code;
+          const regExpCode = regExp.code === "new RegExp" ? (0, codegen_1._)`new RegExp` : (0, util_1.useFunc)(gen, regExp);
+          const valid = gen.let("valid");
+          gen.try(() => gen.assign(valid, (0, codegen_1._)`${regExpCode}(${schemaCode}, ${u4}).test(${data2})`), () => gen.assign(valid, false));
+          cxt.fail$data((0, codegen_1._)`!${valid}`);
+        } else {
+          const regExp = (0, code_1.usePattern)(cxt, schema);
+          cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data2})`);
+        }
       }
     };
     exports2.default = def;
@@ -93945,6 +93982,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -94321,6 +94359,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -94742,6 +94782,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -94755,12 +94803,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error2) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -94768,7 +94814,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error2) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error2;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);
@@ -95660,10 +95736,8 @@ Workspace: ${this.allowedFolders.join(", ")}`;
           toolDefinitions += `${taskToolDefinition}
 `;
         }
-        if (isToolAllowed("attempt_completion")) {
-          toolDefinitions += `${attemptCompletionToolDefinition}
+        toolDefinitions += `${attemptCompletionToolDefinition}
 `;
-        }
         if (this.enableDelegate && isToolAllowed("delegate")) {
           toolDefinitions += `${delegateToolDefinition}
 `;
@@ -97604,8 +97678,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -97681,8 +97757,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -97780,10 +97858,10 @@ var init_delegate = __esm({
     import_crypto9 = require("crypto");
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc230",
+  "version": "0.6.0-rc232",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -79,7 +79,7 @@
     "@ai-sdk/openai": "^2.0.10",
     "@anthropic-ai/claude-agent-sdk": "^0.1.46",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@probelabs/maid": "^0.0.23",
+    "@probelabs/maid": "^0.0.24",
     "adm-zip": "^0.5.16",
     "ai": "^5.0.0",
     "ajv": "^8.17.1",

package/src/agent/ProbeAgent.js

@@ -357,6 +357,10 @@ export class ProbeAgent {
     // Each ProbeAgent instance has its own limits, not shared globally
     this.delegationManager = new DelegationManager();
 
+    // Optional global concurrency limiter shared across all ProbeAgent instances.
+    // When set, every AI API call acquires a slot before calling the provider.
+    this.concurrencyLimiter = options.concurrencyLimiter || null;
+
     // Request timeout configuration (default 2 minutes)
     // Validates env var to prevent NaN or unreasonable values
     this.requestTimeout = options.requestTimeout ?? (() => {
@@ -824,6 +828,7 @@ export class ProbeAgent {
       provider: this.clientApiProvider,
       model: this.clientApiModel,
       delegationManager: this.delegationManager,  // Per-instance delegation limits
+      concurrencyLimiter: this.concurrencyLimiter,  // Global AI concurrency limiter
       isToolAllowed
     };
 
@@ -1363,6 +1368,16 @@ export class ProbeAgent {
    * @private
    */
   async streamTextWithRetryAndFallback(options) {
+    // Acquire global concurrency slot if limiter is configured
+    const limiter = this.concurrencyLimiter;
+    if (limiter) {
+      await limiter.acquire(null);
+      if (this.debug) {
+        const stats = limiter.getStats();
+        console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+      }
+    }
+
     // Create AbortController for overall operation timeout
     const controller = new AbortController();
     const timeoutState = { timeoutId: null };
@@ -1382,12 +1397,10 @@ export class ProbeAgent {
       const useClaudeCode = this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true';
       const useCodex = this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true';
 
+      let result;
       if (useClaudeCode || useCodex) {
         try {
-          const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-          if (result) {
-            return result;
-          }
+          result = await this._tryEngineStreamPath(options, controller, timeoutState);
         } catch (error) {
           if (this.debug) {
             const engineType = useClaudeCode ? 'Claude Code' : 'Codex';
@@ -1397,8 +1410,43 @@ export class ProbeAgent {
         }
       }
 
-      // Use Vercel AI SDK with retry/fallback
-      return await this._executeWithVercelProvider(options, controller);
+      if (!result) {
+        // Use Vercel AI SDK with retry/fallback
+        result = await this._executeWithVercelProvider(options, controller);
+      }
+
+      // Wrap textStream so limiter slot is held until stream completes
+      if (limiter && result.textStream) {
+        const originalStream = result.textStream;
+        const debug = this.debug;
+        result.textStream = (async function* () {
+          try {
+            for await (const chunk of originalStream) {
+              yield chunk;
+            }
+          } finally {
+            limiter.release(null);
+            if (debug) {
+              const stats = limiter.getStats();
+              console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+            }
+          }
+        })();
+      } else if (limiter) {
+        // No textStream (shouldn't happen, but release just in case)
+        limiter.release(null);
+      }
+
+      return result;
+    } catch (error) {
+      // Release on error if limiter was acquired
+      if (limiter) {
+        limiter.release(null);
+        if (this.debug) {
+          console.log(`[DEBUG] Released global AI concurrency slot on error`);
+        }
+      }
+      throw error;
     } finally {
       // Clean up timeout (for non-engine paths; engine paths clean up in the generator)
       if (timeoutState.timeoutId) {
@@ -2496,10 +2544,9 @@ ${extractGuidance}
       toolDefinitions += `${taskToolDefinition}\n`;
     }
 
-    // Always include attempt_completion (unless explicitly disabled in raw AI mode)
-    if (isToolAllowed('attempt_completion')) {
-      toolDefinitions += `${attemptCompletionToolDefinition}\n`;
-    }
+    // Always include attempt_completion unconditionally - it's a completion signal, not a tool
+    // This ensures agents can always complete their work, regardless of tool restrictions
+    toolDefinitions += `${attemptCompletionToolDefinition}\n`;
 
     // Delegate tool (require both enableDelegate flag AND allowedTools permission)
     // Place after attempt_completion as it's an optional tool
@@ -3304,8 +3351,9 @@ Follow these instructions carefully:
           if (this.enableSkills && this.allowedTools.isEnabled('listSkills')) validTools.push('listSkills');
           if (this.enableSkills && this.allowedTools.isEnabled('useSkill')) validTools.push('useSkill');
           if (this.allowedTools.isEnabled('readImage')) validTools.push('readImage');
-          // Always allow attempt_completion - it's a completion signal, not a tool
+          // Always allow attempt_completion in validTools - it's a completion signal, not a tool
           // This ensures agents can complete even when disableTools: true is set (fixes #333)
+          // The tool DEFINITION may be hidden in raw AI mode, but we still need to recognize it
           validTools.push('attempt_completion');
 
           // Edit tools (require both allowEdit flag AND allowedTools permission)

package/src/agent/tasks/taskTool.js

@@ -23,7 +23,8 @@ export const taskItemSchema = z.object({
  */
 export const taskSchema = z.object({
   action: z.enum(['create', 'update', 'complete', 'delete', 'list']),
-  tasks: z.array(z.union([z.string(), taskItemSchema])).optional(),
+  // Accept both array and JSON string (AI models sometimes serialize as string)
+  tasks: z.union([z.array(z.union([z.string(), taskItemSchema])), z.string()]).optional(),
   id: z.string().optional(),
   title: z.string().optional(),
   description: z.string().optional(),
@@ -142,6 +143,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" → ONE task (same type of fix across files)
+- "Update API + tests + docs" → THREE tasks (different types of work)
+- "Implement feature in 5 files" → ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file ❌
+- One task per function ❌
+- One task per repository (when same type of work) ❌
+
+**Good patterns**:
+- One task per distinct deliverable ✓
+- One task per phase (implement, test, document) ✓
+- One task per different type of work ✓
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected → Add new tasks
 - A single task covers too much scope → Split into smaller tasks
@@ -314,7 +334,17 @@ export function createTaskTool(options = {}) {
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
 
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+
+        // Parse tasks if passed as JSON string (common AI model behavior)
+        let tasks = rawTasks;
+        if (typeof rawTasks === 'string') {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e) {
+            return `Error: Invalid tasks JSON - ${e.message}`;
+          }
+        }
 
         switch (action) {
           case 'create': {

package/src/delegate.js

@@ -19,11 +19,14 @@ import { ProbeAgent } from './agent/ProbeAgent.js';
  * - For long-running processes, periodic cleanup of stale sessions may be needed
  */
 class DelegationManager {
-	constructor() {
-		this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
-		this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
+	constructor(options = {}) {
+		this.maxConcurrent = options.maxConcurrent
+			?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
+		this.maxPerSession = options.maxPerSession
+			?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
 		// Default queue timeout: 60 seconds. Set DELEGATION_QUEUE_TIMEOUT=0 to disable.
-		this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
+		this.defaultQueueTimeout = options.queueTimeout
+			?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
 
 		// Track delegations per session with timestamp for potential TTL cleanup
 		// Map<string, { count: number, lastUpdated: number }>
@@ -353,6 +356,7 @@ const DEFAULT_DELEGATE_TIMEOUT = parseInt(process.env.DELEGATE_TIMEOUT, 10) || 3
  * @param {boolean} [options.enableMcp=false] - Enable MCP tool integration (inherited from parent)
  * @param {Object} [options.mcpConfig] - MCP configuration object (inherited from parent)
  * @param {string} [options.mcpConfigPath] - Path to MCP configuration file (inherited from parent)
+ * @param {Object} [options.concurrencyLimiter=null] - Global AI concurrency limiter (DelegationManager instance)
  * @returns {Promise<string>} The response from the delegate agent
  */
 export async function delegate({
@@ -379,7 +383,8 @@ export async function delegate({
 	enableMcp = false,
 	mcpConfig = null,
 	mcpConfigPath = null,
-	delegationManager = null  // Optional per-instance manager, falls back to default singleton
+	delegationManager = null,  // Optional per-instance manager, falls back to default singleton
+	concurrencyLimiter = null  // Optional global AI concurrency limiter
 }) {
 	if (!task || typeof task !== 'string') {
 		throw new Error('Task parameter is required and must be a string');
@@ -464,7 +469,8 @@ export async function delegate({
 			enableTasks, // Inherit from parent (subagent gets isolated TaskManager)
 			enableMcp,   // Inherit from parent (subagent creates own MCPXmlBridge)
 			mcpConfig,   // Inherit from parent
-			mcpConfigPath // Inherit from parent
+			mcpConfigPath, // Inherit from parent
+			concurrencyLimiter // Inherit global AI concurrency limiter
 		});
 
 		if (debug) {