@swarmclawai/swarmclaw 0.9.4 → 0.9.6

package/src/lib/server/plugins.ts

@@ -3,7 +3,24 @@ import path from 'path'
 import crypto from 'crypto'
 import { createRequire } from 'module'
 import { spawn } from 'child_process'
-import type { Plugin, PluginHooks, PluginMeta, PluginToolDef, PluginUIExtension, PluginProviderExtension, PluginConnectorExtension, Session, PluginPackageManager, PluginDependencyInstallStatus } from '@/types'
+import type {
+  Plugin,
+  PluginHooks,
+  PluginMeta,
+  PluginToolDef,
+  PluginUIExtension,
+  PluginProviderExtension,
+  PluginConnectorExtension,
+  Session,
+  PluginPackageManager,
+  PluginDependencyInstallStatus,
+  PluginPromptBuildResult,
+  PluginToolCallResult,
+  PluginModelResolveResult,
+  PluginBeforeMessageWriteResult,
+  PluginSubagentSpawningResult,
+  Message,
+} from '@/types'
 import {
   inferPluginInstallSourceFromUrl,
   inferPluginPublisherSourceFromUrl,
@@ -101,6 +118,9 @@ interface PluginLogger {
 type HookRegistrar = {
   onAgentStart?: (fn: (...args: unknown[]) => unknown) => void
   onAgentComplete?: (fn: (...args: unknown[]) => unknown) => void
+  onBeforeModelResolve?: (fn: (...args: unknown[]) => unknown) => void
+  onBeforePromptBuild?: (fn: (...args: unknown[]) => unknown) => void
+  onBeforeToolCall?: (fn: (...args: unknown[]) => unknown) => void
   onToolCall?: (fn: (...args: unknown[]) => unknown) => void
   onToolResult?: (fn: (...args: unknown[]) => unknown) => void
   onMessage?: (fn: (...args: unknown[]) => unknown) => void
@@ -151,6 +171,69 @@ function isPluginSecretSettingValue(value: unknown): value is PluginSecretSettin
   return rec.__pluginSecret === true && typeof rec.encrypted === 'string'
 }
 
+function concatOptionalTextSegments(...segments: Array<string | null | undefined>): string | undefined {
+  const normalized = segments
+    .map((segment) => (typeof segment === 'string' ? segment.trim() : ''))
+    .filter(Boolean)
+  return normalized.length > 0 ? normalized.join('\n\n') : undefined
+}
+
+function mergePromptBuildResults(
+  current: PluginPromptBuildResult | undefined,
+  next: PluginPromptBuildResult,
+): PluginPromptBuildResult {
+  return {
+    systemPrompt: current?.systemPrompt ?? next.systemPrompt,
+    prependContext: concatOptionalTextSegments(current?.prependContext, next.prependContext),
+    prependSystemContext: concatOptionalTextSegments(current?.prependSystemContext, next.prependSystemContext),
+    appendSystemContext: concatOptionalTextSegments(current?.appendSystemContext, next.appendSystemContext),
+  }
+}
+
+function mergeModelResolveResults(
+  current: PluginModelResolveResult | undefined,
+  next: PluginModelResolveResult,
+): PluginModelResolveResult {
+  return {
+    providerOverride: next.providerOverride ?? current?.providerOverride,
+    modelOverride: next.modelOverride ?? current?.modelOverride,
+    apiEndpointOverride: next.apiEndpointOverride ?? current?.apiEndpointOverride,
+  }
+}
+
+function isToolCallControlResult(value: unknown): value is PluginToolCallResult {
+  if (!isRecord(value)) return false
+  return 'input' in value || 'params' in value || 'block' in value || 'blockReason' in value || 'warning' in value
+}
+
+function isMessageLike(value: unknown): value is Message {
+  return isRecord(value)
+    && (value.role === 'user' || value.role === 'assistant')
+    && typeof value.text === 'string'
+    && typeof value.time === 'number'
+}
+
+function isBeforeMessageWriteResult(value: unknown): value is PluginBeforeMessageWriteResult {
+  if (!isRecord(value)) return false
+  return 'message' in value || 'block' in value
+}
+
+function isSubagentSpawningResult(value: unknown): value is PluginSubagentSpawningResult {
+  return isRecord(value) && (value.status === 'ok' || value.status === 'error')
+}
+
+function mergeToolCallInput(
+  currentInput: Record<string, unknown> | null,
+  nextInput: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | null {
+  if (nextInput === undefined) return currentInput
+  if (nextInput === null) return null
+  if (currentInput && typeof currentInput === 'object') {
+    return { ...currentInput, ...nextInput }
+  }
+  return nextInput
+}
+
 function hashPluginSource(content: string): string {
   return crypto.createHash('sha256').update(content).digest('hex')
 }
@@ -404,6 +487,18 @@ function normalizePlugin(mod: unknown): Plugin | null {
     const tools: PluginToolDef[] = []
 
     const hookEventMap: Record<string, keyof PluginHooks> = {
+      'before_model_resolve': 'beforeModelResolve',
+      'before_prompt_build': 'beforePromptBuild',
+      'before_tool_call': 'beforeToolCall',
+      'llm_input': 'llmInput',
+      'llm_output': 'llmOutput',
+      'tool_result_persist': 'toolResultPersist',
+      'before_message_write': 'beforeMessageWrite',
+      'session_start': 'sessionStart',
+      'session_end': 'sessionEnd',
+      'subagent_spawning': 'subagentSpawning',
+      'subagent_spawned': 'subagentSpawned',
+      'subagent_ended': 'subagentEnded',
       'agent:start': 'beforeAgentStart',
       'agent:complete': 'afterAgentComplete',
       'tool:call': 'beforeToolExec',
@@ -484,6 +579,8 @@ function normalizePlugin(mod: unknown): Plugin | null {
     const registrar = {
       onAgentStart: (fn: (...args: unknown[]) => unknown) => { hooks.beforeAgentStart = fn as PluginHooks['beforeAgentStart'] },
       onAgentComplete: (fn: (...args: unknown[]) => unknown) => { hooks.afterAgentComplete = fn as PluginHooks['afterAgentComplete'] },
+      onBeforePromptBuild: (fn: (...args: unknown[]) => unknown) => { hooks.beforePromptBuild = fn as PluginHooks['beforePromptBuild'] },
+      onBeforeToolCall: (fn: (...args: unknown[]) => unknown) => { hooks.beforeToolCall = fn as PluginHooks['beforeToolCall'] },
       onToolCall: (fn: (...args: unknown[]) => unknown) => { hooks.beforeToolExec = fn as PluginHooks['beforeToolExec'] },
       onToolResult: (fn: (...args: unknown[]) => unknown) => { hooks.afterToolExec = fn as PluginHooks['afterToolExec'] },
       onMessage: (fn: (...args: unknown[]) => unknown) => { hooks.onMessage = fn as PluginHooks['onMessage'] },
@@ -1048,22 +1145,154 @@ class PluginManager {
     }
   }
 
-  async runBeforeToolExec(
-    params: { toolName: string; input: Record<string, unknown> | null },
+  async runBeforePromptBuild(
+    params: {
+      session: Session
+      prompt: string
+      message: string
+      history: import('@/types').Message[]
+      messages: import('@/types').Message[]
+    },
     options?: HookExecutionOptions,
-  ): Promise<Record<string, unknown> | null> {
+  ): Promise<PluginPromptBuildResult | null> {
     this.load()
     const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
-    let currentInput = params.input
+    let result: PluginPromptBuildResult | undefined
+
+    for (const [id, p] of this.plugins.entries()) {
+      if (filterIds !== null && !filterIds.has(id)) continue
+      const hook = p.hooks.beforePromptBuild
+      if (!hook) continue
+      try {
+        const next = await hook(params)
+        if (next && typeof next === 'object' && !Array.isArray(next)) {
+          result = mergePromptBuildResults(result, next as PluginPromptBuildResult)
+        }
+        this.markPluginSuccess(id)
+      } catch (err: unknown) {
+        log.error('plugins', 'beforePromptBuild hook failed', {
+          pluginId: id,
+          pluginName: p.meta.name,
+          error: errorMessage(err),
+        })
+        this.markPluginFailure(id, 'hook.beforePromptBuild', err, true)
+      }
+    }
+
+    return result || null
+  }
+
+  async runBeforeModelResolve(
+    params: {
+      session: Session
+      prompt: string
+      message: string
+      provider: Session['provider']
+      model: string
+      apiEndpoint?: string | null
+    },
+    options?: HookExecutionOptions,
+  ): Promise<PluginModelResolveResult | null> {
+    this.load()
+    const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
+    let result: PluginModelResolveResult | undefined
 
     for (const [id, p] of this.plugins.entries()) {
       if (filterIds !== null && !filterIds.has(id)) continue
-      const hook = p.hooks.beforeToolExec
+      const hook = p.hooks.beforeModelResolve
       if (!hook) continue
       try {
-        const result = await hook({ toolName: params.toolName, input: currentInput })
-        if (result && typeof result === 'object' && !Array.isArray(result)) {
-          currentInput = result as Record<string, unknown>
+        const next = await hook(params)
+        if (next && typeof next === 'object' && !Array.isArray(next)) {
+          result = mergeModelResolveResults(result, next as PluginModelResolveResult)
+        }
+        this.markPluginSuccess(id)
+      } catch (err: unknown) {
+        log.error('plugins', 'beforeModelResolve hook failed', {
+          pluginId: id,
+          pluginName: p.meta.name,
+          error: errorMessage(err),
+        })
+        this.markPluginFailure(id, 'hook.beforeModelResolve', err, true)
+      }
+    }
+
+    return result || null
+  }
+
+  async runBeforeToolCall(
+    params: {
+      session: Session
+      toolName: string
+      input: Record<string, unknown> | null
+      runId?: string
+      toolCallId?: string
+    },
+    options?: HookExecutionOptions,
+  ): Promise<{ input: Record<string, unknown> | null; blockReason: string | null; warning: string | null }> {
+    this.load()
+    const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
+    let currentInput = params.input
+    let blockReason: string | null = null
+    let warning: string | null = null
+
+    for (const [id, p] of this.plugins.entries()) {
+      if (filterIds !== null && !filterIds.has(id)) continue
+
+      const beforeToolCall = p.hooks.beforeToolCall
+      if (beforeToolCall) {
+        try {
+          const result = await beforeToolCall({
+            session: params.session,
+            toolName: params.toolName,
+            input: currentInput,
+            runId: params.runId,
+            toolCallId: params.toolCallId,
+          })
+
+          if (isToolCallControlResult(result)) {
+            if (result.block === true) {
+              blockReason = typeof result.blockReason === 'string' && result.blockReason.trim()
+                ? result.blockReason.trim()
+                : 'Tool call blocked by plugin hook'
+            }
+            if (typeof result.warning === 'string' && result.warning.trim()) {
+              warning = result.warning.trim()
+            }
+            currentInput = mergeToolCallInput(
+              currentInput,
+              isRecord(result.params)
+                ? result.params
+                : isRecord(result.input)
+                  ? result.input
+                  : result.input === null
+                    ? null
+                    : undefined,
+            )
+          } else if (result && typeof result === 'object' && !Array.isArray(result)) {
+            currentInput = result as Record<string, unknown>
+          }
+          this.markPluginSuccess(id)
+        } catch (err: unknown) {
+          log.error('plugins', 'beforeToolCall hook failed', {
+            pluginId: id,
+            pluginName: p.meta.name,
+            toolName: params.toolName,
+            error: errorMessage(err),
+          })
+          this.markPluginFailure(id, 'hook.beforeToolCall', err, true)
+        }
+      }
+
+      const beforeToolExec = p.hooks.beforeToolExec
+      if (blockReason) break
+      if (!beforeToolExec) {
+        continue
+      }
+      try {
+        const legacyResult = await beforeToolExec({ toolName: params.toolName, input: currentInput })
+        if (legacyResult && typeof legacyResult === 'object' && !Array.isArray(legacyResult)) {
+          currentInput = legacyResult as Record<string, unknown>
         }
         this.markPluginSuccess(id)
       } catch (err: unknown) {
@@ -1075,9 +1304,176 @@ class PluginManager {
         })
         this.markPluginFailure(id, 'hook.beforeToolExec', err, true)
       }
+
+      if (blockReason) break
     }
 
-    return currentInput
+    return { input: currentInput, blockReason, warning }
+  }
+
+  async runToolResultPersist(
+    params: {
+      session: Session
+      message: Message
+      toolName?: string
+      toolCallId?: string
+      isSynthetic?: boolean
+    },
+    options?: HookExecutionOptions,
+  ): Promise<Message> {
+    this.load()
+    const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
+    let currentMessage = params.message
+
+    for (const [id, p] of this.plugins.entries()) {
+      if (filterIds !== null && !filterIds.has(id)) continue
+      const hook = p.hooks.toolResultPersist
+      if (!hook) continue
+      try {
+        const result = await hook({
+          session: params.session,
+          message: currentMessage,
+          toolName: params.toolName,
+          toolCallId: params.toolCallId,
+          isSynthetic: params.isSynthetic,
+        })
+        if (isMessageLike(result)) {
+          currentMessage = result
+        } else if (isRecord(result) && isMessageLike(result.message)) {
+          currentMessage = result.message
+        }
+        this.markPluginSuccess(id)
+      } catch (err: unknown) {
+        log.error('plugins', 'toolResultPersist hook failed', {
+          pluginId: id,
+          pluginName: p.meta.name,
+          error: errorMessage(err),
+        })
+        this.markPluginFailure(id, 'hook.toolResultPersist', err, true)
+      }
+    }
+
+    return currentMessage
+  }
+
+  async runBeforeMessageWrite(
+    params: {
+      session: Session
+      message: Message
+      phase?: 'user' | 'system' | 'assistant_partial' | 'assistant_final' | 'heartbeat'
+      runId?: string
+    },
+    options?: HookExecutionOptions,
+  ): Promise<{ message: Message; block: boolean }> {
+    this.load()
+    const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
+    let currentMessage = params.message
+    let block = false
+
+    for (const [id, p] of this.plugins.entries()) {
+      if (filterIds !== null && !filterIds.has(id)) continue
+      const hook = p.hooks.beforeMessageWrite
+      if (!hook) continue
+      try {
+        const result = await hook({
+          session: params.session,
+          message: currentMessage,
+          phase: params.phase,
+          runId: params.runId,
+        })
+        if (isMessageLike(result)) {
+          currentMessage = result
+        } else if (isBeforeMessageWriteResult(result)) {
+          if (isMessageLike(result.message)) currentMessage = result.message
+          if (result.block === true) {
+            block = true
+            this.markPluginSuccess(id)
+            break
+          }
+        }
+        this.markPluginSuccess(id)
+      } catch (err: unknown) {
+        log.error('plugins', 'beforeMessageWrite hook failed', {
+          pluginId: id,
+          pluginName: p.meta.name,
+          error: errorMessage(err),
+        })
+        this.markPluginFailure(id, 'hook.beforeMessageWrite', err, true)
+      }
+    }
+
+    return { message: currentMessage, block }
+  }
+
+  async runSubagentSpawning(
+    params: {
+      parentSessionId?: string | null
+      agentId: string
+      agentName: string
+      message: string
+      cwd: string
+      mode: 'run' | 'session'
+      threadRequested: boolean
+    },
+    options?: HookExecutionOptions,
+  ): Promise<PluginSubagentSpawningResult> {
+    this.load()
+    const filterIds = this.resolveEnabledFilter(options?.enabledIds, options?.includeAllWhenEmpty === true)
+
+    for (const [id, p] of this.plugins.entries()) {
+      if (filterIds !== null && !filterIds.has(id)) continue
+      const hook = p.hooks.subagentSpawning
+      if (!hook) continue
+      try {
+        const result = await hook(params)
+        if (isSubagentSpawningResult(result) && result.status === 'error') {
+          this.markPluginSuccess(id)
+          return {
+            status: 'error',
+            error: typeof result.error === 'string' && result.error.trim()
+              ? result.error.trim()
+              : 'Subagent spawn blocked by plugin hook',
+          }
+        }
+        this.markPluginSuccess(id)
+      } catch (err: unknown) {
+        log.error('plugins', 'subagentSpawning hook failed', {
+          pluginId: id,
+          pluginName: p.meta.name,
+          error: errorMessage(err),
+        })
+        this.markPluginFailure(id, 'hook.subagentSpawning', err, true)
+      }
+    }
+
+    return { status: 'ok' }
+  }
+
+  async runBeforeToolExec(
+    params: { toolName: string; input: Record<string, unknown> | null },
+    options?: HookExecutionOptions,
+  ): Promise<Record<string, unknown> | null> {
+    const result = await this.runBeforeToolCall(
+      {
+        session: {
+          id: 'plugin-hook-session',
+          name: 'Plugin Hook Session',
+          cwd: process.cwd(),
+          user: 'system',
+          // Synthetic fallback used only when no real session context is available.
+          provider: 'openai',
+          model: 'synthetic-hook-context',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: Date.now(),
+          lastActiveAt: Date.now(),
+        },
+        toolName: params.toolName,
+        input: params.input,
+      },
+      options,
+    )
+    return result.input
   }
 
   async transformText(

package/src/lib/server/session-tools/context.ts

@@ -1,5 +1,5 @@
 import type { StructuredToolInterface } from '@langchain/core/tools'
-import type { Agent } from '@/types'
+import type { Agent, Session } from '@/types'
 
 export const MAX_OUTPUT = 50 * 1024 // 50KB
 export const MAX_FILE = 100 * 1024 // 100KB
@@ -7,6 +7,7 @@ export const MAX_FILE = 100 * 1024 // 100KB
 export interface ToolContext {
   agentId?: string | null
   sessionId?: string | null
+  runId?: string | null
   platformAssignScope?: 'self' | 'all'
   mcpServerIds?: string[]
   mcpDisabledTools?: string[]
@@ -15,6 +16,19 @@ export interface ToolContext {
   projectName?: string | null
   projectDescription?: string | null
   memoryScopeMode?: 'auto' | 'all' | 'global' | 'agent' | 'session' | 'project' | null
+  beforeToolCall?: (params: {
+    session: Session
+    toolName: string
+    input: Record<string, unknown> | null
+    runId?: string | null
+  }) => Promise<ToolCallGuardResult | void> | ToolCallGuardResult | void
+  onToolCallWarning?: (params: { toolName: string; message: string }) => void
+}
+
+export interface ToolCallGuardResult {
+  input?: Record<string, unknown> | null
+  blockReason?: string | null
+  warning?: string | null
 }
 
 /**

package/src/lib/server/session-tools/index.ts

@@ -334,8 +334,9 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
       name: 'Plugin Hook Session',
       cwd,
       user: 'system',
+      // Synthetic fallback used only for hook execution when no persisted session exists.
       provider: 'openai',
-      model: 'unknown',
+      model: 'synthetic-hook-context',
       claudeSessionId: null,
       messages: [],
       createdAt: Date.now(),
@@ -353,19 +354,54 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
             throw new DOMException('Tool execution aborted', 'AbortError')
           }
           const normalizedArgs = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
+          const hookSession = resolveCurrentSession() || buildFallbackHookSession()
           // Enforce file access policy before execution
           if (fileAccessPolicy) {
             const denial = enforceFileAccessPolicy(candidate.name, normalizedArgs, cwd, fileAccessPolicy)
             if (denial) return denial
           }
-          const nextArgs = await pluginManager.runBeforeToolExec(
-            { toolName: candidate.name, input: normalizedArgs },
+          let guardedArgs: Record<string, unknown> | null = normalizedArgs
+          if (ctx?.beforeToolCall) {
+            const guardResult = await ctx.beforeToolCall({
+              session: hookSession,
+              toolName: candidate.name,
+              input: guardedArgs,
+              runId: ctx.runId,
+            })
+            if (guardResult?.warning) {
+              ctx.onToolCallWarning?.({
+                toolName: candidate.name,
+                message: guardResult.warning,
+              })
+            }
+            if (typeof guardResult?.blockReason === 'string' && guardResult.blockReason.trim()) {
+              throw new Error(guardResult.blockReason.trim())
+            }
+            if (guardResult && 'input' in guardResult) {
+              guardedArgs = guardResult.input === undefined ? guardedArgs : guardResult.input ?? null
+            }
+          }
+          const hookResult = await pluginManager.runBeforeToolCall(
+            {
+              session: hookSession,
+              toolName: candidate.name,
+              input: guardedArgs,
+              runId: ctx?.runId || undefined,
+            },
             { enabledIds: activePlugins },
           )
-          const effectiveArgs = nextArgs ?? normalizedArgs
-          const result = await candidate.invoke(effectiveArgs)
+          if (hookResult.warning) {
+            ctx?.onToolCallWarning?.({
+              toolName: candidate.name,
+              message: hookResult.warning,
+            })
+          }
+          if (hookResult.blockReason) {
+            throw new Error(hookResult.blockReason)
+          }
+          const effectiveArgs = hookResult.input ?? guardedArgs
+          const result = await candidate.invoke(effectiveArgs ?? {})
           const outputText = typeof result === 'string' ? result : JSON.stringify(result)
-          const hookSession = resolveCurrentSession() || buildFallbackHookSession()
           await pluginManager.runHook(
             'afterToolExec',
             { session: hookSession, toolName: candidate.name, input: effectiveArgs, output: outputText },

package/src/lib/server/session-tools/session-tools-wiring.test.ts

@@ -75,6 +75,56 @@ describe('buildSessionTools signature', () => {
     assert.ok(buildSessionTools.length >= 2, 'buildSessionTools should accept at least 2 params')
   })
 
+  it('runs beforeToolCall hooks before invoking plugin tools', async () => {
+    const { buildSessionTools } = await import('./index')
+    const { getPluginManager } = await import('../plugins')
+    const pluginId = `tool_wrapper_${Date.now()}`
+    const toolName = `${pluginId}_echo`
+
+    getPluginManager().registerBuiltin(pluginId, {
+      name: 'Tool Wrapper Hook Test',
+      hooks: {
+        beforeToolCall: ({ input }) => {
+          if (input?.message === 'blocked') {
+            return { block: true, blockReason: 'blocked before invoke' }
+          }
+          return { params: { message: `${String(input?.message || '')}:patched` } }
+        },
+      },
+      tools: [
+        {
+          name: toolName,
+          description: 'Echo the message',
+          parameters: {
+            type: 'object',
+            properties: {
+              message: { type: 'string' },
+            },
+          },
+          execute: async (args) => String(args.message || ''),
+        },
+      ],
+    })
+
+    const built = await buildSessionTools(process.cwd(), [pluginId], {
+      agentId: 'agent-test',
+      sessionId: 'session-test',
+      runId: 'run-test',
+    })
+    const wrapped = built.tools.find((entry) => entry.name === toolName)
+    assert.ok(wrapped, 'plugin tool should be built')
+
+    const ok = await wrapped!.invoke({ message: 'hello' })
+    assert.equal(ok, 'hello:patched')
+
+    await assert.rejects(
+      () => wrapped!.invoke({ message: 'blocked' }),
+      /blocked before invoke/,
+    )
+
+    await built.cleanup()
+  })
+
   it('sandbox builder exposes the local Node/Docker sandbox tools', async () => {
     const { buildSandboxTools } = await import('./sandbox')
     const bctx: import('./context').ToolBuildContext = {

package/src/lib/server/session-tools/subagent.ts

@@ -245,7 +245,7 @@ async function handleBatch(args: Record<string, unknown>, ctx: ActionContext): P
     : 'auto'
 
   // Use spawnSwarm internally — batch is a simplified interface
-  const swarm = spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   const jobIds = swarm.members
     .filter((m) => !m.spawnError && m.handle)
     .map((m) => m.handle.jobId)
@@ -303,7 +303,7 @@ async function handleSwarm(args: Record<string, unknown>, ctx: ActionContext): P
     ? args.executionMode
     : 'auto'
 
-  const swarm = spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   if (!waitForCompletion) {
     const snapshot = getSwarmSnapshot(swarm.swarmId)
     return JSON.stringify({
@@ -361,7 +361,7 @@ async function handleStart(args: Record<string, unknown>, ctx: ActionContext): P
   const shareBrowserProfile = args.shareBrowserProfile === true || args.share_browser_profile === true
   const waitForCompletion = args.waitForCompletion !== false && args.background !== true
 
-  const handle = spawnSubagent(
+  const handle = await spawnSubagent(
     { agentId, message, cwd, shareBrowserProfile, waitForCompletion },
     { sessionId: ctx.sessionId, cwd: ctx.cwd },
   )

package/src/lib/server/tool-loop-detection.test.ts

@@ -91,6 +91,27 @@ describe('ToolLoopTracker', () => {
     assert.equal(warn.severity, 'warning')
     assert.equal(warn.detector, 'tool_frequency')
   })
+
+  it('previews critical repeats before another identical tool call executes', () => {
+    const tracker = new ToolLoopTracker({ repeatWarn: 2, repeatCritical: 3, toolFrequencyWarn: 100, toolFrequencyCritical: 100 })
+    tracker.record('web_search', { query: 'same' }, 'result 1')
+    tracker.record('web_search', { query: 'same' }, 'result 2')
+
+    const preview = tracker.preview('web_search', { query: 'same' })
+    assert.ok(preview)
+    assert.equal(preview?.severity, 'critical')
+    assert.equal(preview?.detector, 'generic_repeat')
+  })
+
+  it('previews tool overuse by frequency before the next call executes', () => {
+    const tracker = new ToolLoopTracker({ toolFrequencyWarn: 2, toolFrequencyCritical: 4 })
+    tracker.record('browser', { action: 'open', url: 'https://a.example' }, 'ok')
+
+    const preview = tracker.preview('browser', { action: 'open', url: 'https://b.example' })
+    assert.ok(preview)
+    assert.equal(preview?.severity, 'warning')
+    assert.equal(preview?.detector, 'tool_frequency')
+  })
 })
 
 describe('hash helpers', () => {