task-bg

name: task-bg description: Launch and manage background tasks for parallel droid execution using background-manager.py. Factory Droid has no native run_in_background, so this uses manual Python-based background management.

<Use_When>

• Need to run a droid task in the background while continuing other work
• User says "background", "task-bg", "run in background"
• Long-running operations (builds, test suites, large refactors)
• Multiple independent tasks that should run concurrently
• Used internally by ultrawork and ralph for parallel droid orchestration </Use_When>

<Do_Not_Use_When>

• Quick operations that complete in seconds -- run directly
• Tasks that need interactive feedback -- run in foreground
• For full parallel orchestration -- use ultrawork which manages task-bg internally </Do_Not_Use_When>

<What_You_MUST_Do>

1. PARSE - Extract description, prompt, and droid selection
2. LAUNCH - Run python3 hooks/background-manager.py launch ...
3. TRACK - Task is recorded in ~/.factory/.omd/background-tasks/
4. MONITOR - Use list for summary or status <id> for specific task
5. COLLECT - Use output <id> to read stdout/stderr
6. REPORT - Summary of all background task outcomes </What_You_MUST_Do>

<What_You_MUST_NOT_Do>

1. DO NOT run quick operations in background
2. DO NOT forget to collect results
3. DO NOT skip cleanup of completed tasks
4. DO NOT use for tasks needing interactive feedback </What_You_MUST_NOT_Do>

<Why_Manual_Python> Factory Droid CLI does not support run_in_background: true like some other platforms. Instead, we use background-manager.py which:

• Executes droid exec --auto <autonomy> -- "<prompt>" as a background process
• Tracks tasks in ~/.factory/.omd/background-tasks/ as JSON files (task state) and .out files (output)
• Provides CLI commands: launch, complete, status, output, list, prune, cleanup, hook-complete
• Integrates with the SubagentStop hook via hook-complete for automatic completion tracking </Why_Manual_Python>

<Background_Manager_CLI>

Launch a task

python3 hooks/background-manager.py launch "<description>" "<prompt>" <droid> <parent_session_id> [autonomy_level] [model]

• description: Short task label (3-5 words)
• prompt: Full task instructions for the droid
• droid: Droid name (e.g., executor-med, explorer)
• parent_session_id: Current session ID (use "main" if unknown)
• autonomy_level: low | medium (default) | high
• model: Optional model override

Examples

# Search task (low autonomy - read only)
python3 hooks/background-manager.py launch "Find auth patterns" "Find all authentication implementations in src/" explorer "main" low

# Implementation task (medium autonomy - default)
python3 hooks/background-manager.py launch "Fix API errors" "Fix all validation errors in src/api/" executor-med "main" medium

# Complex task (high autonomy + model override)
python3 hooks/background-manager.py launch "Refactor auth" "Refactor auth module to support OAuth2" executor-high "main" high opus

# Multiple tasks in parallel
python3 hooks/background-manager.py launch "Fix auth" "Fix auth module errors" executor-med "main"
python3 hooks/background-manager.py launch "Fix API" "Fix API route errors" executor-med "main"
python3 hooks/background-manager.py launch "Fix UI" "Fix frontend type errors" executor-med "main"

Monitor tasks

# List all tasks with status summary (total, running, queued, completed, error)
python3 hooks/background-manager.py list

# Check specific task status (returns full task JSON)
python3 hooks/background-manager.py status <task_id>

# Get task stdout/stderr output from .out file
python3 hooks/background-manager.py output <task_id>

Complete a task manually

python3 hooks/background-manager.py complete <task_id> "<result>" [error_message]

Cleanup

# Prune stale/timed-out tasks (marks as ERROR, respects TTL of 30 min)
python3 hooks/background-manager.py prune

# Reset all tasks from memory (does NOT delete .json files)
python3 hooks/background-manager.py cleanup

Hook integration (internal - called by SubagentStop hook)

# Reads session_id from stdin JSON, finds matching task, marks complete with transcript result
python3 hooks/background-manager.py hook-complete

</Background_Manager_CLI>

<Autonomy_Levels>

<Available_Droids>

<Task_Lifecycle>

launch() -> RUNNING -> complete() -> COMPLETED
                    -> error      -> ERROR
                    -> prune()    -> ERROR (timeout/stale)

Files per task:

• ~/.factory/.omd/background-tasks/<task_id>.json - Task state (status, progress, metadata)
• ~/.factory/.omd/background-tasks/<task_id>.out - Stdout/stderr from droid exec

Hook: SubagentStop event calls background-manager.py hook-complete which reads transcript and auto-completes the matching task. </Task_Lifecycle>

<Output_Format>

Background Tasks

Completed

• Task: [result summary]

Still Running

• </Output_Format>