ummaya 0.2.4 → 0.2.6

package/tui/src/tools/AgentTool/lifecycle.ts

@@ -0,0 +1,244 @@
+import { feature } from 'bun:bundle'
+import { isCoordinatorMode } from '../../coordinator/coordinatorMode.js'
+import { type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, logEvent } from '../../services/analytics/index.js'
+import type { AppState } from '../../state/AppState.js'
+import type { ToolUseContext, Tools } from '../../Tool.js'
+import { getAgentModel } from '../../utils/model/agent.js'
+import { createAgentId } from '../../utils/uuid.js'
+import { buildCoordinatorWorkerPermissionContext } from './orchestrationSupport.js'
+import { isBuiltInAgent } from './loadAgentsDir.js'
+import { isForkSubagentEnabled } from './forkSubagent.js'
+import { runAgent } from './runAgent.js'
+import {
+  assertAgentLaunchAllowed,
+  launchTeammateIfRequested,
+  resolveSelectedAgentRoute,
+  resolveTeamName,
+} from './launchRouting.js'
+import { launchRemoteAgentIfRequested } from './remoteRouting.js'
+import {
+  buildAgentPromptSetup,
+  buildRunAgentParams,
+} from './promptSetup.js'
+import {
+  appendForkWorktreeNotice,
+  buildWorktreeCleanup,
+  createWorktreeState,
+} from './worktreeLifecycle.js'
+import {
+  isBackgroundTasksDisabled,
+  isCoordinatorEnvMode,
+  isProactiveAgentActive,
+} from './runtimeConfig.js'
+import {
+  launchAsyncAgent,
+  registerAgentName,
+} from './asyncLifecycle.js'
+import { launchSyncAgent } from './foregroundLifecycle.js'
+import type {
+  AgentLifecycleMetadata,
+  AgentToolCallResult,
+  AgentToolInput,
+  AgentToolProgressCallback,
+} from './schemas.js'
+
+type SetAppState = (f: (prev: AppState) => AppState) => void
+type RunAgentParams = Parameters<typeof runAgent>[0]
+type AssistantProgressSource = {
+  readonly requestId?: string
+  readonly message?: { readonly id?: string }
+}
+
+export async function callAgentTool(
+  input: AgentToolInput,
+  toolUseContext: ToolUseContext,
+  canUseTool: RunAgentParams['canUseTool'],
+  assistantMessage: AssistantProgressSource | undefined,
+  onProgress?: AgentToolProgressCallback,
+): Promise<AgentToolCallResult> {
+  const startTime = Date.now()
+  const model = isCoordinatorMode() ? undefined : input.model
+  const appState = toolUseContext.getAppState()
+  const rootSetAppState =
+    toolUseContext.setAppStateForTasks ?? toolUseContext.setAppState
+  const teamName = resolveTeamName(input, appState)
+  assertAgentLaunchAllowed({ input, teamName })
+
+  const teammateResult = await launchTeammateIfRequested({
+    input,
+    teamName,
+    model,
+    toolUseContext,
+    assistantMessage,
+  })
+  if (teammateResult) return teammateResult
+
+  const { selectedAgent, isForkPath } = await resolveSelectedAgentRoute({
+    input,
+    toolUseContext,
+    appState,
+  })
+  assertAgentLaunchAllowed({ input, selectedAgent, teamName })
+  const permissionMode = appState.toolPermissionContext.mode
+  const resolvedAgentModel = getAgentModel(
+    selectedAgent.model,
+    toolUseContext.options.mainLoopModel,
+    isForkPath ? undefined : model,
+    permissionMode,
+  )
+  const shouldRunAsync = shouldRunAgentAsync({
+    input,
+    selectedAgent,
+    appState,
+  })
+  const metadata: AgentLifecycleMetadata = {
+    prompt: input.prompt,
+    resolvedAgentModel,
+    isBuiltInAgent: isBuiltInAgent(selectedAgent),
+    startTime,
+    agentType: selectedAgent.agentType,
+    isAsync: shouldRunAsync,
+  }
+  logSelectedAgent(selectedAgent, resolvedAgentModel, metadata, isForkPath)
+
+  const effectiveIsolation = input.isolation ?? selectedAgent.isolation
+  const remoteResult = await launchRemoteAgentIfRequested({
+    effectiveIsolation,
+    description: input.description,
+    prompt: input.prompt,
+    selectedAgent,
+    toolUseContext,
+  })
+  if (remoteResult) return remoteResult
+
+  const earlyAgentId = createAgentId()
+  const promptSetup = await buildAgentPromptSetup({
+    prompt: input.prompt,
+    selectedAgent,
+    toolUseContext,
+    assistantMessage,
+    resolvedAgentModel,
+    isForkPath,
+    hasWorktree: effectiveIsolation === 'worktree',
+    cwd: input.cwd,
+  })
+  const worktreeState = await createWorktreeState({
+    isolation: effectiveIsolation,
+    earlyAgentId,
+  })
+  appendForkWorktreeNotice({
+    isForkPath,
+    worktreePath: worktreeState.current?.worktreePath,
+    promptMessages: promptSetup.promptMessages,
+  })
+
+  const workerPermissionContext = buildCoordinatorWorkerPermissionContext(
+    appState.toolPermissionContext,
+    selectedAgent.permissionMode ?? 'acceptEdits',
+  )
+  const workerTools = await assembleWorkerTools(
+    workerPermissionContext,
+    appState.mcp.tools,
+  )
+  const runAgentParams = buildRunAgentParams({
+    selectedAgent,
+    promptSetup,
+    toolUseContext,
+    canUseTool,
+    shouldRunAsync,
+    isForkPath,
+    model,
+    workerTools,
+    worktreePath: worktreeState.current?.worktreePath,
+    description: input.description,
+  })
+  const cwdOverridePath = input.cwd ?? worktreeState.current?.worktreePath
+  const getWorktreeResult = buildWorktreeCleanup({
+    state: worktreeState,
+    earlyAgentId,
+    selectedAgent,
+    description: input.description,
+  })
+
+  if (shouldRunAsync) {
+    const data = launchAsyncAgent({
+      asyncAgentId: earlyAgentId,
+      description: input.description,
+      prompt: input.prompt,
+      selectedAgent,
+      rootSetAppState,
+      toolUseContext,
+      runAgentParams,
+      metadata,
+      assistantMessage,
+      cwdOverridePath,
+      isCoordinator: isCoordinatorEnvMode(),
+      getWorktreeResult,
+    })
+    registerAgentName({ name: input.name, agentId: earlyAgentId, rootSetAppState })
+    return { data }
+  }
+
+  return launchSyncAgent({
+    syncAgentId: earlyAgentId,
+    selectedAgent,
+    prompt: input.prompt,
+    promptMessages: promptSetup.promptMessages,
+    description: input.description,
+    runAgentParams,
+    toolUseContext,
+    rootSetAppState,
+    metadata,
+    assistantMessage,
+    cwdOverridePath,
+    onProgress,
+    getWorktreeResult,
+  })
+}
+
+async function assembleWorkerTools(
+  workerPermissionContext: AppState['toolPermissionContext'],
+  mcpTools: AppState['mcp']['tools'],
+): Promise<Tools> {
+  const { assembleToolPool } = await import('../../tools.js')
+  return assembleToolPool(workerPermissionContext, mcpTools)
+}
+
+function shouldRunAgentAsync({
+  input,
+  selectedAgent,
+  appState,
+}: {
+  readonly input: AgentToolInput
+  readonly selectedAgent: { readonly background?: boolean }
+  readonly appState: Pick<AppState, 'kairosEnabled'>
+}): boolean {
+  const assistantForceAsync = feature('KAIROS') ? appState.kairosEnabled : false
+  return (
+    (input.run_in_background === true ||
+      selectedAgent.background === true ||
+      isCoordinatorEnvMode() ||
+      isForkSubagentEnabled() ||
+      assistantForceAsync ||
+      isProactiveAgentActive()) &&
+    !isBackgroundTasksDisabled
+  )
+}
+
+function logSelectedAgent(
+  selectedAgent: { readonly agentType: string; readonly source?: string; readonly color?: string },
+  resolvedAgentModel: string,
+  metadata: Pick<AgentLifecycleMetadata, 'isAsync' | 'isBuiltInAgent'>,
+  isForkPath: boolean,
+): void {
+  logEvent('tengu_agent_tool_selected', {
+    agent_type: selectedAgent.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    model: resolvedAgentModel as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    source: selectedAgent.source as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    color: selectedAgent.color as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    is_built_in_agent: metadata.isBuiltInAgent,
+    is_resume: false,
+    is_async: metadata.isAsync,
+    is_fork: isForkPath,
+  })
+}

package/tui/src/tools/AgentTool/mcpRouting.ts

@@ -0,0 +1,73 @@
+import type { AppState } from '../../state/AppState.js'
+import type { Tools, ToolUseContext } from '../../Tool.js'
+import { sleep } from '../../utils/sleep.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+import { hasRequiredMcpServers } from './loadAgentsDir.js'
+
+export async function waitForRequiredMcpServers(
+  selectedAgent: AgentDefinition,
+  toolUseContext: ToolUseContext,
+  appState: AppState,
+): Promise<void> {
+  const requiredMcpServers = selectedAgent.requiredMcpServers
+  if (!requiredMcpServers?.length) return
+  let currentAppState = appState
+  if (hasPendingRequiredServers(currentAppState, requiredMcpServers)) {
+    const deadline = Date.now() + 30_000
+    while (Date.now() < deadline) {
+      await sleep(500)
+      currentAppState = toolUseContext.getAppState()
+      if (hasFailedRequiredServer(currentAppState, requiredMcpServers)) break
+      if (!hasPendingRequiredServers(currentAppState, requiredMcpServers)) break
+    }
+  }
+  const serversWithTools = mcpServersWithTools(currentAppState.mcp.tools)
+  if (hasRequiredMcpServers(selectedAgent, serversWithTools)) return
+  const missing = requiredMcpServers.filter(
+    pattern =>
+      !serversWithTools.some(server =>
+        server.toLowerCase().includes(pattern.toLowerCase()),
+      ),
+  )
+  throw new Error(
+    `Agent '${selectedAgent.agentType}' requires MCP servers matching: ${missing.join(', ')}. MCP servers with tools: ${serversWithTools.length > 0 ? serversWithTools.join(', ') : 'none'}. Use /mcp to configure and authenticate the required MCP servers.`,
+  )
+}
+
+export function mcpServersWithTools(tools: Tools): string[] {
+  const serverNames: string[] = []
+  for (const tool of tools) {
+    if (!tool.name?.startsWith('mcp__')) continue
+    const serverName = tool.name.split('__')[1]
+    if (serverName && !serverNames.includes(serverName)) {
+      serverNames.push(serverName)
+    }
+  }
+  return serverNames
+}
+
+function hasPendingRequiredServers(
+  appState: AppState,
+  requiredMcpServers: readonly string[],
+): boolean {
+  return appState.mcp.clients.some(
+    client =>
+      client.type === 'pending' &&
+      requiredMcpServers.some(pattern =>
+        client.name.toLowerCase().includes(pattern.toLowerCase()),
+      ),
+  )
+}
+
+function hasFailedRequiredServer(
+  appState: AppState,
+  requiredMcpServers: readonly string[],
+): boolean {
+  return appState.mcp.clients.some(
+    client =>
+      client.type === 'failed' &&
+      requiredMcpServers.some(pattern =>
+        client.name.toLowerCase().includes(pattern.toLowerCase()),
+      ),
+  )
+}

package/tui/src/tools/AgentTool/orchestrationSupport.ts

@@ -0,0 +1,70 @@
+import type { ToolPermissionContext } from '../../Tool.js'
+import type { PermissionMode } from '../../types/permissions.js'
+
+export const COORDINATOR_PERMISSION_FLOW =
+  'coordinator_parent_round_trip' as const
+
+export type CoordinatorPermissionFlow = typeof COORDINATOR_PERMISSION_FLOW
+
+export type AgentSupportMetadata = {
+  evidenceJoinKey: string
+  parentToolUseId: string
+  resumeToken: string
+  permissionFlow: CoordinatorPermissionFlow
+}
+
+const UNKNOWN_PARENT_TOOL_USE_ID = 'parent-tool-use:unknown'
+
+const PROTECTED_WORKER_TOOLS = new Set([
+  'document',
+  'send',
+  'check',
+  'workspace_write',
+  'workspace_edit',
+])
+
+function stableJoinPart(part: string): string {
+  const sanitized = part.replace(/[^A-Za-z0-9_.:-]/g, '_')
+  return sanitized.length > 0 ? sanitized : 'unknown'
+}
+
+export function buildAgentSupportMetadata({
+  agentId,
+  taskId,
+  parentToolUseId,
+}: {
+  agentId?: string
+  taskId?: string
+  parentToolUseId?: string
+}): AgentSupportMetadata {
+  const childId = stableJoinPart(agentId ?? taskId ?? 'unknown')
+  const parentId = stableJoinPart(parentToolUseId ?? UNKNOWN_PARENT_TOOL_USE_ID)
+  return {
+    evidenceJoinKey: `${parentId}:${childId}`,
+    parentToolUseId: parentId,
+    resumeToken: `resume:${childId}`,
+    permissionFlow: COORDINATOR_PERMISSION_FLOW,
+  }
+}
+
+export function isProtectedWorkerTool(toolName: string): boolean {
+  return PROTECTED_WORKER_TOOLS.has(toolName)
+}
+
+function workerMode(requestedMode: PermissionMode | undefined): PermissionMode {
+  return requestedMode === 'plan' ? 'plan' : 'default'
+}
+
+export function buildCoordinatorWorkerPermissionContext(
+  parent: ToolPermissionContext,
+  requestedMode: PermissionMode | undefined,
+): ToolPermissionContext {
+  return {
+    ...parent,
+    mode: workerMode(requestedMode),
+    alwaysAllowRules: {},
+    isBypassPermissionsModeAvailable: false,
+    shouldAvoidPermissionPrompts: false,
+    awaitAutomatedChecksBeforeDialog: true,
+  }
+}

package/tui/src/tools/AgentTool/permissions.ts

@@ -0,0 +1,39 @@
+import type { ToolUseContext } from '../../Tool.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+import type { AgentToolInput } from './schemas.js'
+import { isAntBuild } from './runtimeConfig.js'
+
+const NON_INHERITABLE_PERMISSION_MODES = new Set(['bypassPermissions', 'dontAsk'])
+
+export async function checkAgentToolPermissions(
+  input: AgentToolInput,
+  context: ToolUseContext,
+): Promise<PermissionResult> {
+  const appState = context.getAppState()
+  const requestedMode = input.mode
+  if (
+    (requestedMode && NON_INHERITABLE_PERMISSION_MODES.has(requestedMode)) ||
+    NON_INHERITABLE_PERMISSION_MODES.has(appState.toolPermissionContext.mode)
+  ) {
+    return {
+      behavior: 'deny',
+      message:
+        'Agent workers must use the coordinator parent permission round-trip; bypass and dontAsk modes are not inherited by subagents.',
+      decisionReason: {
+        type: 'asyncAgent',
+        reason: 'Subagents cannot inherit bypass or dontAsk permission mode.',
+      },
+    }
+  }
+
+  if (isAntBuild() && appState.toolPermissionContext.mode === 'auto') {
+    return {
+      behavior: 'passthrough',
+      message: 'Agent tool requires permission to spawn sub-agents.',
+    }
+  }
+  return {
+    behavior: 'allow',
+    updatedInput: input,
+  }
+}

package/tui/src/tools/AgentTool/promptSetup.ts

@@ -0,0 +1,181 @@
+import type { AssistantMessage, Message as MessageType } from 'src/types/message.js'
+import { getQuerySourceForAgent } from 'src/utils/promptCategory.js'
+import { enhanceSystemPromptWithEnvDetails, getSystemPrompt } from '../../constants/prompts.js'
+import type { ToolUseContext, Tools } from '../../Tool.js'
+import { type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, logEvent } from '../../services/analytics/index.js'
+import { createUserMessage } from '../../utils/messages.js'
+import { logForDebugging } from '../../utils/debug.js'
+import { errorMessage } from '../../utils/errors.js'
+import { buildEffectiveSystemPrompt } from '../../utils/systemPrompt.js'
+import { asSystemPrompt } from '../../utils/systemPromptType.js'
+import { buildForkedMessages } from './forkSubagent.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+import { isBuiltInAgent } from './loadAgentsDir.js'
+import { runAgent } from './runAgent.js'
+import {
+  additionalWorkingDirectoryPaths,
+  isAntBuild,
+} from './runtimeConfig.js'
+
+type RunAgentParams = Parameters<typeof runAgent>[0]
+
+export type PromptSetup = {
+  readonly promptMessages: MessageType[]
+  readonly override?: RunAgentParams['override']
+  readonly forkContextMessages?: MessageType[]
+  readonly useExactTools?: true
+  readonly querySource: RunAgentParams['querySource']
+}
+
+export async function buildAgentPromptSetup({
+  prompt,
+  selectedAgent,
+  toolUseContext,
+  assistantMessage,
+  resolvedAgentModel,
+  isForkPath,
+  hasWorktree,
+  cwd,
+}: {
+  readonly prompt: string
+  readonly selectedAgent: AgentDefinition
+  readonly toolUseContext: ToolUseContext
+  readonly assistantMessage?: AssistantMessage
+  readonly resolvedAgentModel: string
+  readonly isForkPath: boolean
+  readonly hasWorktree: boolean
+  readonly cwd?: string
+}): Promise<PromptSetup> {
+  if (isForkPath) {
+    const systemPrompt =
+      toolUseContext.renderedSystemPrompt ??
+      (await buildFallbackParentSystemPrompt(toolUseContext))
+    return {
+      promptMessages: buildForkedMessages(prompt, assistantMessage),
+      override: { systemPrompt },
+      forkContextMessages: toolUseContext.messages,
+      useExactTools: true,
+      querySource:
+        toolUseContext.options.querySource ??
+        getQuerySourceForAgent(selectedAgent.agentType, isBuiltInAgent(selectedAgent)),
+    }
+  }
+
+  const enhancedSystemPrompt = await buildSelectedAgentSystemPrompt({
+    selectedAgent,
+    toolUseContext,
+    resolvedAgentModel,
+  })
+  return {
+    promptMessages: [createUserMessage({ content: prompt })],
+    override:
+      enhancedSystemPrompt && !hasWorktree && !cwd
+        ? { systemPrompt: asSystemPrompt(enhancedSystemPrompt) }
+        : undefined,
+    querySource:
+      toolUseContext.options.querySource ??
+      getQuerySourceForAgent(selectedAgent.agentType, isBuiltInAgent(selectedAgent)),
+  }
+}
+
+export function buildRunAgentParams({
+  selectedAgent,
+  promptSetup,
+  toolUseContext,
+  canUseTool,
+  shouldRunAsync,
+  isForkPath,
+  model,
+  workerTools,
+  worktreePath,
+  description,
+}: {
+  readonly selectedAgent: AgentDefinition
+  readonly promptSetup: PromptSetup
+  readonly toolUseContext: ToolUseContext
+  readonly canUseTool: RunAgentParams['canUseTool']
+  readonly shouldRunAsync: boolean
+  readonly isForkPath: boolean
+  readonly model?: string
+  readonly workerTools: Tools
+  readonly worktreePath?: string
+  readonly description: string
+}): RunAgentParams {
+  return {
+    agentDefinition: selectedAgent,
+    promptMessages: promptSetup.promptMessages,
+    toolUseContext,
+    canUseTool,
+    isAsync: shouldRunAsync,
+    querySource: promptSetup.querySource,
+    model: isForkPath ? undefined : model,
+    override: promptSetup.override,
+    availableTools: isForkPath ? toolUseContext.options.tools : workerTools,
+    forkContextMessages: promptSetup.forkContextMessages,
+    ...(promptSetup.useExactTools ? { useExactTools: true as const } : {}),
+    worktreePath,
+    description,
+  }
+}
+
+async function buildFallbackParentSystemPrompt(
+  toolUseContext: ToolUseContext,
+): Promise<ReturnType<typeof buildEffectiveSystemPrompt>> {
+  const appState = toolUseContext.getAppState()
+  const mainThreadAgentDefinition = appState.agent
+    ? appState.agentDefinitions.activeAgents.find(
+        agent => agent.agentType === appState.agent,
+      )
+    : undefined
+  const defaultSystemPrompt = await getSystemPrompt(
+    toolUseContext.options.tools,
+    toolUseContext.options.mainLoopModel,
+    additionalWorkingDirectoryPaths(toolUseContext),
+    toolUseContext.options.mcpClients,
+  )
+  return buildEffectiveSystemPrompt({
+    mainThreadAgentDefinition,
+    toolUseContext,
+    customSystemPrompt: toolUseContext.options.customSystemPrompt,
+    defaultSystemPrompt,
+    appendSystemPrompt: toolUseContext.options.appendSystemPrompt,
+  })
+}
+
+async function buildSelectedAgentSystemPrompt({
+  selectedAgent,
+  toolUseContext,
+  resolvedAgentModel,
+}: {
+  readonly selectedAgent: AgentDefinition
+  readonly toolUseContext: ToolUseContext
+  readonly resolvedAgentModel: string
+}): Promise<string[] | undefined> {
+  try {
+    const agentPrompt = selectedAgent.getSystemPrompt({ toolUseContext })
+    if (selectedAgent.memory) {
+      logEvent('tengu_agent_memory_loaded', {
+        ...(isAntBuild()
+          ? {
+              agent_type:
+                selectedAgent.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+            }
+          : {}),
+        scope: selectedAgent.memory as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        source: 'subagent' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+    }
+    return enhanceSystemPromptWithEnvDetails(
+      [agentPrompt],
+      resolvedAgentModel,
+      additionalWorkingDirectoryPaths(toolUseContext),
+    )
+  } catch (error) {
+    const promptError =
+      error instanceof Error ? error : new Error(errorMessage(error))
+    logForDebugging(
+      `Failed to get system prompt for agent ${selectedAgent.agentType}: ${errorMessage(promptError)}`,
+    )
+    return undefined
+  }
+}

package/tui/src/tools/AgentTool/remoteRouting.ts

@@ -0,0 +1,62 @@
+import type { ToolUseContext } from '../../Tool.js'
+import {
+  checkRemoteAgentEligibility,
+  formatPreconditionError,
+  getRemoteTaskSessionUrl,
+  registerRemoteAgentTask,
+} from '../../tasks/RemoteAgentTask/RemoteAgentTask.js'
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js'
+import { teleportToRemote } from '../../utils/teleport.js'
+import type { AgentDefinition } from './loadAgentsDir.js'
+import type {
+  AgentToolCallResult,
+  RemoteLaunchedOutput,
+} from './schemas.js'
+import { isAntBuild } from './runtimeConfig.js'
+
+export async function launchRemoteAgentIfRequested({
+  effectiveIsolation,
+  description,
+  prompt,
+  selectedAgent: _selectedAgent,
+  toolUseContext,
+}: {
+  readonly effectiveIsolation?: 'worktree' | 'remote'
+  readonly description: string
+  readonly prompt: string
+  readonly selectedAgent: AgentDefinition
+  readonly toolUseContext: ToolUseContext
+}): Promise<AgentToolCallResult | undefined> {
+  if (!isAntBuild() || effectiveIsolation !== 'remote') return undefined
+  const eligibility = await checkRemoteAgentEligibility()
+  if ('errors' in eligibility) {
+    const reasons = eligibility.errors.map(formatPreconditionError).join('\n')
+    throw new Error(`Cannot launch remote agent:\n${reasons}`)
+  }
+  let bundleFailHint: string | undefined
+  const session = await teleportToRemote({
+    initialMessage: prompt,
+    description,
+    signal: toolUseContext.abortController.signal,
+    onBundleFail: message => {
+      bundleFailHint = message
+    },
+  })
+  if (!session) throw new Error(bundleFailHint ?? 'Failed to create remote session')
+  const { taskId, sessionId } = registerRemoteAgentTask({
+    remoteTaskType: 'remote-agent',
+    session: { id: session.id, title: session.title || description },
+    command: prompt,
+    context: toolUseContext,
+    toolUseId: toolUseContext.toolUseId,
+  })
+  const remoteResult: RemoteLaunchedOutput = {
+    status: 'remote_launched',
+    taskId,
+    sessionUrl: getRemoteTaskSessionUrl(sessionId),
+    description,
+    prompt,
+    outputFile: getTaskOutputPath(taskId),
+  }
+  return { data: remoteResult }
+}