subtask_run

Overview

Spawns a subtask with isolated context. Optionally specify an agent to use for the subtask. Subtask runs until completion, then returns results.

Availability

• Tasks: ✓ Available
• Subtasks: ✗ Not available (prevents infinite delegation)

Signature

 subtask_run(prompt: string, agent_id?: string) 

Parameters

Returns

Subtask results and completion status.

Behavior

• Spawns a subtask with isolated context
• If agent_id is omitted, subtask uses current scope capabilities
• If agent_id is specified, subtask uses that agent’s capabilities
• Subtask runs until completion, then returns results
• Subtasks cannot spawn additional subtasks (prevents infinite delegation)
• Subtasks cannot ask user questions (prevents blocking)

Example Usage

 // Spawn subtask with current scope
subtask_run("Analyze the error logs and identify the root cause")

// Spawn subtask with specific agent
subtask_run(
  "Review the pull request for code quality issues",
  "code-review-agent"
)

// Parallel subtasks for independent work
subtask_run("Deploy to staging environment")
subtask_run("Run integration tests") 

Use Cases

Parallel Execution

Spawn multiple subtasks for independent work that can run in parallel:

 subtask_run("Analyze inventory levels across all warehouses")
subtask_run("Fetch pending customer orders from Shopify")
subtask_run("Check shipping carrier delivery status") 

Specialized Execution

Delegate work to specialized agents:

 // Use agent search to find specialists
const agents = agent_search("code review")

// Spawn subtask with specialist
subtask_run("Review this pull request", agents[0].agent_id) 

Isolated Context

Create isolated context for focused work without cluttering main task:

 subtask_run("Generate a detailed technical report on the performance bottlenecks") 

Related

• agent_search - Find agents for subtasks
• Built-in Tools Overview